View a markdown version of this page

通用辅助方法 - Amazon CloudFront
edgeLocation 元数据rawQueryString() 方法logCustomData() 方法

通用辅助方法

本页面提供了 CloudFront Functions 中的其他辅助方法。要使用这些方法，请使用 JavaScript 运行时 2.0 创建 CloudFront 函数。

import cf from 'cloudfront';

有关更多信息，请参阅适用于 CloudFront Functions 的 JavaScript 运行时系统 2.0 特征。

edgeLocation 元数据

此方法需要使用 cloudfront 模块。

注意

您只能将此方法用于查看器-请求函数。对于查看器-响应函数，此方法为空。

使用此 JavaScript 对象可获取边缘站点机场代码、预期的区域边缘缓存区域，或用于处理请求的 CloudFront 服务器 IP 地址。此元数据仅在查看器请求事件触发时可用。

cf.edgeLocation = {
    name: SEA
    serverIp: 1.2.3.4
    region: us-west-2
}

cf.edgeLocation 对象可包含：

name

处理请求的边缘站点的三字母 IATA 代码。

serverIp

处理请求的服务器的 IPv4 或 IPv6 地址。

region

发生缓存未命中时请求预计会使用的 CloudFront 区域边缘缓存（REC）。如果预期的 REC 不可用且请求使用备用 REC，则不会更新此值。这不包括正在使用的源护盾位置，除非主 REC 和源护盾的位置相同。

注意

如果 CloudFront 已配置为使用源失效转移，则不会再次调用 CloudFront Functions。有关更多信息，请参阅通过 CloudFront 源失效转移来优化高可用性。

rawQueryString() 方法

此方法不需要 cloudFront 模块。

使用 rawQueryString() 方法可以字符串形式检索未解析和未更改的查询字符串。

请求

function handler(event) {
    var request = event.request;
    const qs = request.rawQueryString();
}

响应

以不带前导 ? 的字符串值形式返回传入请求的完整查询字符串。

  • 如果没有查询字符串，但存在 ?，则函数将返回一个空字符串。

  • 如果没有查询字符串且 ? 不存在，则函数将返回 undefined。

场景 1：返回完整查询字符串（不带前导 ?）

传入请求 URL：https://example.com/page?name=John&age=25&city=Boston

rawQueryString()返回："name=John&age=25&city=Boston"

场景 2：返回空字符串（当 ? 存在但没有参数时）

传入请求 URL：https://example.com/page?

rawQueryString()返回：""

场景 3：返回 undefined（无查询字符串和 ?）

传入请求 URL：https://example.com/page

rawQueryString()返回：undefined

logCustomData() 方法

要使用此方法，请导入 cloudfront 模块。

使用 logCustomData() 方法将来自您的 Amazon CloudFront 函数的自定义数据发送到 CloudFront 访问日志。数据将写入 viewer-request-log-data 或 viewer-response-log-data 日志字段，具体取决于该函数是与查看器请求还是与查看器响应事件相关联。

该方法接受单个字符串参数。要记录对象，请先使用 JSON.stringify() 将其转换为字符串。例如：

const resp_obj = JSON.stringify(some_obj);
cf.logCustomData(resp_obj);

每个字段最多支持 800 字节的数据。在将数据写入日志字段之前，CloudFront 会自动对数据进行 URL 编码。经过 URL 编码后，CloudFront 会截断任何超过 800 字节的数据。如果您的函数在一次执行中多次调用 logCustomData()，CloudFront 将仅使用最后一个值。

在日志配置中添加字段

要在 CloudFront 访问日志中接收这些数据，您必须在使用实时访问日志配置或配置标准日志记录（v2）设置中添加 viewer-request-log-data 或 viewer-response-log-data 字段。CloudFront Functions 不支持嵌入式入网点（PoP）的自定义数据日志记录。

与 console.log() 的区别

logCustomData() 方法不能取代用于 CloudFront Functions 的 console.log()。使用 console.log() 将日志行发送到 Amazon CloudWatch Logs。使用 cf.logCustomData() 将自定义数据写入 CloudFront 访问日志（使用实时访问日志和配置标准日志记录（v2））。您可以在同一个函数中使用这两个方法。有关更多信息，请参阅 CloudFront Functions 日志。

该方法使用以下语法：

cf.logCustomData(String);
例在查看器请求函数中记录标头
import cf from 'cloudfront';

function handler(event) {
    var request = event.request;

    // Check if the debug header exists, if so log it
    if (request.headers['x-debug-header']) {
        // Log the debug header value
        cf.logCustomData("debug header found: " + request.headers['x-debug-header'].value);
    }

    return request;
}