CloudFront Functions 事件结构

CloudFront Functions 在运行函数时将 event 对象作为输入传递给函数代码。当您测试函数时，可以创建 event 对象并将其传递至您的函数。创建用于测试函数的 event 对象时，您可以省略 context 对象中的 distributionDomainName、distributionId 和 requestId 字段。请确保标头的名称为小写字母，在生产环境中 CloudFront Functions 传递给您的函数的 event 对象中情况总是如此。

下面显示了此事件对象的结构概述。

{
    "version": "1.0",
    "context": {
        <context object>
    },
    "viewer": {
        <viewer object>
    },
    "request": {
        <request object>
    },
    "response": {
        <response object>
    }
}

有关更多信息，请参阅以下主题：

版本字段

version 字段包含一个字符串，用于指定 CloudFront Functions 事件对象的版本。当前版本为 1.0。

Context 对象

context 对象包含有关事件的上下文信息。其中包括以下字段：

查看器对象

viewer 对象包含一个 ip 字段，其值为发送请求的查看器（客户端）的 IP 地址。如果查看器请求来自 HTTP 代理或负载均衡器，则值为该代理或负载均衡器的 IP 地址。

请求对象

request 对象包含查看器至 CloudFront HTTP 请求的表示形式。在传递至您的函数的 event 对象中，request 对象代表 CloudFront 从查看器中接收的实际请求。

如果您的函数代码将 request 对象返回到 CloudFront，则它必须使用相同的结构。

request 对象包含以下字段：

有关查询字符串、标头和 Cookies 结构的更多信息，请参阅 查询字符串、标头或 Cookie 的结构。

有关示例 event 对象，请参阅 示例事件对象。

响应对象

response 对象包含 CloudFront 至查看器 HTTP 响应的表示形式。在传递至您的函数的 event 对象中，response 对象表示 CloudFront 对查看器请求的实际响应。

如果您的函数代码返回一个 response 对象，它必须使用这个相同的结构。

response 对象包含以下字段：

有关修改后的状态代码和正文内容的更多信息，请参阅 状态代码和正文。

有关标头和 Cookies 结构的更多信息，请参阅 查询字符串、标头或 Cookie 的结构。

有关示例 response 对象，请参阅 示例响应对象。

状态代码和正文

使用 CloudFront Functions，您可以更新查看器响应状态代码，将整个响应正文替换为新响应正文，或删除响应正文。在评估来自 CloudFront 缓存或源的响应的各个方面后更新查看器响应的一些常见场景包括：

当您在处理 HTTP 响应时，CloudFront Functions 无权访问响应正文。您可以通过将正文内容设置为所需值来替换正文内容，或者通过将值设置为空来删除正文。如果您不更新函数中的正文字段，CloudFront 缓存或源返回的源正文将返回到查看器。

如果您的 CloudFront 函数配置为返回 400 或以上的 HTTP 错误，则您的查看器将看不到您为相同状态代码指定的自定义错误页面。

查询字符串、标头或 Cookie 的结构

查询字符串、标头和 Cookie 共享同一个结构。查询字符串可以出现在请求中。标头出现在请求和响应中。Cookie 出现在请求和响应中。

每个查询字符串、标头或 Cookie 都是父项 querystring、headers 或 cookies 对象内的唯一字段。字段名称是查询字符串、标头或 Cookie 的名称。每个字段都包含一个 value 属性，并带有查询字符串、标头或 Cookie 的值。

查询字符串值或查询字符串对象

除了查询字符串对象之外，函数还可以返回查询字符串值。查询字符串值可用于按任何自定义顺序排列查询字符串参数。

var request = event.request; 
request.querystring = 'ID=42&Exp=1619740800&TTL=1440&NoValue=&querymv=val1&querymv=val2,val3';

标头的特殊注意事项

仅对于标头，标头名称在事件对象中转换为小写，当您的函数代码添加它们时，标头名称必须为小写。当 CloudFront 函数将事件对象转换回 HTTP 请求或响应时，标头名称中每个单词的第一个字母都会大写。单词由连字符 (-) 分隔。例如，如果您的函数代码添加了名为 example-header-name 的标头，CloudFront 会将其转换为 HTTP 请求或响应中的 Example-Header-Name。

Host: video.example.com

"headers": {
    "host": {
        "value": "video.example.com"
    }
}

var request = event.request;
var host = request.headers.host.value;

var request = event.request;
request.headers['x-custom-header'] = {value: 'example value'};

重复的查询字符串、标头和 Cookies（multiValue 数组）

HTTP 请求或响应可以包含多个具有相同名称的查询字符串、标头或 Cookie。在这种情况下，重复的查询字符串、标头或 Cookie 会折叠为 request 或 response 对象中的一个字段，但此字段包含名为 multiValue 的额外属性。multiValue 属性包含一个数组，其中包含每个重复查询字符串、标头或 Cookies 的值。

Accept: application/json
Accept: application/xml
Accept: text/html

"headers": {
    "accept": {
        "value": "application/json",
        "multiValue": [
            {
                "value": "application/json"
            },
            {
                "value": "application/xml"
            },
            {
                "value": "text/html"
            }
        ]
    }
}

如果函数代码修改具有 multiValue 数组的查询字符串、标头或 Cookie，CloudFront Functions 将使用以下规则来应用更改：

仅当 HTTP 请求或响应中包含重复的查询字符串、标头或具有相同名称的 Cookie 时，才使用 multiValue 属性，如前面的示例所示。但是，如果单个查询字符串、标头或 Cookie 中有多个值，则不使用 multiValue 属性。

Accept: application/json, application/xml, text/html

"headers": {
    "accept": {
        "value": "application/json, application/xml, text/html"
    }
}

