リクエストとレスポンスを使用する - Amazon CloudFront
オリジンフェイルオーバーで関数を使用するリクエストトリガーでの HTTP レスポンスを生成するオリジンレスポンストリガーでの HTTP レスポンスを更新するinclude body オプションを選択してリクエストボディにアクセスする

リクエストとレスポンスを使用する

Lambda@Edge のリクエストとレスポンスを使用するには、以下のトピックを参照してください。

オリジンフェイルオーバーで Lambda@Edge 関数を使用する

例えば、高い可用性を確保するために設定したオリジンフェイルオーバーなど、オリジングループで設定した CloudFront ディストリビューションで Lambda@Edge 関数を使用できます。オリジングループで Lambda 関数を使用するには、キャッシュ動作を作成するときにオリジングループのオリジンリクエストまたはオリジンレスポンストリガーで関数を指定します。

詳細については、次を参照してください:

リクエストトリガーでの HTTP レスポンスを生成する

CloudFront がリクエストを受け取ったときに、Lambda 関数が HTTP レスポンスを生成することで、CloudFront がレスポンスをオリジンに転送せずに直接ビューワーに返すようにできます。HTTP レスポンスを生成することで、オリジンの負荷が軽減され、通常はビューワーのレイテンシーも短縮されます。

以下に示しているのは、HTTP レスポンスを生成する一般的なシナリオです。

  • 小さいウェブページをビューワーに返す。

  • HTTP 301 または 302 ステータスコードを返して、ユーザーを別のウェブページにリダイレクトする。

  • ユーザーが認証されない場合に HTTP 401 ステータスコードをビューワーに返す。

Lambda@Edge 関数は、以下の CloudFront イベントが発生したときに HTTP レスポンスを生成できます。

ビューワーリクエストイベント

関数がビューワーリクエストイベントによってトリガーされると、CloudFront はレスポンスをビューワーに返し、キャッシュしません。

オリジンリクエストイベント

関数がオリジンリクエストイベントによってトリガーされると、CloudFront は、その関数によって以前に生成されたレスポンスがエッジキャッシュ内にあるかどうかを確認します。

  • レスポンスがキャッシュ内にある場合、関数は実行されず、CloudFront はキャッシュされたレスポンスをビューワーに返します。

  • レスポンスがキャッシュ内にない場合、関数が実行され、CloudFront はそのレスポンスをビューワーに返すとともに、キャッシュします。

HTTP レスポンスを生成するためのサンプルコードを見るには、「Lambda@Edge 関数の例」を参照してください。レスポンストリガーの HTTP レスポンスを置き換えることもできます。詳細については、「オリジンレスポンストリガーでの HTTP レスポンスを更新する」を参照してください。

プログラミングモデル

このセクションでは、Lambda@Edge を使用して HTTP レスポンスを生成するためのプログラミングモデルについて説明します。

レスポンスオブジェクト

result メソッドの callback パラメータとして返すレスポンスには、以下の構造が必要です (status フィールドのみが必須)。

const response = {
    body: 'content',
    bodyEncoding: 'text' | 'base64',
    headers: {
        'header name in lowercase': [{
            key: 'header name in standard case',
            value: 'header value'
         }],
         ...
    },
    status: 'HTTP status code (string)',
    statusDescription: 'status description'
};

レスポンスオブジェクトには、以下の値が含まれる場合があります。

body

生成されたレスポンスで CloudFront が返す本文 (存在する場合)。

bodyEncoding

body で指定した値のエンコード。有効なエンコードは text と base64 のみです。response オブジェクトに body を含めるが、bodyEncoding を省略した場合、CloudFront は本文をテキストとして扱います。

bodyEncoding を base64 と指定したが本文が有効な base64 でない場合、CloudFront はエラーを返します。

headers

生成されるレスポンスで CloudFront が返すヘッダー。次の点に注意してください。

  • headers オブジェクトのキーは標準の HTTP ヘッダー名を小文字にしたものです。小文字のキーを使用して、大文字と小文字を区別せずにヘッダー値にアクセスできます。

  • 各ヘッダー (headers["accept"]、headers["host"] など) はキーと値のペアの配列です。返されたヘッダーの配列には、生成されたレスポンスの値ごとに 1 つのキーと値のペアが含まれます。

  • key (省略可能) は、HTTP リクエストに表示されるヘッダーの大文字と小文字を区別する名前です (accept、host など)。

  • ヘッダー値として value を指定します。

  • キーと値のペアのヘッダーキー部分を含めない場合、Lambda@Edge は指定したヘッダー名を使用してヘッダーキーを自動的に挿入します。ヘッダー名をどのようにフォーマットしたかにかかわらず、挿入されるヘッダーキーは、各パートの先頭の大文字がハイフン (-) で区切られて自動的にフォーマットされます。

    たとえば、ヘッダーキー 'content-type': [{ value: 'text/html;charset=UTF-8' }] なしで次のようなヘッダーを追加できます。

    この例で、Lambda@Edge はヘッダーキー Content-Type を作成します。

