Lambda@Edge イベント構造 - Amazon CloudFront

Lambda@Edge イベント構造

以下のトピックでは、Lambda@Edge 関数がトリガーされたときにその関数に CloudFront が渡すリクエストおよびレスポンスイベントオブジェクトについて説明します。

動的オリジン選択

キャッシュ動作でパスパターンを使用すると、リクエストされたオブジェクトのパスと名前 (images/*.jpg など) に基づいて、リクエストをオリジンにルーティングできます。Lambda@Edge を使用すると、リクエストヘッダーの値など他のプロパティに基づいても、リクエストをオリジンにルーティングできます。

この動的オリジン選択が便利な状況がいくつかあります。たとえば、グローバルな負荷分散に役立つように、地理的に異なるリージョンのオリジンにリクエストを分散させる場合です。あるいは、機能 (ボット処理、SEO 最適化、認証など) が異なるさまざまなオリジンに、リクエストを選択的にルーティングする場合です。この機能の使用方法を示すコードサンプルについては、「コンテンツベースの動的オリジンの選択 - 例」を参照してください。

CloudFront のオリジンリクエストイベントで、イベント構造の origin オブジェクトには、パスパターンに基づいてリクエストがルーティングされるオリジンに関する情報が含まれます。リクエストを別のオリジンにルーティングするように、origin オブジェクトの値を更新できます。origin オブジェクトを更新するときに、ディストリビューションのオリジンを定義する必要はありません。Amazon S3 オリジンオブジェクトをカスタムオリジンオブジェクトに置き換えたり、その逆にすることもできます。ただし、カスタムオリジンと Amazon S3 オリジンのどちらか (両府は不可) を通じて、リクエストごとに 1 つのオリジンしか指定できません。

リクエストイベント

以下のトピックでは、ビューワーおよびオリジンリクエストイベントの Lambda 関数に CloudFront が渡すオブジェクトの構造を示します。これらの例は、本文のない GET リクエストを示しています。例に続いて、ビューワーとオリジンリクエストイベントで使用可能なすべてのフィールドのリストを示します。

ビューワーリクエストの例

次の例は、ビューワーリクエストイベントオブジェクトを示しています。

{ "Records": [ { "cf": { "config": { "distributionDomainName": "d111111abcdef8.cloudfront.net", "distributionId": "EDFDVBD6EXAMPLE", "eventType": "viewer-request", "requestId": "4TyzHTaYWb1GX1qTfsHhEqV6HUDd_BzoBZnwfnvQc_1oF26ClkoUSEQ==" }, "request": { "clientIp": "203.0.113.178", "headers": { "host": [ { "key": "Host", "value": "d111111abcdef8.cloudfront.net" } ], "user-agent": [ { "key": "User-Agent", "value": "curl/7.66.0" } ], "accept": [ { "key": "accept", "value": "*/*" } ] }, "method": "GET", "querystring": "", "uri": "/" } } } ] }

オリジンリクエストの例

次の例は、オリジンリクエストイベントオブジェクトを示しています。

{ "Records": [ { "cf": { "config": { "distributionDomainName": "d111111abcdef8.cloudfront.net", "distributionId": "EDFDVBD6EXAMPLE", "eventType": "origin-request", "requestId": "4TyzHTaYWb1GX1qTfsHhEqV6HUDd_BzoBZnwfnvQc_1oF26ClkoUSEQ==" }, "request": { "clientIp": "203.0.113.178", "headers": { "x-forwarded-for": [ { "key": "X-Forwarded-For", "value": "203.0.113.178" } ], "user-agent": [ { "key": "User-Agent", "value": "Amazon CloudFront" } ], "via": [ { "key": "Via", "value": "2.0 2afae0d44e2540f472c0635ab62c232b.cloudfront.net (CloudFront)" } ], "host": [ { "key": "Host", "value": "example.org" } ], "cache-control": [ { "key": "Cache-Control", "value": "no-cache, cf-no-cache" } ] }, "method": "GET", "origin": { "custom": { "customHeaders": {}, "domainName": "example.org", "keepaliveTimeout": 5, "path": "", "port": 443, "protocol": "https", "readTimeout": 30, "sslProtocols": [ "TLSv1", "TLSv1.1", "TLSv1.2" ] } }, "querystring": "", "uri": "/" } } } ] }

リクエストイベントフィールド

リクエストイベントオブジェクトデータは、config (Records.cf.config) と request (Records.cf.request) の 2 つのサブオブジェクトに含まれています。次のリストでは、各サブオブジェクトのフィールドについて説明します。

設定オブジェクトのフィールド

次のリストでは、config オブジェクト (Records.cf.config) のフィールドについて説明します。

distributionDomainName (読み取り専用)

リクエストに関連付けられているディストリビューションのドメイン名。

distributionID (読み取り専用)

リクエストに関連付けられているディストリビューションの ID。

eventType (読み取り専用)

リクエストに関連付けられているトリガーのタイプ (viewer-request または origin-request)。

requestId (読み取り専用)

ビューワーから CloudFront へのリクエストを一意に識別する暗号化された文字列。requestId の値は CloudFront アクセスログにも x-edge-request-id として表示されます。詳細については、「アクセスログの設定および使用」および「ウェブディストリビューションのログファイル形式」を参照してください。

リクエストオブジェクトのフィールド

次のリストでは、request オブジェクト (Records.cf.request) のフィールドについて説明します。

clientIp (読み取り専用)

リクエストを行ったビューワーの IP アドレス。ビューワーが HTTP プロキシまたはロードバランサーを使用してリクエストを送った場合、この値はプロキシまたはロードバランサーの IP アドレスです。

headers (読み書き)

リクエストのヘッダー。次の点に注意してください。

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

  • 各ヘッダーオブジェクト (headers["accept"]headers["host"] など) はキーと値のペアの配列です。返されたヘッダーの配列には、リクエストの値ごとに 1 つのキーと値のペアが含まれます。

  • key には、HTTP リクエストに表示されるヘッダーの大文字と小文字を区別する名前が含まれます (HostUser-AgentX-Forwarded-For など)。

  • value には、HTTP リクエストに表示されるヘッダー値が含まれます。

  • Lambda 関数がリクエストヘッダーを追加または変更し、ヘッダー key フィールドを含めない場合、Lambda@Edge は指定したヘッダー名を使用してヘッダー key を自動的に挿入します。ヘッダー名をどのようにフォーマットしたかにかかわらず、自動的に挿入されるヘッダーキーは、各パートの先頭の大文字がハイフン (-) で区切られてフォーマットされます。

    たとえば、ヘッダー key なしで次のようなヘッダーを追加できます。

    "user-agent": [ { "value": "ExampleCustomUserAgent/1.X.0" } ]

    この例では、Lambda@Edge は "key": "User-Agent" を自動的に挿入します。

ヘッダー使用の制限の詳細については、「ヘッダー」を参照してください。

method (読み取り専用)

リクエストの HTTP メソッド。

querystring (読み書き)

リクエスト内のクエリ文字列 (存在する場合)。リクエストにクエリ文字列が含まれていない場合でも、イベントオブジェクトには空の値で querystring が含まれています。クエリ文字列の詳細については、「クエリ文字列パラメータに基づくコンテンツのキャッシュ」を参照してください。

uri (読み書き)

リクエストされたオブジェクトの相対パス。Lambda 関数が uri 値を変更する場合、次の点に注意してください。

  • 新しい uri 値は、スラッシュ (/) で始める必要があります。

  • 関数で uri 値を変更すると、ビューワーがリクエストしているオブジェクトが変更されます。

  • 関数で uri 値を変更しても、リクエストのキャッシュ動作や送信先オリジンは変わりません

body (読み書き)

HTTP リクエストの本文。body 構造には、次のフィールドを含めることができます。

inputTruncated (読み取り専用)

本文が Lambda@Edge で切り捨てられたかどうかを示すブーリアン型フラグ。詳細については、「Include Body オプションがあるリクエストボディのサイズクォータ」を参照してください。

action (読み書き)

本文で実行する予定のアクション。action のオプションは次のとおりです。

  • read-only: これがデフォルト値です。Lambda 関数からレスポンスを返す際に、action が読み取り専用の場合、Lambda@Edge は encoding または data への変更をすべて無視します。

  • replace: オリジンに送信される本文を置き換えるときに指定します。

encoding (読み書き)

本文のエンコード。Lambda@Edge が Lambda 関数に本文を公開すると、まず本文を base64-encoding に変換します。本文を置き換える action として replace を選択した場合、base64 (デフォルト) または text エンコードを使用することもできます。encodingbase64 と指定したが本文が有効な base64 でない場合、CloudFront はエラーを返します。

data (読み書き)

リクエストボディのコンテンツ。

origin (読み書き) (オリジンイベントのみ)

リクエストの送信先のオリジン。origin 構造には、オリジンが 1 つだけ含まれていなければなりません。オリジンはカスタムオリジンでも Amazon S3 オリジンでも構いません。オリジン構造には、次のフィールドを含めることができます。

customHeaders (読み書き) (カスタムオリジンと Amazon S3 オリジン)

各カスタムヘッダーの名前と値のペアを指定することで、カスタムヘッダーをリクエストに含めることができます。ブラックリストに載っているヘッダーを追加することはできません。また、同じ名前のヘッダーを Records.cf.request.headers に含めることはできません。リクエストヘッダーに関する注意事項は、カスタムヘッダーにも適用されます。詳細については、「CloudFront がオリジンリクエストに追加できないカスタムヘッダー」および「ブラックリストに記載されているヘッダー」を参照してください。

domainName (読み書き) (カスタムオリジンと Amazon S3 オリジン)

オリジンのドメイン名。ドメイン名を空にすることはできません。

  • カスタムオリジンの場合 – DNS ドメイン名を指定します (www.example.com など)。ドメイン名にコロン (:) を含めることはできません。また、IP アドレスにすることはできません。ドメイン名の最大長は 253 文字です。

  • Amazon S3 オリジンの場合 – Amazon S3 バケットの DNS ドメイン名を指定します (awsexamplebucket.s3.eu-west-1.amazonaws.com など)。この名前は最大 128 文字で、すべて小文字であることが必要です。

path (読み書き) (カスタムオリジンと Amazon S3 オリジン)

リクエストがコンテンツを検索するサーバーのディレクトリパス。パスは、先頭をスラッシュ (/) にする必要があります。末尾をスラッシュ (/) にすることはできません (たとえば、末尾が example-path/ は不可です)。カスタムオリジンの場合のみ、パスは URL エンコードされ、最大長は 255 文字にする必要があります。

keepaliveTimeout (読み書き) (カスタムオリジンのみ)

CloudFront がレスポンスの最後のパケットを受け取ってからオリジンへの接続を維持しようとする期間 (秒)。この値には、1 ~ 60 の範囲の数値を指定する必要があります。

port (読み書き) (カスタムオリジンのみ)

カスタムオリジンでの CloudFront の接続先ポート。ポートは 80 または 443 であるか、1024 〜 65535 の範囲の数値であることが必要です。

protocol (読み書き) (カスタムオリジンのみ)

オリジンに接続するとき CloudFront が使用する接続プロトコル。ここには、http または https が表示されます。

readTimeout (読み書き) (カスタムオリジンのみ)

オリジンにリクエストを送信した後、CloudFront がレスポンスを待機する時間 (秒単位)。これは、レスポンスのパケットを受信してから次のパケットを受信するまで CloudFront が待機する時間も指定します。この値には、4 ~ 60 の範囲の数値を指定する必要があります。

sslProtocols (読み書き) (カスタムオリジンのみ)

オリジンとの HTTPS 接続を確立するときに CloudFront が使用できる最小限の SSL/TLS プロトコル。値は、TLSv1.2TLSv1.1TLSv1、または SSLv3 のいずれかです。

authMethod (読み書き) (Amazon S3 オリジンのみ)

オリジンアクセスアイデンティティ (OAI) を使用している場合は、このフィールドを origin-access-identity に設定し、OAI を使用していない場合は none に設定します。authMethodorigin-access-identity に設定した場合、いくつかの要件があります。

  • region を指定する必要があります (次のフィールドを参照)。

  • リクエストをある Amazon S3 オリジンから別のオリジンに変更する場合は、同じ OAI を使用する必要があります。

  • リクエストをカスタムオリジンから Amazon S3 オリジンに変更する場合、OAI を使用することはできません。

region (読み書き) (Amazon S3 オリジンのみ)

Amazon S3 バケットの AWS リージョン。これは、authMethodorigin-access-identity に設定した場合にのみ必要です。

レスポンスイベント

以下のトピックでは、ビューワーおよびオリジンレスポンスイベントの Lambda 関数に CloudFront が渡すオブジェクトの構造を示します。例に続いて、ビューワーとオリジンレスポンスイベントで使用可能なすべてのフィールドのリストを示します。

オリジンレスポンスの例

次の例は、オリジンレスポンスイベントオブジェクトを示しています。

{ "Records": [ { "cf": { "config": { "distributionDomainName": "d111111abcdef8.cloudfront.net", "distributionId": "EDFDVBD6EXAMPLE", "eventType": "origin-response", "requestId": "4TyzHTaYWb1GX1qTfsHhEqV6HUDd_BzoBZnwfnvQc_1oF26ClkoUSEQ==" }, "request": { "clientIp": "203.0.113.178", "headers": { "x-forwarded-for": [ { "key": "X-Forwarded-For", "value": "203.0.113.178" } ], "user-agent": [ { "key": "User-Agent", "value": "Amazon CloudFront" } ], "via": [ { "key": "Via", "value": "2.0 8f22423015641505b8c857a37450d6c0.cloudfront.net (CloudFront)" } ], "host": [ { "key": "Host", "value": "example.org" } ], "cache-control": [ { "key": "Cache-Control", "value": "no-cache, cf-no-cache" } ] }, "method": "GET", "origin": { "custom": { "customHeaders": {}, "domainName": "example.org", "keepaliveTimeout": 5, "path": "", "port": 443, "protocol": "https", "readTimeout": 30, "sslProtocols": [ "TLSv1", "TLSv1.1", "TLSv1.2" ] } }, "querystring": "", "uri": "/" }, "response": { "headers": { "access-control-allow-credentials": [ { "key": "Access-Control-Allow-Credentials", "value": "true" } ], "access-control-allow-origin": [ { "key": "Access-Control-Allow-Origin", "value": "*" } ], "date": [ { "key": "Date", "value": "Mon, 13 Jan 2020 20:12:38 GMT" } ], "referrer-policy": [ { "key": "Referrer-Policy", "value": "no-referrer-when-downgrade" } ], "server": [ { "key": "Server", "value": "ExampleCustomOriginServer" } ], "x-content-type-options": [ { "key": "X-Content-Type-Options", "value": "nosniff" } ], "x-frame-options": [ { "key": "X-Frame-Options", "value": "DENY" } ], "x-xss-protection": [ { "key": "X-XSS-Protection", "value": "1; mode=block" } ], "content-type": [ { "key": "Content-Type", "value": "text/html; charset=utf-8" } ], "content-length": [ { "key": "Content-Length", "value": "9593" } ] }, "status": "200", "statusDescription": "OK" } } } ] }

ビューワーレスポンスの例

次の例は、ビューワーレスポンスイベントオブジェクトを示しています。

{ "Records": [ { "cf": { "config": { "distributionDomainName": "d111111abcdef8.cloudfront.net", "distributionId": "EDFDVBD6EXAMPLE", "eventType": "viewer-response", "requestId": "4TyzHTaYWb1GX1qTfsHhEqV6HUDd_BzoBZnwfnvQc_1oF26ClkoUSEQ==" }, "request": { "clientIp": "203.0.113.178", "headers": { "host": [ { "key": "Host", "value": "d111111abcdef8.cloudfront.net" } ], "user-agent": [ { "key": "User-Agent", "value": "curl/7.66.0" } ], "accept": [ { "key": "accept", "value": "*/*" } ] }, "method": "GET", "querystring": "", "uri": "/" }, "response": { "headers": { "access-control-allow-credentials": [ { "key": "Access-Control-Allow-Credentials", "value": "true" } ], "access-control-allow-origin": [ { "key": "Access-Control-Allow-Origin", "value": "*" } ], "date": [ { "key": "Date", "value": "Mon, 13 Jan 2020 20:14:56 GMT" } ], "referrer-policy": [ { "key": "Referrer-Policy", "value": "no-referrer-when-downgrade" } ], "server": [ { "key": "Server", "value": "ExampleCustomOriginServer" } ], "x-content-type-options": [ { "key": "X-Content-Type-Options", "value": "nosniff" } ], "x-frame-options": [ { "key": "X-Frame-Options", "value": "DENY" } ], "x-xss-protection": [ { "key": "X-XSS-Protection", "value": "1; mode=block" } ], "age": [ { "key": "Age", "value": "2402" } ], "content-type": [ { "key": "Content-Type", "value": "text/html; charset=utf-8" } ], "content-length": [ { "key": "Content-Length", "value": "9593" } ] }, "status": "200", "statusDescription": "OK" } } } ] }

レスポンスイベントのフィールド

レスポンスイベントオブジェクトデータは、config (Records.cf.config)、request (Records.cf.request)、response (Records.cf.response) の 3 つのサブオブジェクトに含まれています。リクエストオブジェクトのフィールドの詳細については、「リクエストオブジェクトのフィールド」を参照してください。次のリストでは、config および response サブオブジェクトのフィールドについて説明します。

設定オブジェクトのフィールド

次のリストでは、config オブジェクト (Records.cf.config) のフィールドについて説明します。

distributionDomainName (読み取り専用)

レスポンスに関連付けられているディストリビューションのドメイン名。

distributionID (読み取り専用)

レスポンスに関連付けられているディストリビューションの ID。

eventType (読み取り専用)

レスポンスに関連付けられているトリガーのタイプ (origin-response または viewer-response)。

requestId (読み取り専用)

このレスポンスが関連付けられているビューワーから CloudFront へのリクエストを一意に識別する暗号化された文字列。requestId の値は CloudFront アクセスログにも x-edge-request-id として表示されます。詳細については、「アクセスログの設定および使用」および「ウェブディストリビューションのログファイル形式」を参照してください。

レスポンスオブジェクトのフィールド

次のリストでは、response オブジェクト (Records.cf.response) のフィールドについて説明します。Lambda@Edge 関数を使用して HTTP レスポンスを生成する方法については、「リクエストトリガーでの HTTP レスポンスの生成」を参照してください。

headers (読み書き)

レスポンスのヘッダー。次の点に注意してください。

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

  • 各ヘッダーオブジェクト (headers["content-type"]headers["content-length"] など) はキーと値のペアの配列です。返されたヘッダーの配列には、レスポンスの値ごとに 1 つのキーと値のペアが含まれます。

  • key には、HTTP レスポンスに表示されるヘッダーの大文字と小文字を区別する名前が含まれます (Content-TypeContent-Length など)。

  • value には、HTTP レスポンスに表示されるヘッダー値が含まれます。

  • Lambda 関数がレスポンスヘッダーを追加または変更し、ヘッダー key フィールドを含めない場合、Lambda@Edge は指定したヘッダー名を使用してヘッダー key を自動的に挿入します。ヘッダー名をどのようにフォーマットしたかにかかわらず、自動的に挿入されるヘッダーキーは、各パートの先頭の大文字がハイフン (-) で区切られてフォーマットされます。

    たとえば、ヘッダー key なしで次のようなヘッダーを追加できます。

    "content-type": [ { "value": "text/html;charset=UTF-8" } ]

    この例では、Lambda@Edge は "key": "Content-Type" を自動的に挿入します。

ヘッダー使用の制限の詳細については、「ヘッダー」を参照してください。

status

レスポンスの HTTP ステータスコード。

statusDescription

レスポンスの HTTP ステータスの説明。