Cookie 属性

在 HTTP 响应的 Set-Cookie 标头中，标头包含 Cookie 的名称-值对以及可选的一组用分号分隔的属性。

Set-Cookie: cookie1=val1; Secure; Path=/; Domain=example.com; Expires=Wed, 05 Apr 2021 07:28:00 GMT

"cookie1": {
    "value": "val1",
    "attributes": "Secure; Path=/; Domain=example.com; Expires=Wed, 05 Apr 2021 07:28:00 GMT"
}

示例响应对象

以下示例显示了一个 response 对象（查看器响应函数的输出），其中的正文已被查看器响应函数替换。

{
  "response": {
    "statusCode": 200,
    "statusDescription": "OK",
    "headers": {
      "date": {
        "value": "Mon, 04 Apr 2021 18:57:56 GMT"
      },
      "server": {
        "value": "gunicorn/19.9.0"
      },
      "access-control-allow-origin": {
        "value": "*"
      },
      "access-control-allow-credentials": {
        "value": "true"
      },
      "content-type": {
        "value": "text/html"
      },
      "content-length": {
        "value": "86"
      }
    },
    "cookies": {
      "ID": {
        "value": "id1234",
        "attributes": "Expires=Wed, 05 Apr 2021 07:28:00 GMT"
      },
      "Cookie1": {
        "value": "val1",
        "attributes": "Secure; Path=/; Domain=example.com; Expires=Wed, 05 Apr 2021 07:28:00 GMT",
        "multiValue": [
          {
            "value": "val1",
            "attributes": "Secure; Path=/; Domain=example.com; Expires=Wed, 05 Apr 2021 07:28:00 GMT"
          },
          {
            "value": "val2",
            "attributes": "Path=/cat; Domain=example.com; Expires=Wed, 10 Jan 2021 07:28:00 GMT"
          }
        ]
      }
    },
    
    // Adding the body field is optional and it will not be present in the response object
    // unless you specify it in your function.
    // Your function does not have access to the original body returned by the CloudFront
    // cache or origin.
    // If you don't specify the body field in your viewer response function, the original
    // body returned by the CloudFront cache or origin is returned to viewer.

     "body": {
      "encoding": "text",
      "data": "<!DOCTYPE html><html><body><p>Here is your custom content.</p></body></html>"
    }
  }
}

示例事件对象

以下示例显示了一个完整的 event 对象。这是标准分配（而不是多租户分配）的调用示例。对于多租户分配，使用 endpoint 字段而非 distributionDomainName 字段。endpoint 的值是与事件关联的连接组的 CloudFront 域名（例如 d111111abcdef8.cloudfront.net）。

{
    "version": "1.0",
    "context": {
        "distributionDomainName": "d111111abcdef8.cloudfront.net",
        "distributionId": "EDFDVBD6EXAMPLE",
        "eventType": "viewer-response",
        "requestId": "EXAMPLEntjQpEXAMPLE_SG5Z-EXAMPLEPmPfEXAMPLEu3EqEXAMPLE=="
    },
    "viewer": {"ip": "198.51.100.11"},
    "request": {
        "method": "GET",
        "uri": "/media/index.mpd",
        "querystring": {
            "ID": {"value": "42"},
            "Exp": {"value": "1619740800"},
            "TTL": {"value": "1440"},
            "NoValue": {"value": ""},
            "querymv": {
                "value": "val1",
                "multiValue": [
                    {"value": "val1"},
                    {"value": "val2,val3"}
                ]
            }
        },
        "headers": {
            "host": {"value": "video.example.com"},
            "user-agent": {"value": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:83.0) Gecko/20100101 Firefox/83.0"},
            "accept": {
                "value": "application/json",
                "multiValue": [
                    {"value": "application/json"},
                    {"value": "application/xml"},
                    {"value": "text/html"}
                ]
            },
            "accept-language": {"value": "en-GB,en;q=0.5"},
            "accept-encoding": {"value": "gzip, deflate, br"},
            "origin": {"value": "https://website.example.com"},
            "referer": {"value": "https://website.example.com/videos/12345678?action=play"},
            "cloudfront-viewer-country": {"value": "GB"}
        },
        "cookies": {
            "Cookie1": {"value": "value1"},
            "Cookie2": {"value": "value2"},
            "cookie_consent": {"value": "true"},
            "cookiemv": {
                "value": "value3",
                "multiValue": [
                    {"value": "value3"},
                    {"value": "value4"}
                ]
            }
        }
    },
    "response": {
        "statusCode": 200,
        "statusDescription": "OK",
        "headers": {
            "date": {"value": "Mon, 04 Apr 2021 18:57:56 GMT"},
            "server": {"value": "gunicorn/19.9.0"},
            "access-control-allow-origin": {"value": "*"},
            "access-control-allow-credentials": {"value": "true"},
            "content-type": {"value": "application/json"},
            "content-length": {"value": "701"}
        },
        "cookies": {
            "ID": {
                "value": "id1234",
                "attributes": "Expires=Wed, 05 Apr 2021 07:28:00 GMT"
            },
            "Cookie1": {
                "value": "val1",
                "attributes": "Secure; Path=/; Domain=example.com; Expires=Wed, 05 Apr 2021 07:28:00 GMT",
                "multiValue": [
                    {
                        "value": "val1",
                        "attributes": "Secure; Path=/; Domain=example.com; Expires=Wed, 05 Apr 2021 07:28:00 GMT"
                    },
                    {
                        "value": "val2",
                        "attributes": "Path=/cat; Domain=example.com; Expires=Wed, 10 Jan 2021 07:28:00 GMT"
                    }
                ]
            }
        }
    }
}