Amazon CloudFront
开发人员指南 (API 版本 2016-09-29)
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

Lambda@Edge 事件结构

此部分中的示例显示在触发时,CloudFront 传递到或者从 Lambda@Edge 函数返回的请求和响应事件。

基于内容的动态源选择

您可以在缓存行为中使用路径模式,根据所请求对象的路径和名称将请求路由到源,例如 images/*.jpg。使用 Lambda@Edge,您也可以基于其他特征将请求路由到源,例如请求标头中的值。

在多种情况下,这种基于内容的动态源选择会非常有用。例如,您可以跨不同地理区域中的源分配请求,帮助实现全球负载均衡。或者,您可以选择性地将请求路由到不同的源,每个服务器提供特定功能:自动程序处理、SEO 优化、身份验证等。有关演示如何使用此功能的代码示例,请参阅基于内容的动态源选择的示例函数

在 CloudFront 源请求事件中,根据路径模式,事件结构中的源元素包含有关将请求路由到的 Amazon S3 或自定义源的信息。您可以更新源对象中的值,将请求路由到不同的源。源不需要在分配中定义,您可以将 Amazon S3 源对象替换为自定义源对象,反之亦然。

您可以在单个请求中指定自定义源或 Amazon S3 源,但不能同时指定两者。

请求事件

以下是在 CloudFront 查看器请求事件或源请求事件触发 Lambda 函数时,CloudFront 传递给该函数的事件对象的格式:

{ "Records": [ { "cf": { "config": { "distributionDomainName": "d123.cloudfront.net", "distributionId": "EDFDVBD6EXAMPLE", "eventType": "viewer-request", "requestId": "MRVMF7KydIvxMWfJIglgwHQwZsbG2IhRJ07sn9AkKUFSHS9EXAMPLE==" }, "request": { "body": { "action": "read-only", "data": "eyJ1c2VybmFtZSI6IkxhbWJkYUBFZGdlIiwiY29tbWVudCI6IlRoaXMgaXMgcmVxdWVzdCBib2R5In0=", "encoding": "base64", "inputTruncated": false }, "clientIp": "2001:0db8:85a3:0:0:8a2e:0370:7334", "querystring": "size=large", "uri": "/picture.jpg", "method": "GET", "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" } } } } } ] }

请求事件包括如下值:

配置值

distributionDomainName (只读)

与请求关联的分配的域名。

distributionID (只读)

与请求关联的分配的 ID。

eventType (只读)

与请求关联的触发器的类型。

requestId (只读,仅限查看器请求事件)

唯一能识别请求的加密字符串。requestId 值还在 CloudFront 访问日志中显示为 x-edge-request-id。有关更多信息,请参阅 配置和使用访问日志Web 分配日志文件的格式

请求值 - 常规

clientIp (只读)

发出请求的查看器的 IP 地址。如果查看器使用 HTTP 代理或负载均衡器发送请求,则值为该代理或负载均衡器的 IP 地址。

headers (读/写)

请求中的标头。请注意以下几点:

  • headers 对象中的键为标准 HTTP 请求标头名称的小写版本。使用小写键可为您提供对标头值的不区分大小写的访问权限。

  • 每个标头 (例如,headers["accept"]headers["host"]) 是一个键值对数组。对于一个指定标头,数组为生成的响应中的每个值包含一个键值对。

  • key(可选)是显示在 HTTP 请求中的标头名称,区分大小写;例如 accepthost

  • 指定 value 作为标头值。

  • 如果您不包括键值对的标头键部分,Lambda@Edge 将使用您提供的标头名称自动插入标头键。无论您如何格式化标头名称,自动插入的标头键都将通过对每个部分使用首字母大写方式(用连字符 (-) 分隔)来格式化。

    例如,您可以不带标头键添加标头,如下所示:'content-type': [{ value: 'text/html;charset=UTF-8' }]

    在本示例中,Lambda@Edge 创建以下标头键:Content-Type

有关标头使用情况限制的信息,请参阅标头

method (只读)

查看器请求的 HTTP 方法。

querystring

CloudFront 在查看器请求中收到的查询字符串 (如果有)。如果查看器请求中没有包括查询字符串,则事件结构仍包括使用空值的 querystring。有关查询字符串的更多信息,请参阅 根据查询字符串参数缓存内容

uri (读/写)

所请求对象的相对路径。请注意以下几点:

  • 新的相对路径必须以斜杠开头 (例如:/)。

  • 如果函数更改请求的 URI,则这样会更改查看器请求的对象。

  • 如果某个函数更改请求的 URI,则这样不会更改该请求或该请求转发到的源的缓存行为。

请求值 - 正文

inputTruncated(只读)

一个布尔值标记,它指示 Lambda@Edge 是否截断正文。有关更多信息,请参阅具有“包含正文”选项的正文的大小限制

action(读/写)

您打算对正文执行的操作。action 选项如下所示:

  • read-only:这是默认值。在从 Lambda 函数返回响应时,如果 action 是只读的,Lambda@Edge 将忽略对 encodingdata 的任何更改。

  • replace:如果要替换发送到源的正文,请指定该选项。

encoding(读/写)

正文的编码。在 Lambda@Edge 向 Lambda 函数公开正文时,它先将正文转换为 base64 编码。如果您为 action 选择 replace 以替换正文,您可以选择使用 textbase64(默认)编码。

如果您将 encoding 指定为 base64,但正文不是有效的 base64,CloudFront 将返回错误。

data(读/写)

请求正文内容。

请求值 - 自定义源

您可以在单个请求中指定自定义源或 Amazon S3 源,但不能同时指定两者。

customHeaders

您可以通过为每个自定义标头指定标头名称/值对,在请求中包括自定义标头。您不能为源自定义标头或钩子添加黑名单中的标头,并且 request.headers 或 request.origin.custom.customHeaders 中不能存在同名的标头。对 request.headers 的限制也适用于自定义标头。有关更多信息,请参阅CloudFront 无法转发到源的自定义标头列入黑名单的标头

domainName

源服务器的域名,例如 www.example.com。域名不能为空,不能包含冒号 (:),并且不能使用 IPV4 地址格式。域名最多可以有 253 个字符。

keepaliveTimeout

CloudFront 在接收最后一个响应数据包后应尝试与源保持连接的秒数。该值应该是在 1 到 60 秒之间的数字。

path

服务器上的目录路径,请求应在其中查找内容。路径应该以斜杠 (/) 开头,但不能有尾随 / (例如 path/)。路径应为 URL 编码,最大长度为 255 个字符。

port (远程调试端口)

自定义源上的端口。端口必须为 80 或 443,或者是在 1024 到 65535 之间的数字。

协议(仅源请求)

CloudFront 从源提取对象时应使用的源协议策略。该值可以是 httphttps

readTimeout

CloudFront 在将请求转发到源之后应等待的秒数,以及 CloudFront 在接收一个响应数据包之后并在接收下一个数据包之前应等待的秒数。该值应该是在 4 到 60 秒之间的数字。

sslProtocols

CloudFront 在建立与源的 HTTPS 连接时可使用的 SSL 协议。应为以下值:TLSv1.2TLSv1.1TLSv1SSLv3

请求值 - Amazon S3 源

您可以在单个请求中指定自定义源或 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 的定义)。请勿使用特定于区域的终端节点(如 my-bucket.s3-eu-west-1.amazonaws.com)。名称必须最多为 128 个字符,并且必须为全小写。

path

服务器上的目录路径,请求应在其中查找内容。路径应该以斜杠 (/) 开头,但不能有尾随 / (例如 path/)。

region

Amazon S3 存储桶所在的区域。只有在使用 OAI 时必需。

响应事件

以下是在 CloudFront 查看器响应事件或源响应事件触发 Lambda 函数时,CloudFront 传递给该函数的事件对象的格式:

{ "Records": [ { "cf": { "config": { "distributionDomainName": "d123.cloudfront.net", "distributionId": "EDFDVBD6EXAMPLE", "eventType": "viewer-response", "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。

eventType (只读)

与响应关联的触发器的类型。

headers

您希望 CloudFront 在生成的响应中返回的标头。请注意以下几点:

  • headers 对象中的键为标准 HTTP 请求标头名称的小写版本。使用小写键可为您提供对标头值的不区分大小写的访问权限。

  • 每个标头 (例如,headers["accept"]headers["host"]) 是一个键值对数组。对于一个指定标头,数组为生成的响应中的每个值包含一个键值对。

  • key(可选)是显示在 HTTP 请求中的标头名称,区分大小写;例如 accepthost

  • 指定 value 作为标头值。

  • 如果您不包括键值对的标头键部分,Lambda@Edge 将使用您提供的标头名称自动插入标头键。无论您如何格式化标头名称,自动插入的标头键都将通过对每个部分使用首字母大写方式(用连字符 (-) 分隔)来格式化。

    例如,您可以不带标头键添加标头,如下所示:'content-type': [{ value: 'text/html;charset=UTF-8' }]

    在本示例中,Lambda@Edge 创建以下标头键:Content-Type

有关标头使用情况限制的信息,请参阅标头

requestId (只读,仅限查看器响应事件)

唯一能识别请求的加密字符串。requestId 值还在 CloudFront 访问日志中显示为 x-edge-request-id。有关更多信息,请参阅 配置和使用访问日志Web 分配日志文件的格式

request – 为以下项之一:
  • 查看器请求 – CloudFront 从查看器中收到的请求,以及查看器请求事件触发的 Lambda 函数可能已修改的请求

  • 源请求 – CloudFront 转发到源的请求,以及源请求事件触发的 Lambda 函数可能已修改的请求

如果 Lambda 函数修改请求对象,则会忽略相应更改。

response – 为以下项之一:
  • 查看器响应 – CloudFront 将针对查看器响应事件返回到查看器的响应。

  • 源响应 – CloudFront 针对源响应事件从源收到的响应。

status

CloudFront 返回到查看器的 HTTP 状态代码。

statusDescription

CloudFront 返回到查看器的 HTTP 状态说明。