מפרט הפרוטוקול עבור 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 כאן הוא ערך שהמשתמש סיפק. זה לא בהכרח רשימה של ערכים שמקבלים מפתח לפי סוג פרוטו כמו בפורמט Status של Google.
  • ‫result – הערך שהפונקציה מחזירה. הערך יכול להיות כל ערך JSON תקין. ה-SDK של firebase-functions מקודד אוטומטית את הערך שהמשתמש מחזיר לפורמט JSON הזה. ערכי הפרמטרים האלה מפוענחים אוטומטית בספריות ה-SDK של הלקוח לסוגים מקוריים בהתאם לפורמט הסריאליזציה שמתואר בהמשך.

אם יש שדות אחרים, צריך להתעלם מהם.

סריאליזציה

פורמט הסריאליזציה של מטעני נתונים שרירותיים זהה גם בבקשה וגם בתגובה.

כדי לשמור על עקביות בין הפלטפורמות, הערכים האלה מקודדים ב-JSON כאילו הם הערך של השדה Any ב-proto3 protocol buffer, באמצעות מיפוי JSON רגיל. ערכים של סוגים פשוטים כמו null,‏ int,‏ double או string מקודדים ישירות, ולא כוללים את הסוג המפורש שלהם. לכן, הקידוד של float ושל double זהה, ואולי לא תדעו מה מתקבל בצד השני של השיחה. עבור סוגים שלא מובנים ב-JSON, נעשה שימוש בקידוד המוקלד של proto3 עבור הערך. מידע נוסף מופיע במסמכי התיעוד בנושא קידוד JSON.

מותר להשתמש בסוגים הבאים:

  • null – null
  • ‫int (עם סימן או בלי סימן, עד 32 ביט) – למשל 3 או -30.
  • מספר צף – לדוגמה, 3.14
  • כפול – למשל, 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"
        }
    }
}