API Gateway でペイロードレスポンスストリーミングと Lambda プロキシ統合を設定する

Lambda 関数のレスポンスをストリーミングして、最初のバイトまでの時間 (TTFB) のパフォーマンスを向上させ、利用可能になると部分的なレスポンスをクライアントに送信し直すことができます。API Gateway では、InvokeWithResponseStream Lambda API を使用して Lambda 関数を呼び出す必要があります。API Gateway はイベントオブジェクトを Lambda 関数に渡します。バックエンド Lambda 関数では、受信リクエストデータを解析して、返すレスポンスを決定します。API Gateway が Lambda 出力をストリーミングするには、Lambda 関数が API Gateway に必要な形式を出力する必要があります。

ストリームとバッファレスポンス転送モードの Lambda プロキシ統合の違い

次のリストでは、レスポンスストリーミングの Lambda プロキシ統合と Lambda プロキシ統合の違いについて説明します。

• API Gateway は、InvokeWithResponseStream API を使用して、レスポンスストリーミング用の Lambda プロキシ統合を呼び出します。これにより、次の異なる URI になります。

  arn:aws:apigateway:us-west-1:lambda:path/2021-11-15/functions/arn:aws:lambda:us-west-1:111122223333:function:my-function-name/response-streaming-invocations

  この ARN は、Lambda プロキシ統合とは異なる API バージョンと異なるサービスアクションを使用します。

  レスポンスストリーミングに API Gateway コンソールを使用する場合、コンソールは正しい URI を使用します。

• Lambda プロキシ統合では、API Gateway は Lambda から完全なレスポンスを受け取った後にのみクライアントにレスポンスを送信します。レスポンスストリーミング用の Lambda プロキシ統合では、API Gateway は Lambda から有効なメタデータと区切り記号を受け取った後にペイロードストリームを開始します。

• レスポンスストリーミング用の Lambda プロキシ統合は、プロキシ統合と同じ入力形式を使用しますが、異なる出力形式が必要です。

レスポンスストリーミング用の Lambda プロキシ統合形式

API Gateway がレスポンスストリーミングで Lambda 関数を呼び出す場合、入力形式はプロキシ統合用の Lambda 関数の入力形式と同じです。詳細については、「プロキシ統合のための Lambda 関数の入力形式」を参照してください。

Lambda が API Gateway にレスポンスをストリーミングする場合、レスポンスは次の形式に従う必要があります。この形式では、区切り記号を使用してメタデータ JSON と raw ペイロードを区切ります。この場合、ペイロードデータはストリーミング Lambda 関数によって送信されるときにストリーミングされます。

{
  "headers": {"headerName": "headerValue", ...},
  "multiValueHeaders": { "headerName": ["headerValue", "headerValue2", ...], ... },
  "cookies" : ["cookie1", "cookie2"],
  "statusCode": httpStatusCode
}<DELIMITER>PAYLOAD1 | PAYLOAD2 | PAYLOAD3

出力では、次のようになります。

• 余分なレスポンスヘッダーが返されない場合、headers、multiValueHeaders、cookies、および statusCode キーは指定されません。

• headers キーには、単一値のヘッダーのみを含めることができます。

• 出力では、ヘッダーに Transfer-Encoding: chunked または Content-length: number が含まれていることが想定されます。関数がこれらのヘッダーのいずれかを返さない場合、API Gateway はレスポンスヘッダーに Transfer-Encoding: chunked を追加します。

• multiValueHeaders キーには、複数値のヘッダーや単一値のヘッダーを含めることができます。multiValueHeaders キーを使用して、単一値のヘッダーを含めて、すべてのヘッダーを指定することができます。

• headers と multiValueHeaders の両方の値を指定した場合、API Gateway はそれらを単一のリストにマージします。同じキーと値のペアが両方で指定された場合にのみ、multiValueHeaders の値が、マージされたリストに表示されます。

• メタデータは有効な JSON である必要があります。headers、multiValueHeaders、cookies、および statusCode キーのみがサポートされます。

• メタデータ JSON の後に区切り記号を指定する必要があります。区切り記号は 8 null バイトで、ストリームデータの最初の 16KB 以内に出現する必要があります。

• API Gateway では、メソッドレスポンスペイロードに特定の形式は必要ありません。

関数 URL を使用して Lambda 関数をストリーミングする場合は、これらの要件を満たすように Lambda 関数の入力と出力を変更する必要があります。

Lambda 関数の出力がこの形式の要件に準拠していない場合でも、API Gateway は Lambda 関数を呼び出す可能性があります。次の表は、API Gateway でサポートされている API 統合リクエスト設定と Lambda 関数コードの組み合わせを示しています。これには、バッファリングされたレスポンス転送モードでサポートされている組み合わせが含まれます。

レスポンス転送モード	関数コードが必要な形式に準拠している	Lambda 呼び出し API	API Gateway でサポートされている
ストリーム	あり	InvokeWithResponseStream	はい。API Gateway はレスポンスをストリーミングします。
ストリーム	不可	InvokeWithResponseStream	いいえ。API Gateway は Lambda 関数を呼び出し、500 のエラーレスポンスを返します。
ストリーム	あり	Invoke	いいえ。API Gateway はこの統合設定をサポートしていません。
ストリーム	不可	Invoke	いいえ。API Gateway はこの統合設定をサポートしていません。
バッファ済み	あり	InvokeWithResponseStream	いいえ。API Gateway はこの統合設定をサポートしていません。
バッファ済み	不可	InvokeWithResponseStream	いいえ。API Gateway はこの統合設定をサポートしていません。
バッファ済み	あり	Invoke	API Gateway は HTTP ヘッダーとステータスコードを返しますが、レスポンス本文は返しません。
バッファ済み	不可	Invoke	はい。これは Lambda プロキシ統合です。詳細については、「Lambda プロキシ統合」を参照してください。