درحالیکه سادهترین راه برای استفاده از 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 Authentication REST API، یک کد Firebase ID تولید کنید.
- بازیابی کردن کد Firebase ID کاربر از Firebase Authentication SDK.
با بازیابی کردن کد 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 خطایی برگرداند. | بااستفاده از عقبگرد نمایی دوباره امتحان کنید. |