שימוש ב-Cloud Firestore REST API

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

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

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

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

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

Methods

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

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

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