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

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

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

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

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

المصادقة والتفويض

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

استخدام رموز تعريف Firebase

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

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

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

استخدام رموز OAuth 2.0 من "هوية Google"

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

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

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

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

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

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

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

الإجراءات

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

v1.projects.databases.documents

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

v1.projects.databases.collectionGroups.indexes

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

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

رموز الخطأ

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

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