リクエストトリガーでの HTTP レスポンスの生成 - Amazon CloudFront
プログラミングモデル

リクエストトリガーでの 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 は、提供されているステータスコードを、以下に使用します。

  • レスポンスでの返却

  • オリジンリクエストイベントによってトリガーされた関数によってレスポンスが生成されたときの、CloudFront エッジキャッシュへの保存

  • 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 フィールドは必須です。

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