מפרט הפרוטוקול עבור https.onCall

טריגר https.onCall ל-Cloud Functions הוא טריגר HTTPS עם פורמט ספציפי לבקשה ולתגובה. בקטע הזה מפורטות המפרטים של פורמטים של בקשות ותשובות HTTPS שמשמשים את ה-Client SDK כדי להטמיע את ה-API. המידע הזה יכול להיות שימושי אם אי אפשר לעמוד בדרישות שלכם באמצעות ערכות ה-SDK ל-Android, לפלטפורמות של Apple או לאינטרנט.

פורמט הבקשה: כותרות

בקשת ה-HTTP לנקודת קצה של טריגר שאפשר להפעיל חייבת להיות מסוג POST עם הכותרות הבאות:

• חובה: Content-Type: application/json
  • אפשר להשתמש ב-; charset=utf-8 אופציונלי.
• אופציונלי: Authorization: Bearer <token>
  • אסימון מזהה משתמש Firebase Authentication של המשתמש המחובר שמבצע את הבקשה. הקצה העורפי מאמת את הטוקן הזה באופן אוטומטי והופך אותו לזמין ב-context של ה-handler. אם האסימון לא תקף, הבקשה נדחית.
• אופציונלי: Firebase-Instance-ID-Token: <iid>
  • טוקן הרישום של FCM מ-Firebase Client SDK. הערך חייב להיות מחרוזת. האפשרות הזו זמינה ב-context של המטפל. הוא משמש לטירגוט של הודעות פוש.
• אופציונלי: X-Firebase-AppCheck: <token>
  • הטוקן של Firebase App Check שסופק על ידי אפליקציית הלקוח שממנה נשלחה הבקשה. הקצה העורפי מאמת את האסימון הזה ומפענח אותו באופן אוטומטי, ומזריק את appId אל context של ה-handler. אם אי אפשר לאמת את האסימון, הבקשה נדחית. (זמין ב-SDK בגרסה 3.14.0 ומעלה)

אם נכללות כותרות אחרות, הבקשה נדחית, כפי שמתואר במסמכי התגובה שבהמשך.

הערה: בלקוחות JavaScript, הבקשות האלה מפעילות בקשת קדם-הפעלה של CORS OPTIONS, כי:

• לא ניתן להפר את המדיניות: application/json הערך חייב להיות text/plain או application/x-www-form-urlencoded.
• הכותרת Authorization היא לא כותרת בקשה בטוחה ב-CORS.
• באופן דומה, אסור להשתמש בכותרות אחרות.

הטריגר שניתן להפעלה מטפל אוטומטית בבקשות האלה.OPTIONS

גוף הבקשה

התוכן של בקשת ה-HTTP צריך להיות אובייקט JSON עם אחד מהשדות הבאים:

• חובה: data – הארגומנט שמועבר לפונקציה. הערך יכול להיות כל ערך JSON תקין. הפענוח הזה מתבצע אוטומטית לסוגי JavaScript מקוריים בהתאם לפורמט הסריאליזציה שמתואר בהמשך.

אם יש שדות אחרים בבקשה, ה-Backend יזהה את הבקשה כבקשה פגומה והיא תידחה.

פורמט התשובה: קודי סטטוס

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

1. במקרה של שגיאת HTTP לפני הפעלת הטריגר client, התגובה לא מטופלת כפונקציית לקוח. לדוגמה, אם לקוח מנסה להפעיל פונקציה שלא קיימת, הוא מקבל תגובה 404 Not Found.

2. אם מופעל טריגר בצד הלקוח, אבל הבקשה היא בפורמט שגוי, למשל לא בפורמט JSON, או שהשדות לא תקינים או שהשדה data חסר, הבקשה נדחית עם 400 Bad Request, עם קוד שגיאה INVALID_ARGUMENT.

3. אם טוקן האימות שסופק בבקשה לא תקין, הבקשה נדחית עם קוד השגיאה 401 Unauthorized, UNAUTHENTICATED.

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

