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

在请求触发器中生成 HTTP 响应

在 CloudFront 收到请求时,您可以使用 Lambda 函数生成 CloudFront 直接返回到查看器的 HTTP 响应,而无需将响应转发到源。生成 HTTP 响应会减少源上的负载,通常也可以减少查看器的延迟。

生成 HTTP 响应的一些常见情况包括:

  • 将小网页返回到查看器

  • 返回 HTTP 301 或 302 状态代码将用户重定向到其他网页

  • 用户未通过身份验证时向查看器返回 HTTP 401 状态代码

出现以下 CloudFront 事件时,Lambda@Edge 函数可以生成 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', statusDescription: 'status description' };

响应对象可包括以下值:

body

您希望 CloudFront 在生成的响应中返回的正文 (如果有)。

bodyEncoding

您在 body 中指定的值的编码。有效编码仅为 textbase64。如果您在 response 对象中包含 body 但省略 bodyEncoding,CloudFront 将正文视为文本。

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

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

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

status

您希望 CloudFront 用于以下情况的 HTTP 状态代码:

  • 在响应中返回

  • 当从由源请求事件触发的函数生成响应时,缓存在 CloudFront 边缘缓存中

  • 登录到 CloudFront 配置和使用访问日志

如果 status 值不在 200 到 599 之间,CloudFront 将向查看器返回错误。

statusDescription

您希望 CloudFront 在响应中随 HTTP 状态代码一起返回的说明。无需使用标准说明,例如为 HTTP 状态代码 200 使用 OK

错误

以下是所生成的 HTTP 响应可能的错误。

响应包含正文并为状态指定了 204 (无内容)

当函数由查看器请求触发时,如果满足以下情况,则 CloudFront 返回 HTTP 502 状态代码 (错误网关) 到查看器:

  • status 的值为 204 (无内容)

  • 响应包括 body 的值

这是因为 Lambda@Edge 会施加 RFC 2616 中介绍的可选限制,其中指出 HTTP 204 响应不需要包含消息正文。

生成响应的大小限制

由 Lambda 函数生成的响应的最大大小 (包括标头和正文) 取决于触发该函数的事件:

  • 查看器请求事件 – 40 KB

  • 源请求事件 – 1 MB

如果响应大于允许的大小,则 CloudFront 会向查看器返回 HTTP 502 状态代码 (Bad Gateway)。

必填字段

status 字段为必填项。

所有其他字段均为可选字段。

本页内容: