השתמש ב-Cloud Firestore REST API

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

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

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

אם אתה משתמש בשפה הנתמכת ב-gRPC , שקול להשתמש ב- RPC API ולא ב-REST 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 כדי לקבוע אם בקשה מאושרת.

עבודה עם אסימוני 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

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

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

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

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

ביצוע שיחות REST

כל נקודות הקצה של REST API קיימות תחת כתובת האתר הבסיסית https://firestore.googleapis.com/v1/ .

כדי ליצור נתיב למסמך עם המזהה LA cities האיסוף תחת הפרויקט YOUR_PROJECT_ID , תשתמש במבנה הבא.

/projects/YOUR_PROJECT_ID/databases/(default)/documents/cities/LA

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

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

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

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