בעוד שהדרך הקלה ביותר להשתמש ב-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 Authentication REST API .
- אחזר אסימון Firebase ID של משתמש מ-SDK לאימות Firebase .
על ידי אחזור אסימון 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 החזיר שגיאה. | נסה שוב באמצעות גיבוי אקספוננציאלי. |