שימוש ב-Cloud Firestore REST API

הדרך הכי קלה להשתמש ב-Cloud Firestore היא באמצעות אחת מספריות הלקוח המקוריות, אבל יש מצבים שבהם כדאי לקרוא ישירות ל-REST API.

ה-API ל-REST יכול לעזור בתרחישי השימוש הבאים:

  • גישה אל Cloud Firestore מסביבה עם משאבים מוגבלים, כמו מכשיר IoT, שבה אי אפשר להריץ ספריית לקוח מלאה.
  • אוטומציה של ניהול מסד נתונים או אחזור של מטא-נתונים מפורטים של מסד נתונים.

אם אתם משתמשים בשפה שתומכת ב-gRPC, כדאי להשתמש ב-RPC API ולא ב-REST API.

אימות והרשאה

לצורך אימות, ה-API ל-REST‏ Cloud Firestore מקבל אסימון מזהה מסוג Firebase Authentication או אסימון מסוג Google Identity OAuth 2.0. הטוקן שסיפקת משפיע על ההרשאה של הבקשה שלך:

  • משתמשים באסימוני מזהים של Firebase כדי לאמת בקשות ממשתמשי האפליקציה. במקרה של בקשות כאלה, Cloud Firestore משתמש ב-Cloud Firestore Security Rules כדי לקבוע אם הבקשה מורשית.

  • משתמשים באסימון OAuth 2.0 של Google Identity ובחשבון שירות כדי לאמת בקשות מהאפליקציה, כמו בקשות לניהול מסד נתונים. במקרה של בקשות כאלה, Cloud Firestore משתמש בניהול זהויות והרשאות גישה (IAM) כדי לקבוע אם הבקשה מורשית.

עבודה עם אסימוני מזהה של Firebase

יש שתי דרכים להשיג אסימון מזהה של Firebase:

אפשר לשלוח בקשות בשם המשתמש באמצעות אחזור של אסימון מזהה של Firebase.

בבקשות שאומתו באמצעות אסימון מזהה של Firebase ובבקשות שלא אומתו, Cloud Firestore משתמש בCloud Firestore Security Rules כדי לקבוע אם הבקשה מורשית.

עבודה עם אסימוני OAuth 2.0 של Google Identity

אפשר ליצור אסימון גישה באמצעות חשבון שירות עם ספריית לקוח של Google API או באמצעות השלבים שמפורטים במאמר שימוש ב-OAuth 2.0 לאפליקציות שרת-אל-שרת. אפשר גם ליצור אסימון באמצעות כלי שורת הפקודה gcloud והפקודה gcloud auth application-default print-access-token.

לאסימון הזה צריכה להיות ההרשאה הבאה כדי לשלוח בקשות אל Cloud Firestore REST API:

  • https://www.googleapis.com/auth/datastore

אם אתם מאמתים את הבקשות שלכם באמצעות חשבון שירות ואסימון OAuth 2.0 של Google Identity, ‏ Cloud Firestore מניח שהבקשות שלכם פועלות בשם האפליקציה ולא בשם משתמש פרטי. ‫Cloud Firestore מאפשרת להתעלם מכללי האבטחה שלכם בבקשות האלה. במקום זאת, Cloud Firestore משתמש ב-IAM כדי לקבוע אם בקשה מסוימת מורשית.

אפשר לשלוט בהרשאות הגישה של חשבונות שירות על ידי הקצאה של Cloud Firestore תפקידי IAM.

אימות באמצעות טוקן גישה

אחרי שמקבלים אסימון מזהה של Firebase או אסימון OAuth 2.0 של Google Identity, מעבירים אותו לנקודות הקצה של Cloud Firestore ככותרת Authorization שמוגדרת ל-Bearer {YOUR_TOKEN}.

ביצוע קריאות REST

כל נקודות הקצה של ה-API ל-REST נמצאות תחת כתובת ה-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, שמייצר באופן אוטומטי אסימוני OAuth 2.0 של Google Identity ומאפשר לכם לבדוק את ה-API.

Methods

בהמשך מופיעים תיאורים קצרים של שתי קבוצות השיטות החשובות ביותר. רשימה מלאה זמינה במאמר REST API reference או ב-API Explorer.

