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

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

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

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

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

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

برای احراز هویت، API REST Cloud Firestore یا توکن 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

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

برای تعامل با این مسیر، آن را با 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 با موفقیت انجام می‌شود، API Cloud Firestore یک کد وضعیت HTTP 200 OK و داده‌های درخواستی را برمی‌گرداند. وقتی درخواست با شکست مواجه می‌شود، API Cloud Firestore یک کد وضعیت HTTP 4xx یا 5xx و پاسخی حاوی اطلاعات خطا را برمی‌گرداند.

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

کد خطای متعارف توضیحات اقدام توصیه شده
ABORTED این درخواست با درخواست دیگری در تضاد بود. برای یک کامیت غیر تراکنشی:
درخواست را دوباره امتحان کنید یا مدل داده خود را برای کاهش تداخل، دوباره ساختاردهی کنید.

برای درخواست‌ها در یک تراکنش:
کل تراکنش را دوباره امتحان کنید یا مدل داده خود را برای کاهش تداخل، دوباره ساختاردهی کنید.
ALREADY_EXISTS این درخواست سعی در ایجاد سندی داشت که از قبل وجود دارد. بدون رفع مشکل دوباره امتحان نکنید.
DEADLINE_EXCEEDED سرور Cloud Firestore که به درخواست رسیدگی می‌کرد، از مهلت تعیین‌شده فراتر رفت. با استفاده از backoff نمایی دوباره امتحان کنید.
FAILED_PRECONDITION این درخواست یکی از پیش‌شرط‌های خود را برآورده نکرده است. برای مثال، یک درخواست پرس‌وجو ممکن است به شاخصی نیاز داشته باشد که هنوز تعریف نشده است. برای پیش‌شرط ناموفق، به فیلد پیام در پاسخ خطا مراجعه کنید. بدون رفع مشکل دوباره امتحان نکنید.
INTERNAL سرور Cloud Firestore خطایی را برگرداند. این درخواست را بیش از یک بار تکرار نکنید.
INVALID_ARGUMENT پارامتر درخواست شامل یک مقدار نامعتبر است. برای مشاهده مقدار نامعتبر، به فیلد پیام در پاسخ خطا مراجعه کنید. بدون رفع مشکل دوباره امتحان نکنید.
NOT_FOUND این درخواست سعی در به‌روزرسانی سندی داشت که وجود ندارد. بدون رفع مشکل دوباره امتحان نکنید.
PERMISSION_DENIED کاربر مجاز به انجام این درخواست نیست. بدون رفع مشکل دوباره امتحان نکنید.
RESOURCE_EXHAUSTED این پروژه یا از سهمیه خود یا از ظرفیت منطقه/چند منطقه فراتر رفته است. تأیید کنید که از سهمیه پروژه خود تجاوز نکرده‌اید . اگر از سهمیه پروژه تجاوز کرده‌اید، بدون رفع مشکل دوباره امتحان نکنید.

در غیر این صورت، با روش پس‌روی نمایی دوباره امتحان کنید.
UNAUTHENTICATED این درخواست شامل اطلاعات احراز هویت معتبر نبود. بدون رفع مشکل دوباره امتحان نکنید.
UNAVAILABLE سرور Cloud Firestore خطایی را برگرداند. با استفاده از backoff نمایی دوباره امتحان کنید.