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

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

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

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

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

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

للمصادقة، تقبل واجهة برمجة التطبيقات Cloud Firestore REST إما الرمز المميّز لمعرّف 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 أو باتّباع الخطوات الواردة في مقالة استخدام بروتوكول 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، يجب تمريره إلى نقاط نهاية 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. قد لا تعرض 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 خطأ. يعيد المحاولة باستخدام خوارزمية الرقود الأسي الثنائي.