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

טריגר https.onCall עבור פונקציות ענן הוא טריגר HTTPS עם פורמט ספציפי לבקשה והתגובה. סעיף זה מספק מפרט עבור פורמטים של בקשת HTTPS ותגובה המשמשים את SDK של הלקוח כדי ליישם את ה-API. מידע זה עשוי להיות שימושי עבורך אם לא ניתן לעמוד בדרישות שלך באמצעות פלטפורמות אנדרואיד, אפל או ערכות פיתוח אינטרנט.

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

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

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

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

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

• 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 שסופק בבקשה אינו חוקי, ההתנהגות אינה מוגדרת. האסימון לא נבדק בכל בקשה, למעט כאשר הוא משמש לשליחת הודעת דחיפה עם 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 של הלקוח צריך להתייחס לבקשה ככשלה עם קוד השגיאה של Google INTERNAL (13) .

• error - אם שדה זה קיים, הבקשה נחשבת ככשלה, ללא קשר לקוד הסטטוס של HTTP או אם קיימים גם data . הערך של שדה זה צריך להיות אובייקט JSON בפורמט הסטנדרטי של Google Cloud HTTP Mapping עבור שגיאות, עם שדות עבור 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
• כפול - למשל 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"
        }
    }
}