שימוש ב-Cloud Firestore REST API

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

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

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

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

אימות והרשאה

לצורך אימות, ה-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.

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

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

אם אתם מאמתים את הבקשות באמצעות חשבון שירות וזהות Google אסימון OAuth 2.0, 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

הדרך הטובה ביותר להתחיל להתנסות ב-API ל-REST היא להשתמש API Explorer, שיוצר את Google Identity באופן אוטומטי אסימוני OAuth 2.0 מאפשרים לכם לבחון את ה-API.

שיטות

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

v1.projects.databases.documents

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

v1.projects.databases.collectionGroups.indexes

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

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

קודי שגיאה

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

בטבלה הבאה מפורטות הפעולות המומלצות לכל קוד שגיאה. הקודים האלה חלים לממשק ה-API של Cloud Firestore ל-REST ול-RPC. 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 הפרויקט חרג מהמכסה שלו או מהקיבולת של אזור/מספר אזורים. מוודאים שלא חרגתם ממכסת הפרויקט. אם חרגת ממכסת הפרויקט, אין לנסות שוב בלי לפתור את הבעיה.

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