v1.projects.databases.documents

ביצוע פעולות CRUD במסמכים, בדומה לאלה שמפורטות במדריכים הוספת נתונים או קבלת נתונים.

v1.projects.databases.collectionGroups.indexes

לבצע פעולות באינדקסים, כמו יצירת אינדקסים חדשים, השבתת אינדקס קיים או הצגת רשימה של כל האינדקסים הנוכחיים. האפשרות הזו שימושית לאוטומציה של העברות של מבני נתונים או לסנכרון של אינדקסים בין פרויקטים.

היא מאפשרת גם אחזור של מטא-נתונים של מסמכים, כמו רשימת כל השדות ואוספי המשנה של מסמך נתון.

קודי שגיאה

כשבקשת Cloud Firestore מצליחה, API‏ Cloud Firestore מחזיר קוד סטטוס 200 OK של HTTP ואת הנתונים המבוקשים. אם בקשה נכשלת, Cloud Firestore API מחזיר קוד סטטוס HTTP 4xx או 5xx ותגובה עם מידע על השגיאה.

בטבלה הבאה מפורטות פעולות מומלצות לכל קוד שגיאה. הקודים האלה רלוונטיים ל-Cloud Firestore REST ול-RPC APIs. יכול להיות שCloud Firestoreספריות הלקוח וערכות ה-SDK לא יחזירו את אותם קודי שגיאה.

קוד שגיאה קנוני תיאור מה מומלץ לעשות?
ABORTED הבקשה סותרת בקשה אחרת. אם מדובר בהתחייבות לא טרנזקציונית:
צריך לנסות שוב לשלוח את הבקשה או לשנות את מבנה מודל הנתונים כדי לצמצם את התחרות על המשאבים.

אם מדובר בבקשות בטרנזקציה:
צריך לנסות שוב לשלוח את הטרנזקציה כולה או לשנות את מבנה מודל הנתונים כדי לצמצם את התחרות על המשאבים.
ALREADY_EXISTS הבקשה ניסתה ליצור מסמך שכבר קיים. אל תנסו שוב בלי לפתור את הבעיה.
DEADLINE_EXCEEDED השרת Cloud Firestore שמטפל בבקשה חרג מהמועד האחרון. צריך לנסות שוב באמצעות השהיה מעריכית לפני ניסיון חוזר (exponential backoff).
FAILED_PRECONDITION הבקשה לא עמדה באחד מהתנאים המוקדמים שלה. לדוגמה, יכול להיות שבקשת שאילתה תדרוש אינדקס שעדיין לא הוגדר. התנאי המוקדם שנכשל מופיע בשדה ההודעה בתגובה לשגיאה. אל תנסו שוב בלי לפתור את הבעיה.
INTERNAL השרת Cloud Firestore החזיר שגיאה. אין לנסות לשלוח את הבקשה הזו יותר מפעם אחת.
INVALID_ARGUMENT פרמטר של בקשה כולל ערך לא תקין. הערך הלא תקין מופיע בשדה ההודעה בתגובה לשגיאה. אל תנסו שוב בלי לפתור את הבעיה.
NOT_FOUND הבקשה ניסתה לעדכן מסמך שלא קיים. אל תנסו שוב בלי לפתור את הבעיה.
PERMISSION_DENIED למשתמש אין הרשאה לשלוח את הבקשה הזו. אל תנסו שוב בלי לפתור את הבעיה.
RESOURCE_EXHAUSTED הפרויקט חרג מהמכסה שלו או מהקיבולת של האזור או של מספר האזורים. מוודאים שלא חרגתם מהמכסה של הפרויקט. אם חרגתם ממכסת הפרויקט, אל תנסו שוב בלי לפתור את הבעיה.

אחרת, נסו שוב עם נסיגה אקספוננציאלית.
UNAUTHENTICATED הבקשה לא כללה פרטי כניסה תקפים לאימות. אל תנסו שוב בלי לפתור את הבעיה.
UNAVAILABLE השרת Cloud Firestore החזיר שגיאה. צריך לנסות שוב באמצעות השהיה מעריכית לפני ניסיון חוזר (exponential backoff).