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

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

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

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

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

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

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

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

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

גוף הבקשה

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

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

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

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

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

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

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

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

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

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

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

long

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

ארוך ללא חתימה

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

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

מכיוון שהסוג לא צוין לסוגים פשוטים, ערכים מסוימים ישתנו בסוג החוט אחרי המעבר. float שמועבר הופך ל-double. short הופך ל-int, וכן הלאה. ב-Android, ערכי הרשימות נתמכים גם ב-List וגם ב-JSONArray. במקרים כאלה, העברה של JSONArray תפיק List.

אם מפה שבה השדה @type לא ידוע עוברת deserialize, היא נשארת כמפה. כך מפתחים יכולים להוסיף שדות עם סוגים חדשים לערכי ההחזרה שלהם בלי לפגוע בלקוחות ישנים יותר.

דוגמאות קוד

הדוגמאות בקטע הזה ממחישות איך לקודד את הדברים הבאים:

• דוגמה ל-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"
        }
    }
}