استخدام واجهة برمجة تطبيقات Cloud Firestore REST

على الرغم من أنّ أسهل طريقة لاستخدام Cloud Firestore هي استخدام إحدى مكتبات العميل المضمّنة، إلا أنّ هناك بعض الحالات التي يكون فيها من المفيد طلب بيانات من واجهة برمجة التطبيقات REST API مباشرةً.

يمكن أن تكون واجهة برمجة التطبيقات REST مفيدة في حالات الاستخدام التالية:

  • الوصول إلى Cloud Firestore من بيئة محدودة الموارد مثل جهاز إنترنت الأشياء (IoT)، حيث يتم تشغيل برنامج كامل المكتبة غير ممكنة.
  • أتمتة إدارة قاعدة البيانات أو استرداد البيانات الوصفية التفصيلية لقاعدة البيانات.

إذا كنت تستخدم اللغة المعتمدة من gRPC، ننصحك باستخدام RPC API بدلاً من REST API.

المصادقة والترخيص

للمصادقة، تقبل Cloud Firestore REST API إما رمز تعريف Firebase Authentication أو رمز Google Identity OAuth 2.0. الرمز المميّز الذي تقدّمه في تفويض طلبك:

  • استخدِم الرموز المميّزة لمعرّف Firebase لمصادقة الطلبات الواردة من مستخدمي التطبيق. بالنسبة إلى هذه الطلبات، يستخدم Cloud Firestore Cloud Firestore Security Rules لتحديد ما إذا كان الطلب معتمد.

  • استخدام رمز مميّز لـ Google Identity OAuth 2.0 لحساب الخدمة لمصادقة الطلبات الواردة من تطبيق، مثل طلبات إدارة قاعدة البيانات. بالنسبة لهذه الطلبات، استخدامان (Cloud Firestore) إدارة الهوية والوصول (IAM) لتحديد ما إذا كان طلبه مُصرح به.

العمل باستخدام الرموز المميّزة لرقم تعريف Firebase

يمكنك الحصول على رمز مميز لرقم تعريف Firebase بطريقتين:

من خلال استرداد الرمز المميز لمعرّف Firebase للمستخدم، يمكنك تقديم طلبات نيابةً عن المستخدم.

للطلبات التي تمت مصادقتها باستخدام رمز مميَّز لمعرّف Firebase وللطلبات التي لم تتم مصادقتها الطلبات، يستخدم Cloud Firestore Cloud Firestore Security Rules لتحديد ما إذا كان الطلب مخوّل.

العمل باستخدام رموز Google Identity OAuth 2.0 المميزة

يمكنك إنشاء رمز دخول باستخدام حساب خدمة مع مكتبة برامج Google API أو باتباع الخطوات الواردة في استخدام OAuth 2.0 لتطبيقات خادم إلى خادم إِنْتَ أيضًا إنشاء رمز مميّز باستخدام أداة سطر الأوامر gcloud الأمر gcloud auth application-default print-access-token.

يجب أن يكون لهذا الرمز المميّز النطاق التالي لإرسال الطلبات إلى واجهة برمجة التطبيقات Cloud Firestore REST API:

  • https://www.googleapis.com/auth/datastore

في حال مصادقة طلباتك باستخدام حساب خدمة وهوية Google رمز OAuth 2.0 المميز، يفترض Cloud Firestore أن طلباتك تتصرف نيابةً تطبيقك بدلاً من مستخدم فردي. سماح Cloud Firestore هذه الطلبات لتجاهل قواعد الأمان. بدلاً من ذلك، Cloud Firestore يستخدِم إدارة الهوية وإمكانية الوصول لتحديد ما إذا كان الطلب مصرَّحًا به.

يمكنك التحكّم في أذونات الوصول لحسابات الخدمة من خلال تخصيص Cloud Firestore دور لإدارة الهوية وإمكانية الوصول:

المصادقة باستخدام رمز دخول

بعد الحصول على رمز تعريف Firebase أو رمز بروتوكول OAuth 2.0 لمعرّف Google، يجب تمريره إلى نقاط نهاية Cloud Firestore كعنوان Authorization تم ضبطه على Bearer {YOUR_TOKEN}.

إجراء مكالمات REST

تتوفّر جميع نقاط نهاية REST API ضمن عنوان URL الأساسي https://firestore.googleapis.com/v1/.

لإنشاء مسار إلى مستند باستخدام رقم التعريف LA في المجموعة cities ضمن المشروع YOUR_PROJECT_ID، يمكنك استخدام البنية التالية.

/projects/YOUR_PROJECT_ID/databases/(default)/documents/cities/LA

للتفاعل مع هذا المسار، يجب دمجه مع عنوان URL الأساسي لواجهة برمجة التطبيقات.

