از 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 استفاده می‌کند تا مشخص کند آیا درخواستی مجاز است یا خیر.
از یک توکن Google Identity OAuth 2.0 و یک حساب سرویس برای احراز هویت درخواست های برنامه خود، مانند درخواست های مدیریت پایگاه داده استفاده کنید. برای این درخواست‌ها، Cloud Firestore از مدیریت هویت و دسترسی (IAM) استفاده می‌کند تا تعیین کند آیا درخواستی مجاز است یا خیر.

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

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

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

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

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