https.onCall のプロトコルの仕様

Cloud Functions の https.onCall トリガーは、リクエストとレスポンスに関して特定の形式が含まれる HTTPS トリガーです。このセクションでは、API を実装するためにクライアント SDK により使用される HTTPS リクエストおよびレスポンスの形式の仕様について説明します。この情報は、Android、iOS、ウェブの SDK を使用すると要件を満たすことができない場合に役立つことがあります。

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

呼び出し可能なトリガー エンドポイントへの HTTP リクエストは、次のヘッダーが含まれる POST にする必要があります。

  • 必須: Content-Type: application/json
    • オプション: ; charset=utf-8 を使用できます。
  • オプション: Authorization: Bearer <token>
    • リクエストを行うログイン済みユーザーの Firebase Authentication ユーザー ID トークンです。バックエンドで、このトークンが自動的に検証され、ハンドラの context で使用可能になります。トークンが有効でない場合、リクエストは拒否されます。
  • オプション: Firebase-Instance-ID-Token: <iid>
    • Firebase クライアント SDK のインスタンス ID トークンです。これは文字列にする必要があり、またハンドラの context で使用できます。プッシュ通知を送信する場合に特に便利です。

その他のヘッダーが含まれる場合は、下記のレスポンスに関するドキュメントで説明されているように、リクエストは拒否されます。

注: 次の理由により、JavaScript クライアントでは、これらのリクエストによって CORS OPTIONS プリフライトがトリガーされます。

呼び出し可能なトリガーは、これらの 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. リクエストで指定されているインスタンス ID トークンが無効である場合、動作は未定義になります。インスタンス ID トークンは、すべてのリクエストでチェックされるわけではありません(FCM でプッシュ通知を送信するために使用される場合を除く)。

  5. 呼び出し可能なトリガーが呼び出されたにもかかわらず、処理できない例外により失敗した、または失敗した Promise を返した場合は、リクエストは 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 オブジェクトです。少なくとも、data または error のいずれか一方と、オプションのフィールドが含まれています。レスポンスが JSON オブジェクトではないか、data または error が含まれていない場合は、クライアント SDK はリクエストを失敗(Google エラーコードは INTERNAL (13))として処理します。

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

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

シリアル化

任意のデータ ペイロードのシリアル化形式は、リクエストとレスポンスの両方で同じです。

プラットフォームでの整合性を実現するために、これらは proto3 プロトコル バッファ内の Any フィールドの値と同様に JSON でエンコードされ、その際に標準の JSON マッピングが使用されます。nullintdoublestring などの単純型の値は直接エンコードされ、それらに明示的な型は含まれません。したがって、floatdouble が同じ方法でエンコードされるため、呼び出しの相手側でどちらで受信されたかが不明になる場合があります。JSON のネイティブではない型の場合、型指定の proto3 エンコードが使用されます。詳しくは、JSON エンコードに関するドキュメントをご覧ください。

次の型を使用できます。

  • null - null
  • int(符号付きまたは符号なし、最大 32 ビット)- 例: 3 または -30
  • float - 例: 3.14
  • double - 例: 3.14
  • boolean - true または false
  • string - 例: "hello world"
  • map - 例: {"x": 3}
  • list - 例: [1, 2, 3]
  • long(符号付きまたは符号なし、最大 64 ビット)- [詳細は下記を参照]

floatdouble の場合、NaN 値と Infinity 値はサポートされません。

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 が渡されると double になり、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

成功レスポンス本文:

{
    "data": {
        "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"
        }
    }
}

フィードバックを送信...

ご不明な点がありましたら、Google のサポートページをご覧ください。