メニュー
Amazon CloudFront
開発者ガイド (API Version 2016-09-29)

イベントの構造

このセクションの例では、CloudFront がトリガー時に Lambda@Edge 関数に対して受け渡すリクエストイベントとレスポンスイベントを示しています。

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

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

CloudFront のオリジンリクエストイベントで、イベント構造のオリジン要素には、パスパターンに基づいてリクエストがルーティングされる Amazon S3 またはカスタムオリジンに関する情報が含まれます。リクエストを別のオリジンにルーティングするように、オリジンオブジェクトの値を更新できます。オリジンはディストリビューションで定義する必要はなく、Amazon S3 オリジンオブジェクトをカスタムオリジンオブジェクトに、またはその逆に置き換えることができます。

1 つのリクエストでカスタムオリジンまたは Amazon S3 オリジンのいずれかを指定できますが、両方を指定することはできません。

リクエストイベント

以下に示しているのは、CloudFront のビューワーリクエストイベントまたはオリジンリクエストイベントによって関数がトリガーされた場合に CloudFront から Lambda 関数に渡されるイベントオブジェクトの形式です。

{ "Records": [ { "cf": { "config": { "distributionId": "EDFDVBD6EXAMPLE", "requestId": "MRVMF7KydIvxMWfJIglgwHQwZsbG2IhRJ07sn9AkKUFSHS9EXAMPLE==" }, "request": { "clientIp": "2001:0db8:85a3:0:0:8a2e:0370:7334", "method": "GET", "querystring": "size=large", "headers": { "host": [ { "key": "Host", "value": "d111111abcdef8.cloudfront.net" } ], "user-agent": [ { "key": "User-Agent", "value": "curl/7.51.0" } ] }, "origin": { "custom": { "customHeaders": { "my-origin-custom-header": [ { "key": "My-Origin-Custom-Header", "value": "Test" } ] }, "domainName": "example.com", "keepaliveTimeout": 5, "path": "/custom_path", "port": 443, "protocol": "https", "readTimeout": 5, "sslProtocols": [ "TLSv1", "TLSv1.1" ] }, "s3": { "authMethod": "origin-access-identity", "customHeaders": { "my-origin-custom-header": [ { "key": "My-Origin-Custom-Header", "value": "Test" } ] }, "domainName": "my-bucket.s3.amazonaws.com", "path": "/s3_path", "region": "us-east-1" } } }, "uri": "/picture.jpg" } } ] }

リクエストイベントには次の値が含まれます。

設定値

distributionID (読み取り専用)

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

requestId (読み取り専用、ビューワーリクエストイベントのみ)

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

リクエスト値 - 全般

clientIp (読み取り専用)

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

headers (読み書き)

リクエストのヘッダー。headers オブジェクトのキーは、HTTP リクエストのヘッダー名を小文字にしたものです。これらの小文字のキーにより、大文字と小文字を区別せずにヘッダー値にアクセスできます。各ヘッダー (headers["accept"]headers["host"] など) は、キーと値のペアの配列です。key は、HTTP リクエストに含まれる、大文字と小文字が区別されるヘッダー名です。value はヘッダー値です。配列の要素の数は、ヘッダーが HTTP リクエストに出現する回数です。

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

method (読み取り専用)

ビューワーリクエストの HTTP メソッド。

querystring

ビューワーリクエストで CloudFront が受け取ったクエリ文字列 (存在する場合)。ビューワーリクエストにクエリ文字列が含まれていない場合でも、イベントの構造には空の値で querystring が含まれています。クエリ文字列の詳細については、「クエリ文字列パラメータに基づいてキャッシュするように CloudFront を設定する」を参照してください。

uri (読み書き)

リクエストされたオブジェクトの相対パス。次の点に注意してください。

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

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

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

リクエスト値 - カスタムオリジン

1 つのリクエストでカスタムオリジンまたは Amazon S3 オリジンのいずれかを指定できますが、両方を指定することはできません。

customHeaders

各カスタムヘッダーの名前と値のペアを指定することで、カスタムヘッダーをリクエストに含めることができます。元のカスタムヘッダーまたはフックにブラックリストに登録されたヘッダーを追加することはできず、同じ名前のヘッダーは request.headers または request.origin.custom.customHeaders に存在することはできません。request.headers の制限はカスタムヘッダーにも適用されます。詳細については、「CloudFront がオリジンに転送できないカスタムヘッダー」および「ブラックリストに記載されているヘッダー」を参照してください。

domainName

オリジンサーバーのドメイン名 (www.example.com など)。ドメイン名は、空にすることはできず、コロン (:) を含めることはできません。また、IPV4 アドレス形式を使用できません。ドメイン名の最大長は 253 文字です。

keepaliveTimeout

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

パス

リクエストでコンテンツを検索するサーバーのディレクトリパス。パスはスラッシュ (/) で始める必要がありますが、末尾に / (パス/ など) は不要です。パスは URL でエンコードされ、最大長は 255 文字であることが必要です。

port

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

プロトコル

オリジンからオブジェクトをフェッチするときに CloudFront が使用するオリジンプロトコルポリシー。ここには、http または https が表示されます。

