API Gateway で統合レスポンスを設定する

非プロキシ統合の場合、1 つ以上の統合レスポンスを設定し、デフォルトのレスポンスにしたら、バックエンドから返される結果をクライアントに渡すように定義する必要があります。統合レスポンスデータとメソッドレスポンスデータで形式が異なる場合は、結果をそのまま渡すか、統合レスポンスデータをメソッドレスポンスデータに変換するかを選択できます。

プロキシ統合の場合、API Gateway は自動的にバックエンド出力を HTTP レスポンスとしてクライアントに渡します。この場合、お客様が統合レスポンスもメソッドレスポンスも設定することはありません。

統合レスポンスを設定するには、以下の必須およびオプションのタスクを実行します。

1. 統合レスポンスデータがマップされるメソッドレスポンスの HTTP ステータスコードを指定します。これは必須です。

2. この統合レスポンスが表すバックエンド出力に一致する正規表現を定義します。この項目を空のままにした場合、レスポンスは、未設定のレスポンスのキャッチに使用されるデフォルトのレスポンスになります。

3. 必要に応じて、指定した統合レスポンスパラメータを特定のメソッドレスポンスパラメータにマップするための、キーと値のペアで構成されるマッピングを宣言します。

4. 必要に応じて、特定の統合レスポンスペイロードを、指定したメソッドレスポンスペイロードに変換するための、本文マッピングテンプレートを追加します。

5. 必要に応じて、バイナリペイロードの型変換の処理方法を指定します。

統合レスポンスは、バックエンドレスポンスをカプセル化する HTTP レスポンスです。HTTP エンドポイントの場合、バックエンドレスポンスは HTTP レスポンスです。統合レスポンスのステータスコードは、バックエンドが返すステータスコードであり、統合レスポンスの本文は、バックエンドが返すペイロードです。Lambda エンドポイントの場合、バックエンドレスポンスは Lambda 関数から返される出力です。Lambda 統合では、Lambda 関数出力は 200 OK レスポンスとして返されます。ペイロードには、結果が JSON データ (JSON 文字列または JSON オブジェクト) として含まれたり、エラーメッセージが JSON オブジェクトとして含まれたりします。[selectionPattern] プロパティに正規表現を割り当てて、エラーレスポンスを該当する HTTP エラーレスポンスにマップできます。Lambda 関数のエラーレスポンスの詳細については、「API Gateway で Lambda エラーを処理する」を参照してください。Lambda プロキシ統合では、Lambda 関数は以下の形式で出力を返す必要があります。

{
    statusCode: "...",            // a valid HTTP status code
    headers: { 
        custom-header: "..."      // any API-specific custom header
    },
    body: "...",                  // a JSON string.
    isBase64Encoded:  true|false  // for binary support
}

Lambda 関数レスポンスを適切な HTTP レスポンスにマップする必要はありません。

結果をクライアントに返すには、エンドポイントレスポンスを対応するメソッドレスポンスにそのまま渡すように、統合レスポンスを設定します。または、エンドポイントレスポンスデータをメソッドレスポンスデータにマップすることもできます。マップできるレスポンスデータとしては、レスポンスステータスコード、レスポンスヘッダーパラメータ、レスポンス本文などがあります。返されたステータスコードに対してメソッドレスポンスが定義されていない場合、API Gateway は 500 エラーを返します。詳細については、「マッピングテンプレートを使用して、API のリクエストおよびレスポンスパラメータとステータスコードをオーバーライドする」を参照してください。