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

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

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

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

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

المصادقة والترخيص

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

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

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

العمل باستخدام الرموز المميّزة لرقم تعريف Firebase

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

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

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

العمل باستخدام رموز 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

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

الطُرق

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