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

  • يمكنك استخدام رمز مميز لـ 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 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 ضمن عنوان 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 أو استخدام مستكشف واجهة برمجة التطبيقات.

v1.projects.databases.documents

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

v1.projects.databases.collectionGroups.indexes

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

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

رموز الخطأ

عند نجاح طلب Cloud Firestore، تعرِض Cloud Firestore API رمز حالة 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 خطأ. يعيد المحاولة باستخدام خوارزمية الرقود الأسي الثنائي.