在请求触发器中生成 HTTP 响应 - Amazon CloudFront
编程模型
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

在请求触发器中生成 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 (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"]）是一个键值对数组。对于一个指定标头，数组为生成的响应中的每个值包含一个键值对。

  • key（可选）是显示在 HTTP 请求中的标头名称，区分大小写；例如 accept 或 host。

  • 指定 value 作为标头值。

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

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

    在本示例中，Lambda@Edge 创建以下标头键：Content-Type。

有关标头使用情况限制的信息，请参阅边缘函数的限制。

status

HTTP 状态代码。以字符串形式提供状态代码。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 状态代码（无效网关）。

必填字段

status 字段为必填项。

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