استخدام واجهة برمجة تطبيقات 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 لتحديد ما إذا كان الطلب مُصادقًا عليه.
استخدِم رمزًا مميزًا من الإصدار 2.0 من OAuth في 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 الخاصة بـ Cloud Firestore:

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

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

استخدام واجهة برمجة تطبيقات Cloud Firestore REST تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.