שימוש ב-Firestore API בארכיטקטורת REST

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

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

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

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

אימות והרשאה

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

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

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

עבודה עם אסימוני מזהה של Firebase

יש שתי דרכים להשיג אסימון מזהה של Firebase:

אפשר לשלוף אסימון מזהה של משתמש ב-Firebase כדי לשלוח בקשות בשם המשתמש.

בבקשות שאומתו באמצעות טוקן מזהה של Firebase ובבקשות שלא אומתו, Firestore משתמש בכללי האבטחה של Firestore כדי לקבוע אם הבקשה מורשית.

עבודה עם אסימוני OAuth 2.0 של Google Identity

אפשר ליצור אסימון גישה באמצעות חשבון שירות עם ספריית לקוח של Google API או באמצעות השלבים שמתוארים במאמר שימוש ב-OAuth 2.0 לאפליקציות שרת-אל-שרת. אפשר גם ליצור אסימון באמצעות כלי שורת הפקודה gcloud והפקודה gcloud auth application-default print-access-token.

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

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

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

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

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

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

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

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

קודי שגיאה

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

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

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

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

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