שימוש ב-Cloud Firestore REST API

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

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

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

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

אימות והרשאה

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

  • להשתמש באסימונים מזהים של 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

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

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

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

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

שיטות

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

v1.projects.databases.documents

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

v1.projects.databases.collectionGroups.indexes

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

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

קודי שגיאה

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

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

קוד שגיאה קנוני תיאור מה מומלץ לעשות?
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).