https.onCall 的協議規範

Cloud Functions 的https.onCall觸發器是一個 HTTPS 觸發器，具有特定的請求和響應格式。本節提供客戶端 SDK 用於實現 API 的 HTTPS 請求和響應格式的規範。如果使用 Android、Apple 平台或 Web SDK 無法滿足您的要求，則此信息可能對您有用。

請求格式：標頭

對可調用觸發器端點的 HTTP 請求必須是具有以下標頭的POST ：

  • 必需： Content-Type: application/json
    • 一個可選的; charset=utf-8允許使用; charset=utf-8 。
  • 可選： Authorization: Bearer <token>
    • 發出請求的登錄用戶的 Firebase 身份驗證用戶 ID 令牌。後端自動驗證此令牌並使其在處理程序的context中可用。如果令牌無效，則請求被拒絕。
  • 可選： Firebase-Instance-ID-Token: <iid>
    • 來自 Firebase 客戶端 SDK 的 FCM 註冊令牌。這必須是一個字符串。這在處理程序的context中可用。它用於定位推送通知。
  • 可選： X-Firebase-AppCheck: <token>
    • 發出請求的客戶端應用提供的 Firebase 應用檢查令牌。後端自動驗證此令牌並對其進行解碼，將appId注入處理程序的context中。如果無法驗證令牌，則請求將被拒絕。 （適用於 SDK >=3.14.0）

如果包含任何其他標頭，則請求將被拒絕，如下面的響應文檔中所述。

注意：在 JavaScript 客戶端中，這些請求會觸發 CORS OPTIONS預檢，因為：

  • 不允許application/json 。它必須是text/plain或application/x-www-form-urlencoded 。
  • Authorization標頭不是CORS 安全列表中的 request-header 。
  • 其他標頭同樣也是不允許的。

可調用觸發器自動處理這些OPTIONS請求。

請求正文

HTTP 請求的正文應該是具有以下任意字段的 JSON 對象：

  • 必需： data - 傳遞給函數的參數。這可以是任何有效的 JSON 值。它會根據下面描述的序列化格式自動解碼為本機 JavaScript 類型。

如果請求中存在任何其他字段，後端會認為該請求格式錯誤，並拒絕該請求。

響應格式：狀態碼

在多種情況下，可能會導致響應中的錯誤出現不同的 HTTP 狀態代碼和字符串狀態代碼。

  1. 如果在調用client觸發器之前發生 HTTP 錯誤，則響應不會作為客戶端函數進行處理。例如，如果客戶端嘗試調用不存在的函數，它將收到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允許使用; charset=utf-8 。

響應體

來自客戶端端點的響應始終是 JSON 對象。它至少包含result或error以及任何可選字段。如果響應不是 JSON 對象，或者不包含data或error ，則客戶端 SDK 應將請求視為失敗，並顯示 Google 錯誤代碼INTERNAL (13) 。

  • error - 如果此字段存在，則請求被視為失敗，無論 HTTP 狀態代碼或data是否也存在。此字段的值應該是標準Google Cloud HTTP 錯誤映射格式的 JSON 對象，其中包含status 、 message和（可選） details字段。不應包含code字段。如果status字段未設置，或者是無效值，則客戶端應根據code.proto將狀態視為INTERNAL 。如果存在details ，則它會包含在客戶端 SDK 中錯誤所附加的任何用戶信息中（如果適用）。
    注意：此處的details字段是用戶提供的值。它不一定是像 Google Status格式那樣由原型類型鍵入的值列表。
  • result - 函數返回的值。這可以是任何有效的 JSON 值。 firebase-functions SDK 會自動將用戶返回的值編碼為這種 JSON 格式。客戶端 SDK 根據下面描述的序列化格式自動將這些參數解碼為本機類型。

如果存在其他字段，則應忽略它們。

序列化

請求和響應的任意數據有效負載的序列化格式是相同的。

為了平台一致性，這些使用標準 JSON 映射以 JSON 進行編碼，就好像它們是 proto3 協議緩衝區中的Any字段的值一樣。簡單類型（例如null 、 int 、 double或string的值直接編碼，並且不包括其顯式類型。因此， float和double的編碼方式相同，您可能不知道調用的另一端收到的是哪一個。對於非 JSON 原生的類型，將使用值的類型化 proto3 編碼。有關更多信息，請參閱任何 JSON 編碼的文檔。

允許使用以下類型：

  • 空 - null
  • int （有符號或無符號，最多 32 位） - 例如3或-30 。
  • 浮動 - 例如3.14
  • 雙 - 例如3.14
  • 布爾值 - true或false
  • 字符串 - 例如"hello world"
  • 地圖- 例如{"x": 3}
  • 列表- 例如[1, 2, 3]
  • long（有符號或無符號，最多 64 位）- [詳細信息見下文]

不支持float和double的NaN和Infinity值。

請注意， 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 ，等等。在 Android 中，列表值支持List和JSONArray 。在這些情況下，傳入 JSONArray 將生成一個List 。

如果反序列化具有未知@type字段的映射，則它將保留為映射。這允許開發人員將具有新類型的字段添加到其返回值中，而不會破壞舊客戶端。

代碼示例

本節中的示例說明瞭如何對以下內容進行編碼：

  • Swift 中的 callable.call 示例
  • 呼叫成功響應
  • 呼叫響應失敗

Swift 中的 Callable.call 示例進行編碼

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"
        }
    }
}