טריגר https.onCall
עבור פונקציות ענן הוא טריגר HTTPS עם פורמט ספציפי לבקשה והתגובה. סעיף זה מספק מפרט עבור פורמטים של בקשת HTTPS ותגובה המשמשים את SDK של הלקוח כדי ליישם את ה-API. מידע זה עשוי להיות שימושי עבורך אם לא ניתן לעמוד בדרישות שלך באמצעות פלטפורמות אנדרואיד, אפל או ערכות פיתוח אינטרנט.
פורמט בקשה: כותרות
בקשת ה-HTTP לנקודת קצה טריגר הניתנת להתקשרות חייבת להיות POST
עם הכותרות הבאות:
- נדרש:
Content-Type: application/json
- אופציונלי
; charset=utf-8
מותר.
- אופציונלי
- אופציונלי:
Authorization: Bearer <token>
- אסימון משתמש מזהה Firebase Authentication עבור המשתמש המחובר שמבצע את הבקשה. הקצה העורפי מאמת אוטומטית את האסימון הזה והופך אותו לזמין
context
של המטפל . אם האסימון אינו תקף, הבקשה נדחית.
- אסימון משתמש מזהה Firebase Authentication עבור המשתמש המחובר שמבצע את הבקשה. הקצה העורפי מאמת אוטומטית את האסימון הזה והופך אותו לזמין
- אופציונלי:
Firebase-Instance-ID-Token: <iid>
- אסימון הרישום של FCM מ-SDK של לקוח Firebase. זה חייב להיות מחרוזת. זה זמין
context
של המטפל . הוא משמש למיקוד הודעות דחיפה.
- אסימון הרישום של FCM מ-SDK של לקוח Firebase. זה חייב להיות מחרוזת. זה זמין
- אופציונלי:
X-Firebase-AppCheck: <token>
- אסימון ה-Firebase App Check שסופק על ידי אפליקציית הלקוח שהגישה את הבקשה. הקצה העורפי מאמת אוטומטית את האסימון הזה ומפענח אותו, ומחדיר את ה-
appId
context
של המטפל. אם לא ניתן לאמת את האסימון, הבקשה נדחית. (זמין עבור SDK >=3.14.0)
- אסימון ה-Firebase App Check שסופק על ידי אפליקציית הלקוח שהגישה את הבקשה. הקצה העורפי מאמת אוטומטית את האסימון הזה ומפענח אותו, ומחדיר את ה-
אם כלולים כותרות אחרות, הבקשה נדחית, כמתואר בתיעוד התגובה שלהלן.
הערה: בלקוחות JavaScript, בקשות אלו מפעילות בדיקה מוקדמת של CORS OPTIONS
, מכיוון:
-
application/json
אינו מורשה. זה חייב להיותtext/plain
אוapplication/x-www-form-urlencoded
. - כותרת
Authorization
אינה כותרת בקשה ברשימה בטוחה של CORS . - כותרות אחרות אינן מותרות באופן דומה.
הטריגר הניתן להתקשרות מטפל אוטומטית בבקשות ה- OPTIONS
הללו.
גוף הבקשה
גוף בקשת ה-HTTP צריך להיות אובייקט JSON עם כל אחד מהשדות הבאים:
- נדרש:
data
- הארגומנט הועבר לפונקציה. זה יכול להיות כל ערך JSON חוקי. זה מפוענח אוטומטית לסוגי JavaScript מקוריים לפי פורמט הסידרה המתואר להלן.
אם יש שדות נוספים בבקשה, הקצה העורפי מחשיב את הבקשה כפגומה, והיא נדחתה.
פורמט תגובה: קודי מצב
ישנם מספר מקרים שעלולים לגרום לקודי מצב HTTP שונים ולקודי סטטוס מחרוזת עבור שגיאות בתגובה.
במקרה של שגיאת HTTP לפני הפעלת טריגר
client
, התגובה אינה מטופלת כפונקציית לקוח. לדוגמה, אם לקוח מנסה להפעיל פונקציה לא קיימת, הוא מקבל תגובת404 Not Found
.אם הטריגר של הלקוח מופעל, אך הבקשה בפורמט שגוי, כגון לא JSON, שדות לא חוקיים או חסר שדה
data
, הבקשה נדחית עם400 Bad Request
, עם קוד שגיאה שלINVALID_ARGUMENT
.אם אסימון ההרשאה שסופק בבקשה אינו חוקי, הבקשה נדחית עם
401 Unauthorized
, עם קוד שגיאה שלUNAUTHENTICATED
.אם אסימון הרישום של FCM שסופק בבקשה אינו חוקי, ההתנהגות אינה מוגדרת. האסימון לא נבדק בכל בקשה, למעט כאשר הוא משמש לשליחת הודעת דחיפה עם FCM.
אם הטריגר הניתן להתקשרות מופעל, אך נכשל עם חריגה לא מטופלת או מחזיר הבטחה שנכשלה, הבקשה נדחית עם
500 Internal Server Error
, עם קוד שגיאה שלINTERNAL
. זה מונע משגיאות קידוד להיחשף בטעות למשתמשי קצה.אם הניתן להתקשרות מופעל ומחזיר מצב שגיאה מפורש באמצעות ה-API שסופק לפונקציות הניתנות להתקשרות, הבקשה נכשלת. קוד מצב ה-HTTP המוחזר מבוסס על המיפוי הרשמי של מצב השגיאה לסטטוס HTTP, כפי שהוגדר ב- code.proto . קוד השגיאה, ההודעה והפרטים הספציפיים המוחזרים מקודדים בגוף התגובה כמפורט להלן. המשמעות היא שאם הפונקציה מחזירה שגיאה מפורשת עם הסטטוס
OK
, אז לתגובה יש סטטוס200 OK
, אך שדהerror
מוגדר בתגובה.אם ההפעלה של הלקוח מצליחה, סטטוס התגובה הוא
200 OK
.
פורמט תגובה: כותרות
לתגובה יש את הכותרות הבאות:
-
Content-Type: application/json
- אופציונלי
; charset=utf-8
מותר.
גוף תגובה
התגובה מנקודת קצה של לקוח היא תמיד אובייקט JSON. לכל הפחות הוא מכיל result
או error
, יחד עם כל שדות אופציונליים. אם התגובה אינה אובייקט JSON, או שאינה מכילה data
או error
, ה-SDK של הלקוח צריך להתייחס לבקשה ככשלה עם קוד השגיאה של Google INTERNAL (13)
.
-
error
- אם שדה זה קיים, הבקשה נחשבת ככשלה, ללא קשר לקוד הסטטוס של HTTP או אם קיימים גםdata
. הערך של שדה זה צריך להיות אובייקט JSON בפורמט הסטנדרטי של Google Cloud HTTP Mapping עבור שגיאות, עם שדות עבורstatus
,message
details
(אופציונלי). שדהcode
לא ייכלל. אם שדהstatus
אינו מוגדר, או שהוא ערך לא חוקי, הלקוח צריך להתייחס לסטטוס כאלINTERNAL
, בהתאם ל- code.proto . אם קיימיםdetails
, הם נכללים בכל מידע משתמש המצורף לשגיאה ב-SDK של הלקוח, אם רלוונטי.
הערה: שדהdetails
כאן הוא ערך שסופק על ידי המשתמש. זו לא בהכרח רשימה של ערכים המבוססים על סוג פרוטו כמו בפורמט GoogleStatus
. -
result
- הערך המוחזר על ידי הפונקציה. זה יכול להיות כל ערך JSON חוקי. ה-SDK של firebase-functions מקודד אוטומטית את הערך המוחזר על ידי המשתמש לפורמט JSON זה. ערכות ה-SDK של הלקוח מפענחות באופן אוטומטי את הפרמטרים הללו לסוגים מקוריים בהתאם לפורמט הסידרה המתואר להלן.
אם קיימים שדות אחרים, יש להתעלם מהם.
סדרה
פורמט ההסדרה עבור מטענים שרירותיים של נתונים זהה הן עבור הבקשה והן עבור התגובה.
למען עקביות הפלטפורמה, אלה מקודדים ב-JSON כאילו הם הערך של שדה Any
במאגר פרוטוקול proto3, באמצעות מיפוי JSON הסטנדרטי . ערכים של סוגים פשוטים כגון null
, int
, double
או string
מקודדים ישירות ואינם כוללים את הסוג המפורש שלהם. אז, float
double
מקודדים באותו אופן, וייתכן שלא תדע מה מתקבל בצד השני של השיחה. עבור טיפוסים שאינם מקוריים ל-JSON, נעשה שימוש בקידוד proto3 המוקלד עבור הערך. למידע נוסף, עיין בתיעוד עבור כל קידוד JSON .
הסוגים הבאים מותרים:
- null -
null
- int (חתום או לא חתום, עד 32 סיביות) - למשל
3
או-30
. - לצוף - למשל
3.14
- כפול - למשל
3.14
- בוליאני -
true
אוfalse
- מחרוזת - למשל
"hello world"
- מַפָּה
- למשל {"x": 3}
- רשימה
- למשל [1, 2, 3]
- ארוך (חתום או לא חתום, עד 64 סיביות) - [ראה למטה לפרטים]
ערכי NaN
ו- Infinity
עבור float
double
אינם נתמכים.
שימו לב ש- long
הוא סוג מיוחד שלא מותר בדרך כלל ב-JSON, אבל הוא מכוסה על ידי מפרט proto3. לדוגמה, אלה מקודדים כ:
ארוך
{
'@type': 'type.googleapis.com/google.protobuf.Int64Value',
'value': '-123456789123456'
}
לא חתום ארוך
{
'@type': 'type.googleapis.com/google.protobuf.UInt64Value',
'value': '123456789123456'
}
באופן כללי, יש לראות במפתח @type
שמור, ולא להשתמש בו עבור מפות שהועברו פנימה.
מכיוון שהסוג לא מצוין עבור טיפוסים פשוטים, חלק מהערכים ישנו סוג לאחר מעבר על החוט. float
שעברה פנימה הופכת double
. short
הופך ל- int
, וכן הלאה. באנדרואיד, גם List
וגם JSONArray
נתמכים עבור ערכי רשימה. במקרים אלה, העברת JSONArray תניב List
.
אם מפה עם שדה @type
לא ידוע מסודרת, היא נשארת כמפה. זה מאפשר למפתחים להוסיף שדות עם סוגים חדשים לערכי ההחזר שלהם מבלי לשבור לקוחות ישנים יותר.
דוגמאות קוד
הדוגמאות בסעיף זה ממחישות כיצד לקודד את הדברים הבאים:
- דוגמה callable.call ב-Swift
- תגובה מוצלחת לשיחה
- תגובת כשל לשיחה
Callable.call לדוגמה ב-Swift לקידוד
callable.call([
"aString": "some string",
"anInt": 57,
"aFloat": 1.23,
"aLong": -123456789123456 as Int64
])
כותרת הבקשה:
Method: POST
Content-Type: application/json; charset=utf-8
Authorization: Bearer some-auth-token
Firebase-Instance-ID-Token: some-iid-token
גוף הבקשה:
{
"data": {
"aString": "some string",
"anInt": 57,
"aFloat": 1.23,
"aLong": {
"@type": "type.googleapis.com/google.protobuf.Int64Value",
"value": "-123456789123456"
}
}
}
תגובה לקידוד
return {
"aString": "some string",
"anInt": 57,
"aFloat": 1.23
};
כותרת תגובה מוצלחת:
200 OK
Content-Type: application/json; charset=utf-8
גוף תגובה מוצלח:
{
"response": {
"aString": "some string",
"anInt": 57,
"aFloat": 1.23
}
}
כשל בתגובה לקידוד
throw new HttpsError("unauthenticated", "Request had invalid credentials.", {
"some-key": "some-value"
});
כותרת תגובה שנכשלה:
401 UNAUTHENTICATED
Content-Type: application/json; charset=utf-8
גוף התגובה שנכשל:
{
"error": {
"message": "Request had invalid credentials.",
"status": "UNAUTHENTICATED",
"details": {
"some-key": "some-value"
}
}
}