از Cloud Firestore REST API استفاده کنید

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

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

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

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

احراز هویت و مجوز

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

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

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

کار با توکن های Firebase ID

شما می توانید به دو روش به یک نشانه Firebase ID دست پیدا کنید:

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

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

کار با توکن های Google Identity OAuth 2.0

می‌توانید با استفاده از یک حساب سرویس با Google API Client Library یا با دنبال کردن مراحل استفاده از 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 ID یا یک نشانه Google Identity OAuth 2.0 به دست آوردید، آن را به عنوان یک سرصفحه Authorization تنظیم شده روی Bearer {YOUR_TOKEN} به نقاط پایانی Cloud Firestore ارسال کنید.

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

همه نقاط پایانی REST API در زیر URL اصلی https://firestore.googleapis.com/v1/ وجود دارند.

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

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

برای تعامل با این مسیر، آن را با URL پایه API ترکیب کنید.

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

بهترین راه برای شروع آزمایش با REST API استفاده از API Explorer است که به طور خودکار توکن های Google Identity OAuth 2.0 را تولید می کند و به شما امکان می دهد 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 و پاسخی حاوی اطلاعات مربوط به خطا را برمی‌گرداند.

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