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

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

במקרה של בקשות בטרנזקציה:
מנסים שוב לשלוח את כל הטרנזקציה או משנים את מבנה מודל הנתונים כדי לצמצם את התחרות על המשאבים.
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).