استخدام واجهة برمجة تطبيقات 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 لتحديد ما إذا كان الطلب مصرَّحًا به.

  • استخدِم رمز OAuth 2.0 المميز من 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.

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

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

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

يمكنك التحكّم في أذونات الوصول إلى حسابات الخدمة من خلال منح أدوار "إدارة الهوية وإمكانية الوصول" (IAM) في 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

نفِّذ عمليات CRUD على المستندات، مثل تلك الموضّحة في دليلَي إضافة البيانات أو الحصول على البيانات.

v1.projects.databases.collectionGroups.indexes

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

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

رموز الخطأ

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

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

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

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

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