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

درحالی‌که ساده‌ترین راه برای استفاده از Cloud Firestore استفاده از یکی از کتابخانه‌های کارخواه بومی است، در برخی شرایط مفید است که مستقیماً با REST API تماس بگیرید.

‫REST API می‌تواند برای موارد استفاده زیر مفید باشد:

  • دسترسی به Cloud Firestore از محیطی با منابع محدود، مانند دستگاه اینترنت اشیاء (IoT)، که در آن اجرای یک کتابخانه مشتری کامل امکان‌پذیر نیست.
  • خودکارسازی مدیریت پایگاه داده یا بازیابی فراداده‌های دقیق پایگاه داده.

اگر از زبان پشتیبانی‌شده gRPC استفاده می‌کنید، به‌جای REST API، استفاده از RPC API را مدنظر قرار دهید.

اصالت‌سنجی و صدور مجوز

برای اصالت‌سنجی، Cloud Firestore REST API یا یک Firebase Authentication کد شناسه یا یک Google Identity OAuth 2.0 کد را می‌پذیرد. نشانه‌ای که ارائه می‌دهید بر مجوز درخواستتان تأثیر می‌گذارد:

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

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

کار کردن با نشان‌های Firebase ID

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

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

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

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

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

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