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