ヘッダー使用の制限の詳細については、「エッジ関数に対する制限」を参照してください。

status

HTTP ステータスコード 。ステータスコードを文字列として指定します。CloudFront は、提供されているステータスコードを、以下に使用します。

status の値が 200～599 の範囲にない場合、CloudFront はエラーをビューワーに返します。

statusDescription

CloudFront がレスポンスで HTTP ステータスコードに付けて返す説明。標準の説明 (HTTP ステータスコード 200 の場合の OK など) を使用する必要はありません。

エラー

生成された HTTP レスポンスで発生する可能性があるエラーを以下に示します。

レスポンスに本文が含まれ、ステータスに 204 (No Content) が指定されている

関数がビューワーリクエストによってトリガーされると、CloudFront は、以下の両方が当てはまる場合に、HTTP 502 ステータスコード (Bad Gateway) をビューワーに返します。

  • status の値が 204 (No Content) である。

  • このレスポンスに body の値が含まれている。

これは、HTTP 204 レスポンスにはメッセージ本文を含める必要がないことを述べている RFC 2616 のオプションの制限を Lambda@Edge が適用しているためです。

生成されるレスポンスのサイズ制限を超えている

Lambda 関数によって生成されるレスポンスの最大サイズは、関数をトリガーするイベントによって異なります。

  • ビューワーリクエストイベント - 40 KB

  • オリジンリクエストイベント - 1 MB

レスポンスがこの許容サイズを超えると、CloudFront が HTTP 502 ステータスコード (Bad Gateway) をビューワーに返します。

必須フィールド

status フィールドは必須です。

その他のすべてのフィールドはオプションです。

オリジンレスポンストリガーでの HTTP レスポンスを更新する

CloudFront がオリジンサーバーから HTTP レスポンスを受け取ったときに、キャッシュ動作に関連付けられた origin-response トリガーがあれば、HTTP レスポンスを変更して、オリジンから返されたものを上書きできます。

以下に示しているのは、HTTP レスポンスを更新する一般的なシナリオです。

注記

関数は 200 と 599 の間 (両端を含む) のステータス値を返す必要があります。そうでない場合、CloudFront はエラーをビューワーに返します。

ビューワーとオリジンのリクエストイベントの HTTP レスポンスを置き換えることもできます。詳細については、「リクエストトリガーでの HTTP レスポンスを生成する」を参照してください。

HTTP レスポンスを使用する場合、Lambda@Edge は、オリジンサーバーから返された本文を origin-response トリガーに公開しません。必要な値に設定することで静的なコンテンツ本文を生成したり、値を空に設定することで関数内の本文を削除したりできます。関数内の本文フィールドを更新しない場合は、オリジンサーバーによって返された元の本文がビューワーに返されます。

include body オプションを選択してリクエストボディにアクセスする

書き込み可能な HTTP メソッド (POST、PUT、DELETE など) のリクエストのボディを Lambda@Edge で公開することを選択できるため、Lambda 関数でそのボディにアクセスできます。読み取り専用アクセスを選択することも、ボディを置き換えることを指定することもできます。

このオプションを有効にするには、ビューワーリクエストやオリジンリクエストイベントのために関数に CloudFront トリガーを作成するとき、[ボディを含める] を選択します。詳細については、「Lambda@Edge 関数のトリガーを追加する」を参照してください。または、関数で [ボディを含める] を使用する方法については、「Lambda@Edge イベント構造」を参照してください。

この機能を使用する場合のシナリオには次のようなものがあります。

  • お客様の入力データをオリジンサーバーに返送することなく、「お問い合わせ」フォームのようなウェブフォームを処理します。

  • ビューワーブラウザによって送信されるウェブビーコンデータを収集し、エッジで処理します。

サンプルコードについては、「Lambda@Edge 関数の例」を参照してください。

注記

リクエストボディが大きい場合は、Lambda@Edge によって切り捨てられます。最大サイズ制限と切り捨ての詳細については、「[本文を含める] オプションを使用する場合のリクエスト本文に対する制限」を参照してください。