استفاده از Cloud Firestore REST API

درحالی‌که ساده‌ترین راه برای استفاده از 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 ID tokens برای اصالت‌سنجی درخواست‌های کاربران برنامه‌تان استفاده کنید. برای این درخواست‌ها، Cloud Firestore از Cloud Firestore Security Rules استفاده می‌کند تا تعیین کند که آیا درخواست مجاز است یا نه.

  • از یک توکن Google Identity OAuth 2.0 و یک حساب سرویس برای اصالت‌سنجی درخواست‌های برنامه‌تان، مانند درخواست‌های مدیریت پایگاه داده، استفاده کنید. برای این درخواست‌ها، Cloud Firestore از مدیریت هویت و دسترسی‌ها (IAM) استفاده می‌کند تا تعیین کند که آیا درخواست مجاز است یا نه.

کار کردن با توکن‌های شناسه Firebase

به دو روش می‌توانید یک شناسه Firebase دریافت کنید:

با بازیابی کردن کد Firebase ID کاربر، می‌توانید ازطرف کاربر درخواست ارسال کنید.

برای درخواست‌های اصالت‌سنجی‌شده با کد Firebase ID و برای درخواست‌های اصالت‌سنجی‌نشده، Cloud Firestore از Cloud Firestore Security Rules شما استفاده می‌کند تا تعیین کند که آیا درخواست مجاز است یا نه.

کار با کدهای 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 برای تعیین اینکه درخواست مجاز است یا نه استفاده می‌کند.

می‌توانید با اختصاص دادن نقش‌های IAM Cloud Firestore، اجازه‌های دسترسی حساب‌های سرویس را کنترل کنید.

اصالت‌سنجی با کد دسترسی

پس‌از دریافت کد Firebase ID یا کد Google Identity OAuth 2.0، آن را به‌عنوان سرصفحه Authorization تنظیم‌شده روی Bearer {YOUR_TOKEN} به نقاط پایانی Cloud Firestore ارسال کنید.

برقراری تماس‌های REST

همه نقاط پایانی REST API تحت نشانی وب پایه https://firestore.googleapis.com/v1/ وجود دارند.

برای ایجاد مسیر به سندی با شناسه LA در مجموعه cities تحت پروژه YOUR_PROJECT_ID، از ساختار زیر استفاده می‌کنید.

/projects/YOUR_PROJECT_ID/databases/(default)/documents/cities/LA

برای تعامل با این مسیر، آن را با نشانی وب پایه میانای برنامه‌سازی کاربردی ترکیب کنید.

https://firestore.googleapis.com/v1/projects/YOUR_PROJECT_ID/databases/(default)/documents/cities/LA

بهترین راه برای شروع آزمایش با REST API استفاده از API Explorer است که به‌طور خودکار نشان‌های OAuth 2.0 «هویت‌سنجی Google» را تولید می‌کند و به شما امکان می‌دهد API را بررسی کنید.

روش‌ها

در زیر شرح مختصری از دو گروه روش مهم آورده شده است. برای فهرست کامل، مرجع 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 API اعمال می‌شود. 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 خطایی برگرداند. بااستفاده از عقب‌گرد نمایی دوباره امتحان کنید.