في حين أن أسهل طريقة لاستخدام Cloud Firestore هي هناك بعض الحالات التي يكون من المفيد فيها باستدعاء واجهة برمجة تطبيقات REST مباشرة.
يمكن أن تكون REST API مفيدة في حالات الاستخدام التالية:
- يتيح لك الوصول إلى Cloud Firestore من بيئة محدودة الموارد مثل جهاز إنترنت الأشياء (IoT)، حيث يتم تشغيل برنامج كامل المكتبة غير ممكنة.
- أتمتة إدارة قاعدة البيانات أو استرداد البيانات الوصفية التفصيلية لقاعدة البيانات.
إذا كنت تستخدم اللغة المعتمدة من gRPC، ننصحك باستخدام RPC API بدلاً من REST API.
المصادقة والترخيص
بالنسبة إلى المصادقة، تقبل واجهة برمجة التطبيقات 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 باستخدام واجهة برمجة التطبيقات REST لمصادقة Firebase
- استرداد الرمز المميز لأحد المستخدمين لرقم تعريف Firebase من حزمة SDK لمصادقة 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:
https://www.googleapis.com/auth/datastore
في حال مصادقة طلباتك باستخدام حساب خدمة وهوية Google رمز 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 هي استخدام مستكشف واجهات برمجة التطبيقات الذي ينشئ هوية Google تلقائيًا رموز OAuth 2.0 المميزة ويسمح لك بفحص واجهة برمجة التطبيقات.
الطُرق
في ما يلي أوصاف موجزة لأهم مجموعتي طرق. للحصول على يمكنك الاطّلاع على مرجع REST API أو استخدام مستكشف واجهات برمجة التطبيقات.
v1.projects.databases.documents
إجراء عمليات CRUD على المستندات، على غرار تلك الموضحة في إضافة بيانات أو الحصول على أدلة حول البيانات
v1.projects.databases.collectionGroups.indexes
تنفيذ إجراءات على الفهارس، مثل إنشاء فهارس جديدة أو إيقاف فهرس أو إدراج جميع الفهارس الحالية. مفيد لأتمتة هيكل البيانات أو ترحيلات أو مزامنة الفهارس بين المشروعات.
يتيح أيضًا استرجاع البيانات الوصفية للمستند، مثل قائمة جميع الحقول والمجموعات الفرعية لمستند معين.
رموز الأخطاء
عند نجاح طلب Cloud Firestore،
تعرض واجهة برمجة التطبيقات Cloud Firestore رمز حالة HTTP 200 OK
البيانات المطلوبة. عند تعذّر تنفيذ طلب، تعرض واجهة برمجة التطبيقات Cloud Firestore API
رمز حالة 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 خطأً. | أعِد المحاولة باستخدام خوارزمية الرقود الأسي الثنائي. |