https://firestore.googleapis.com/v1/projects/YOUR_PROJECT_ID/databases/(default)/documents/cities/LA

إن أفضل طريقة لبدء تجربة واجهة برمجة تطبيقات REST هي استخدام مستكشف واجهات برمجة التطبيقات الذي ينشئ هوية Google تلقائيًا رموز OAuth 2.0 المميزة ويسمح لك بفحص واجهة برمجة التطبيقات.

الطُرق

في ما يلي أوصاف موجزة لمجموعة الطريقتَين الأكثر أهمّية. للحصول على يمكنك الاطّلاع على مرجع REST API أو استخدام مستكشف واجهات برمجة التطبيقات.

v1.projects.databases.documents

إجراء عمليات CRUD على المستندات، على غرار تلك الموضحة في إضافة بيانات أو الحصول على أدلة حول البيانات

v1.projects.databases.collectionGroups.indexes

تنفيذ إجراءات على الفهارس، مثل إنشاء فهارس جديدة أو إيقاف فهرس أو إدراج جميع الفهارس الحالية. مفيد لأتمتة هيكل البيانات أو ترحيلات أو مزامنة الفهارس بين المشروعات.

تتيح هذه الميزة أيضًا استرداد البيانات الوصفية للمستند، مثل قائمة جميع الحقول والمجموعات الفرعية لمستند معيّن.

رموز الأخطاء

عند نجاح طلب Cloud Firestore، تعرِض Cloud Firestore API رمز حالة HTTP‏ 200 OK وال data المطلوبة. عند تعذّر تنفيذ طلب، تعرض واجهة برمجة التطبيقات Cloud Firestore رمز حالة HTTP 4xx أو 5xx واستجابة تتضمّن معلومات عن الخطأ.

يسرد الجدول التالي الإجراءات المقترَحة لكل رمز خطأ. تنطبق هذه الرموز. إلى واجهات برمجة تطبيقات REST وRPC في Cloud Firestore. يعمل Cloud Firestore وقد لا تعرض حِزم تطوير البرامج (SDK) ومكتبات العملاء رموز الخطأ نفسها هذه.

رمز الخطأ الأساسي الوصف الإجراء المقترَح
ABORTED تعارض الطلب مع طلب آخر. بالنسبة إلى التسليم غير المرتبط بالمعاملات:
حاوِل إرسال الطلب أو أعِد تنظيم نموذج البيانات لتقليل التضارب.

بالنسبة إلى الطلبات في معاملة:
عليك إعادة محاولة إجراء العملية بأكملها أو إعادة هيكلة نموذج البيانات لتقليل التضارب.
ALREADY_EXISTS حاول الطلب إنشاء مستند موجود من قبل. لا تُعد المحاولة بدون حلّ المشكلة.
DEADLINE_EXCEEDED تجاوز خادم Cloud Firestore الذي يعالج الطلب الموعد النهائي. أعِد المحاولة باستخدام خوارزمية الرقود الأسي الثنائي.
FAILED_PRECONDITION لم يستوفِ الطلب أحد الشروط المسبقة. على سبيل المثال، قد يتطلب طلب البحث فهرسًا لم يتم تحديده بعد. اطّلِع على حقل الرسالة في استجابة الخطأ للحالة المسبقة التي تعذّر إكمالها. يُرجى عدم إعادة المحاولة بدون حل المشكلة.
INTERNAL عرَضَ خادم "Cloud Firestore" خطأً. لا تعِد محاولة تنفيذ هذا الطلب أكثر من مرة.
INVALID_ARGUMENT تحتوي معلَمة الطلب على قيمة غير صالحة. راجِع حقل الرسالة في استجابة الخطأ للقيمة غير الصالحة. لا تُعد المحاولة بدون حلّ المشكلة.
NOT_FOUND حاول الطلب تعديل مستند غير موجود. يُرجى عدم إعادة المحاولة بدون حل المشكلة.
PERMISSION_DENIED غير مسموح للمستخدِم بإرسال هذا الطلب. يُرجى عدم إعادة المحاولة بدون حل المشكلة.
RESOURCE_EXHAUSTED تجاوز المشروع حصته أو سعة المنطقة/المناطق المتعددة. تحقّق من عدم تجاوز حصة المشروع. في حال تجاوز الحصة المحدَّدة للمشروع، يُرجى عدم إعادة المحاولة بدون حل المشكلة.

وإلا يُرجى إعادة المحاولة باستخدام خوارزمية الرقود الأسي.
UNAUTHENTICATED لم يتضمن الطلب بيانات اعتماد مصادقة صالحة. لا تُعد المحاولة بدون حلّ المشكلة.
UNAVAILABLE عرَض خادم Cloud Firestore خطأ. يعيد المحاولة باستخدام خوارزمية الرقود الأسي الثنائي.