הדרך הקלה ביותר להשתמש ב-Cloud Firestore היא להשתמש באחת מספריות הלקוח הילידיות, אבל יש מצבים שבהם כדאי לבצע קריאה ישירה ל-API ל-REST.
API ל-REST יכול להועיל בתרחישים הבאים:
- גישה אל Cloud Firestore מסביבה מוגבלת במשאבים, כמו אינטרנט של מכשיר דברים (IoT), שבו פועל לקוח שלם היא אינה אפשרית.
- אוטומציה של ניהול מסדי נתונים או אחזור של מטא-נתונים מפורטים של מסדי נתונים.
אם אתם משתמשים בשפה נתמכת של gRPC, כדאי לכם להשתמש בRPC API במקום ב-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 Authentication API ל-REST
- אחזור אסימון מזהה של משתמש ב-Firebase מתוך Firebase Authentication SDK.
על ידי אחזור אסימון מזהה של משתמש ב-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
אם אתם מאמתים את הבקשות באמצעות חשבון שירות וזהות Google אסימון OAuth 2.0, 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
הדרך הטובה ביותר להתחיל להתנסות ב-API ל-REST היא להשתמש API Explorer, שיוצר את Google Identity באופן אוטומטי אסימוני OAuth 2.0 מאפשרים לכם לבחון את ה-API.
שיטות
בהמשך מתוארים תיאורים קצרים של שתי קבוצות השיטות החשובות ביותר. לקבלת תמונה מלאה תוכלו לעיין בחומר העזר בנושא API ל-REST או להשתמש ב-API Explorer.
v1.projects.databases.documents
לבצע פעולות CRUD על מסמכים, בדומה לאלה המתוארות הוספת נתונים או קבלת מדריכים לנתונים.
v1.projects.databases.collectionGroups.indexes
ביצוע פעולות על אינדקסים, כגון יצירת אינדקסים חדשים והשבתה של אינדקס קיים או לפרט את כל המדדים הנוכחיים. שימושי לאוטומציה של מבנה הנתונים או סנכרון אינדקסים בין פרויקטים.
היא מאפשרת גם אחזור של מטא-נתונים של מסמכים, כמו רשימת כל השדות והאוספים המשניים של מסמך נתון.
קודי שגיאה
כשבקשת Cloud Firestore מצליחה,
Cloud Firestore API מחזיר קוד סטטוס HTTP 200 OK
הנתונים המבוקשים. כשבקשה נכשלת, ה-API של Cloud Firestore מחזיר
קוד הסטטוס 4xx
או 5xx
של HTTP, ותגובה עם מידע על
השגיאה.
בטבלה הבאה מפורטות הפעולות המומלצות לכל קוד שגיאה. הקודים האלה חלים לממשק ה-API של Cloud Firestore ל-REST ול-RPC. Cloud Firestore יכול להיות שערכות SDK וספריות לקוח לא יחזירו את אותם קודי שגיאה.
קוד שגיאה קנוני | תיאור | מה מומלץ לעשות? |
---|---|---|
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). |