5. אם מפעילים את הטריגר שאפשר להפעיל, אבל הוא נכשל בגלל חריגה שלא טופלה או מחזיר הבטחה שנכשלה, הבקשה נדחית עם 500 Internal Server Error וקוד השגיאה INTERNAL. כך נמנעת חשיפה של שגיאות בתכנות למשתמשי הקצה.

6. אם הפונקציה ניתנת להפעלה ומוחזר תנאי שגיאה מפורש באמצעות ה-API שסופק לפונקציות שניתנות להפעלה, הבקשה נכשלת. קוד הסטטוס של HTTP שמוחזר מבוסס על המיפוי הרשמי של סטטוס השגיאה לסטטוס HTTP, כפי שמוגדר ב-code.proto. קוד השגיאה, ההודעה והפרטים הספציפיים שמוחזרים מקודדים בגוף התגובה, כמו שמפורט בהמשך. כלומר, אם הפונקציה מחזירה שגיאה מפורשת עם סטטוס OK, התשובה תהיה עם סטטוס 200 OK, אבל השדה error יוגדר בתשובה.

7. אם ההפעלה של הטריגר בצד הלקוח מצליחה, סטטוס התגובה הוא 200 OK.

פורמט התשובה: כותרות

התשובה כוללת את הכותרות הבאות:

• Content-Type: application/json
• אפשר להשתמש ב-; charset=utf-8 אופציונלי.

גוף התשובה

התגובה מנקודת קצה של לקוח היא תמיד אובייקט JSON. לפחות אחד מהשדות result או error חייב להופיע, בנוסף לכל השדות האופציונליים. אם התגובה היא לא אובייקט JSON, או אם היא לא מכילה את data או error, ה-SDK של הלקוח צריך להתייחס לבקשה כאל בקשה שנכשלה עם קוד השגיאה INTERNAL (13) של Google.

• ‫error – אם השדה הזה קיים, הבקשה נחשבת כבקשה שנכשלה, ללא קשר לקוד הסטטוס של HTTP או לשאלה אם קיים גם data. הערך של השדה הזה צריך להיות אובייקט JSON בפורמט מיפוי HTTP של Google Cloud הרגיל לשגיאות, עם שדות ל-status, ל-message ול-details (אופציונלי). השדה code לא ייכלל. אם השדה status לא מוגדר או שהערך שלו לא תקין, הלקוח צריך להתייחס לסטטוס כאל INTERNAL, בהתאם ל-code.proto. אם details קיים, הוא נכלל בפרטי המשתמש שמצורפים לשגיאה ב-SDK של הלקוח, אם רלוונטי.
  הערה: השדה details כאן הוא ערך שהמשתמש סיפק. הוא לא בהכרח רשימה של ערכים עם מפתח לפי סוג פרוטו כמו בפורמט של Google Status.
• ‫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
• ‫double – לדוגמה, 3.14
• ‫boolean –‏ true או false
• מחרוזת – למשל: "hello world"
• ‫map<string, any=""> – לדוגמה, {"x": 3}</string,>
• רשימה – לדוגמה: [1, 2, 3]
• ‫long (עם או בלי סימן, עד 64 ביט) – [פרטים נוספים מופיעים בהמשך]

אין תמיכה בערכים NaN ו-Infinity של הפרמטרים float ו-double.

שימו לב ש-long הוא סוג מיוחד שבדרך כלל לא מותר ב-JSON, אבל הוא כלול במפרט proto3. לדוגמה, הם מקודדים כך:

long

{
    '@type': 'type.googleapis.com/google.protobuf.Int64Value',
    'value': '-123456789123456'
}

unsigned long

{
    '@type': 'type.googleapis.com/google.protobuf.UInt64Value',
    'value': '123456789123456'
}

באופן כללי, המפתח @type שמור ואין להשתמש בו במפות שמועברות.

מכיוון שהסוג לא מצוין עבור סוגים פשוטים, חלק מהערכים ישנו את הסוג שלהם אחרי שהם עוברים דרך החוט. התנאי float passed in הופך ל-double. short הופך ל-int וכן הלאה. ב-Android, יש תמיכה גם ב-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"
        }
    }
}