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

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

يمكن أن تكون واجهة REST API مفيدة في حالات الاستخدام التالية:

  • الوصول إلى 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 لتحديد ما إذا كان الطلب مصادقًا عليه.

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

التعامل مع رموز التعريف في Firebase

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

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

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

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

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

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

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

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

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

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

بعد الحصول على رمز مميّز للمعرّف على Firebase أو رمز مميّز لبروتوكول OAuth 2.0 من Google Identity، مرِّره إلى نقاط نهاية 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 API هي استخدام مستكشف واجهات برمجة التطبيقات الذي ينشئ تلقائيًا رموز OAuth 2.0 المميزة لخدمة Google Identity ويتيح لك فحص واجهة برمجة التطبيقات.

الإجراءات

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

v1.projects.databases.documents

تنفيذ عمليات إنشاء وقراءة وتعديل وحذف على المستندات، على غرار العمليات الموضّحة في دليلَي إضافة البيانات أو الحصول على البيانات

v1.projects.databases.collectionGroups.indexes

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

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

رموز الخطأ

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

يسرد الجدول التالي الإجراءات المقترَحة لكل رمز خطأ. تنطبق هذه الرموز على واجهات برمجة التطبيقات Cloud Firestore REST وRPC. قد لا تعرض 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 خطأً. أعِد المحاولة باستخدام خوارزمية الرقود الأسي الثنائي.