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

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

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

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

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

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

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

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

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

العمل مع الرموز المميزة لمعرف Firebase

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

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

إذا قمت بمصادقة طلباتك باستخدام حساب خدمة ورمز Google Identity OAuth 2.0 المميز، فإن Cloud Firestore يفترض أن طلباتك تعمل نيابةً عن تطبيقك بدلاً من مستخدم فردي. يسمح Cloud Firestore لهذه الطلبات بتجاهل قواعد الأمان الخاصة بك. وبدلاً من ذلك، يستخدم Cloud Firestore IAM لتحديد ما إذا كان الطلب معتمدًا أم لا.

يمكنك التحكم في أذونات الوصول لحسابات الخدمة عن طريق تعيين أدوار Cloud Firestore IAM .

المصادقة باستخدام رمز الوصول

بعد الحصول على رمز معرف Firebase أو رمز Google Identity OAuth 2.0، قم بتمريره إلى نقاط نهاية 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 هي استخدام API Explorer ، الذي يقوم تلقائيًا بإنشاء رموز Google Identity OAuth 2.0 المميزة ويسمح لك بفحص واجهة برمجة التطبيقات.

طُرق

وفيما يلي وصف موجز لمجموعتي الأساليب الأكثر أهمية. للحصول على قائمة كاملة، راجع مرجع REST API أو استخدم API Explorer .

v1.projects.databases.documents

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

v1.projects.databases.collectionGroups.indexes

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

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

رموز الخطأ

عندما ينجح طلب Cloud Firestore، تقوم Cloud Firestore API بإرجاع رمز حالة HTTP 200 OK والبيانات المطلوبة. عند فشل الطلب، تقوم Cloud Firestore API بإرجاع رمز حالة 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 خطأً. أعد المحاولة باستخدام التراجع الأسي.