מפרט הפרוטוקול עבור 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 של המשתמש המחובר שמבצע את הבקשה. ה-backend מאמת את האסימון הזה באופן אוטומטי ומאפשר להשתמש בו ב-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 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"
        }
    }
}