على الرغم من أن أسهل طريقة لاستخدام 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 Authentication REST API .
- يمكنك استرداد رمز Firebase ID المميز للمستخدم من Firebase Authentication SDK .
من خلال استرداد رمز معرف 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 خطأً. | أعد المحاولة باستخدام التراجع الأسي. |