Firebase Summit で発表されたすべての情報をご覧ください。Firebase を使用してアプリ開発を加速し、自信を持ってアプリを実行する方法を紹介しています。詳細

https.onCallのプロトコル仕様

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

Cloud Functions のhttps.onCallトリガーは、要求と応答の特定の形式を持つ HTTPS トリガーです。このセクションでは、API を実装するためにクライアント SDK で使用される HTTPS 要求および応答形式の仕様を提供します。この情報は、Android、Apple プラットフォーム、または Web SDK を使用して要件を満たすことができない場合に役立ちます。

リクエスト形式: ヘッダー

呼び出し可能なトリガー エンドポイントへの HTTP 要求は、次のヘッダーを持つPOSTである必要があります。

  • 必須: Content-Type: application/json
    • オプションの; charset=utf-8が許可されています。
  • オプション: Authorization: Bearer <token>
    • リクエストを行っているログイン ユーザーの Firebase Authentication ユーザー ID トークン。バックエンドはこのトークンを自動的に検証し、ハンドラーのcontextで使用できるようにします。トークンが有効でない場合、リクエストは拒否されます。
  • オプション: Firebase-Instance-ID-Token: <iid>
    • Firebase クライアント SDK からの FCM 登録トークン。これは文字列でなければなりません。これは、ハンドラーの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 セーフリストの 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. 呼び出し可能なトリガーが呼び出されたが、未処理の例外で失敗するか、失敗した promise を返す場合、リクエストは500 Internal Server Errorで拒否され、エラー コードはINTERNALになります。これにより、コーディング エラーが誤ってエンド ユーザーに公開されるのを防ぐことができます。

  6. callable が呼び出され、callable 関数用に提供された API を使用して明示的なエラー状態を返す場合、リクエストは失敗します。返される HTTP ステータス コードは、 code.protoで定義されているように、エラー ステータスから HTTP ステータスへの公式のマッピングに基づいています。返される特定のエラー コード、メッセージ、および詳細は、以下に詳述するように、応答本文にエンコードされます。つまり、関数がステータスOKの明示的なエラーを返した場合、レスポンスのステータスは200 OKになりますが、 errorフィールドはレスポンスに設定されます。

  7. クライアント トリガーが成功した場合、応答ステータスは200 OK

応答形式: ヘッダー

応答には次のヘッダーがあります。

  • Content-Type: application/json
  • オプションの; charset=utf-8が許可されています。

レスポンスボディ

クライアント エンドポイントからの応答は常に JSON オブジェクトです。少なくとも、オプションのフィールドに加えて、 resultまたはerrorのいずれかが含まれます。レスポンスが JSON オブジェクトでない場合、またはdataerrorが含まれていない場合、クライアント SDK は Google エラー コードINTERNAL (13)でリクエストを失敗として処理する必要があります。

  • error - このフィールドが存在する場合、HTTP ステータス コードやdataも存在するかどうかに関係なく、リクエストは失敗したと見なされます。このフィールドの値は、エラー用の標準のGoogle Cloud HTTP マッピング形式の JSON オブジェクトである必要があり、 statusmessage 、および (オプションで) detailsのフィールドがあります。 codeフィールドは含まれません。 statusフィールドが設定されていないか、無効な値である場合、クライアントはcode.protoに従ってステータスをINTERNALとして扱う必要があります。 detailsが存在する場合は、該当する場合、クライアント SDK のエラーに添付されたユーザー情報に含まれます。
    注:ここのdetailsフィールドは、ユーザー指定の値です。これは、必ずしも Google Status形式のようにプロトタイプ タイプによってキー設定された値のリストではありません。
  • result - 関数によって返される値。これは、任意の有効な JSON 値にすることができます。 firebase-functions SDK は、ユーザーから返された値をこの JSON 形式に自動的にエンコードします。クライアント SDK は、以下で説明するシリアル化形式に従って、これらのパラメーターをネイティブ型に自動的にデコードします。

他のフィールドが存在する場合、それらは無視されます。

シリアル化

任意のデータ ペイロードのシリアル化形式は、要求と応答の両方で同じです。

プラットフォームの一貫性のために、これらは、標準の JSON マッピングを使用して、proto3 プロトコル バッファー内のAnyフィールドの値であるかのように JSON でエンコードされます。 nullintdouble 、またはstringなどの単純な型の値は直接エンコードされ、明示的な型は含まれません。そのため、 floatdoubleは同じ方法でエンコードされ、呼び出しの反対側でどちらが受信されたかわからない場合があります。 JSON にネイティブでない型の場合、値の型付き proto3 エンコーディングが使用されます。詳細については、 Any JSON encoding のドキュメントを参照してください。

次のタイプが許可されています。

  • ヌル - null
  • int (符号付きまたは符号なし、最大 32 ビット) - 例: 3または-30
  • float - 例: 3.14
  • double - 例: 3.14
  • ブール値 - trueまたはfalse
  • 文字列 - 例: "hello world"
  • 地図- 例{"x": 3}
  • リスト- 例[1, 2, 3]
  • long (符号付きまたは符号なし、最大 64 ビット) - [詳細は以下を参照]

floatおよびdoubleNaNおよびInfinity値はサポートされていません。

longは、JSON では通常許可されていない特殊な型ですが、proto3 仕様でカバーされていることに注意してください。たとえば、これらは次のようにエンコードされます。

長いです

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

符号なしロング

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

一般に、 @typeキーは予約されていると見なされ、渡されたマップには使用されません。

単純型は型が指定されていないため、一部の値はワイヤーを通過した後に型が変わります。渡されたfloatdoubleになります。 shortintになります。 Android では、リスト値に対してListJSONArrayの両方がサポートされています。そのような場合、 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"
        }
    }
}