readTimeout

CloudFront がリクエストをオリジンに転送してからレスポンスを待つ期間と、CloudFront がレスポンスパケットを受け取ってから次のパケットを受け取るまで待つ期間 (秒単位)。値は 4 〜 60 秒の範囲の数値であることが必要です。

sslProtocols

オリジンで HTTPS 接続を確立するときに CloudFront が使用できる SSL プロトコル。値には TLSv1.2TLSv1.1TLSv1SSLv3 を指定できます。

リクエスト値 - Amazon S3 オリジン

1 つのリクエストでカスタムオリジンまたは Amazon S3 オリジンのいずれかを指定できますが、両方を指定することはできません。

authMethod

Amazon S3 バケットにオリジンアクセスアイデンティティ (OAI) を設定している場合は origin-access-identity に、OAI を使用していない場合は none に設定します。authMethod を origin-access-identity に設定する場合は、いくつかの要件があります。

  • ヘッダーでリージョンを指定する必要があります。

  • Amazon S3 オリジンを別のものに切り替えるときには、同じ OAI を使用する必要があります。

  • カスタムオリジンから Amazon S3 オリジンに切り替えるときには、OAI を使用できません。

OAI の使用の詳細については、「オリジンアクセスアイデンティティを使用して Amazon S3 コンテンツへのアクセスを制限する」を参照してください。

customHeaders

各カスタムヘッダーの名前と値のペアを指定することで、カスタムヘッダーをリクエストに含めることができます。元のカスタムヘッダーまたはフックにブラックリストに登録されたヘッダーを追加することはできず、同じ名前のヘッダーは request.headers または request.origin.custom.customHeaders に存在することはできません。request.headers の制限はカスタムヘッダーにも適用されます。詳細については、「CloudFront がオリジンに転送できないカスタムヘッダー」および「ブラックリストに記載されているヘッダー」を参照してください。

domainName

Amazon S3 オリジンサーバーのドメイン名 (my-bucket.s3.amazonaws.com など)。ドメイン名は空にすることはできません。許可されたバケット名 (Amazon S3 で定義) であることが必要です。この名前は最大 128 文字で、すべて小文字であることが必要です。

パス

リクエストでコンテンツを検索するサーバーのディレクトリパス。パスはスラッシュ (/) で始める必要がありますが、末尾に / (パス/ など) は不要です。

リージョン

Amazon S3 バケットのリージョン。これは、OAI を使用する場合にのみ必要です。

レスポンスイベント

以下に示しているのは、CloudFront のビューワーレスポンスイベントまたはオリジンレスポンスイベントによって関数がトリガーされた場合に CloudFront から Lambda 関数に渡されるイベントオブジェクトの形式です。

{ "Records": [ { "cf": { "config": { "distributionId": "EDFDVBD6EXAMPLE", "requestId": "xGN7KWpVEmB9Dp7ctcVFQC4E-nrcOcEKS3QyAez--06dV7TEXAMPLE==" }, "request": { "clientIp": "2001:0db8:85a3:0:0:8a2e:0370:7334", "method": "GET", "uri": "/picture.jpg", "querystring": "size=large", "headers": { "host": [ { "key": "Host", "value": "d111111abcdef8.cloudfront.net" } ], "user-agent": [ { "key": "User-Agent", "value": "curl/7.18.1" } ] } }, "response": { "status": "200", "statusDescription": "OK", "headers": { "server": [ { "key": "Server", "value": "MyCustomOrigin" } ], "set-cookie": [ { "key": "Set-Cookie", "value": "theme=light" }, { "key": "Set-Cookie", "value": "sessionToken=abc123; Expires=Wed, 09 Jun 2021 10:18:14 GMT" } ] } } } } ] }

レスポンスイベントには、対応するリクエストイベントに表示される値と、さらに以下の値が含まれます。Lambda@Edge 関数が HTTP レスポンスを生成する場合は、「リクエストトリガーでの HTTP レスポンスの生成」を参照してください。

distributionID (読み取り専用)

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

ヘッダ

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

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

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

  • HTTP リクエストに表示されるヘッダーの大文字と小文字を区別する名前として key を指定します (accepthost など)。

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

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

requestId (読み取り専用、ビューワーレスポンスイベントのみ)

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

request – 次のいずれかです。
  • ビューワーのレスポンス – CloudFront がビューワーから受け取ったリクエスト。ビューワーリクエストイベントによってトリガーされた Lambda 関数によって変更されている可能性があります。

  • オリジンのレスポンス – CloudFront がオリジンに転送したリクエスト。オリジンリクエストイベントによってトリガーされた Lambda 関数によって変更されている可能性があります。

Lambda 関数によってリクエストオブジェクトが変更された場合、その変更は無視されます。

response – 次のいずれかです。
  • ビューワーのレスポンス – CloudFront がビューワーレスポンスイベントでビューワーに返すレスポンス.

  • オリジンのレスポンス – CloudFront がオリジンレスポンスイベントでオリジンから受け取ったレスポンス.

status

CloudFront がビューワーに返す HTTP ステータスコード。

statusDescription

CloudFront がビューワーに返す HTTP ステータスの説明。