Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

可用于 Node.js 金丝雀脚本的库函数

本节列出了可用于 Node.js 金丝雀脚本的库函数。

适用于所有金丝雀的 Node.js 库类和函数

以下用于 Node.js 的 CloudWatch Synthetics 库函数适用于所有金丝雀。

Synthetics 类

以下适用于所有金丝雀的函数都属于 Synthetics 类。

addExecutionError(errorMessage, ex);

errorMessage 描述错误，ex 指遇到的异常

您可以使用 addExecutionError 来设置金丝雀的执行错误。它会在不中断脚本执行的情况下导致金丝雀失败。它也不会影响 successPercent 指标。

只有当错误对于指示金丝雀脚本成功或故障并不重要时，才应将错误作为执行错误进行跟踪。

以下是使用 addExecutionError 的示例。您将会监控端点的可用性，并在页面加载完成后捕获屏幕截图。由于捕获屏幕截图故障并不会决定端点的可用性，因此您可以捕获在截图时遇到的任何错误，并将它们添加为执行错误。可用性指标仍会指示端点已启动并正在运行，但金丝雀状态会被标记为失败。以下示例代码块将会捕获此类错误并将其添加为执行错误。

try {
        await synthetics.takeScreenshot(stepName, "loaded");
    } catch(ex) {
        synthetics.addExecutionError('Unable to take screenshot ', ex);
    }

getCanaryName();

返回金丝雀的名称。

getCanaryArn();

返回金丝雀的 ARN。

getCanaryUserAgentString();

返回金丝雀的自定义用户代理。

getRuntimeVersion();

此函数在 syn-nodejs-puppeteer-3.0 和更高版本的运行时中可用。其返回金丝雀的 Synthetics 运行时版本。例如，返回值可能为 syn-nodejs-puppeteer-3.0。

getLogLevel();

检索 Synthetics 库的当前日志级别。可能的值包括：

例如：

let logLevel = synthetics.getLogLevel();

setLogLevel();

设置 Synthetics 库的日志级别。可能的值包括：

例如：

synthetics.setLogLevel(0);

SyntheticsConfiguration 类

此类仅在 syn-nodejs-2.1 或更高版本的运行时中可用。

您可以使用 SyntheticsConfiguration 类来配置 Synthetics 库函数的行为。例如，您可以使用此类将 executeStep() 函数配置为不捕获屏幕截图。

您可以在全局级别设置 CloudWatch Synthetics 配置，这些配置会应用于金丝雀的所有步骤。您还可以通过传递配置键/值对，在步骤级别覆盖这些配置。

您可以在步骤级别传入选项。有关示例，请参阅 async executeStep(stepName, functionToExecute, [stepConfig]); 和 executeHttpStep(stepName, requestOptions, [callback], [stepConfig])。

函数定义：

setConfig(options)

options 是一个对象，它是一组适用于您的金丝雀的可配置选项。以下各节将介绍 options 中的可能字段。

所有金丝雀的 setConfig(options)

对于使用 syn-nodejs-puppeteer-3.2 或更高版本的金丝雀，setConfig 的 (options) 可包含以下参数：

CloudWatch 指标的相关 setConfig(options)

对于使用 syn-nodejs-puppeteer-3.1 或更高版本的金丝雀，setConfig 的 (options) 可包含以下布尔参数，这些参数决定将由金丝雀发布的指标。其中每个选项的默认值均为 true。以 aggregated 开头的选项决定是否不带 CanaryName 维度发出指标。您可以使用该等指标查看所有金丝雀的聚合结果。其他选项决定是否带 CanaryName 维度发出指标。您可以使用该等指标查看每个金丝雀的结果。

用于启用或禁用指标的方法

disableAggregatedRequestMetrics()

禁用金丝雀发出以不带 CanaryName 维度形式发出的所有请求指标。

disableRequestMetrics()

禁用所有请求指标，包括每个金丝雀的指标和跨所有金丝雀聚合的指标。

disableStepMetrics()

禁用所有步骤指标，包括步骤成功指标和步骤持续时间指标。

enableAggregatedRequestMetrics()

启用金丝雀发出以不带 CanaryName 维度形式发出的所有请求指标。

enableRequestMetrics()

启用所有请求指标，包括每个金丝雀的指标和跨所有金丝雀聚合的指标。

enableStepMetrics()

启用所有步骤指标，包括步骤成功指标和步骤持续时间指标。

get2xxMetric()

返回金丝雀是否发出带 CanaryName 维度的 2xx 指标。

get4xxMetric()

返回金丝雀是否发出带 CanaryName 维度的 4xx 指标。

get5xxMetric()

返回金丝雀是否发出带 CanaryName 维度的 5xx 指标。

getAggregated2xxMetric()

返回金丝雀是否发出不带维度的 2xx 指标。

getAggregated4xxMetric()

返回金丝雀是否发出不带维度的 4xx 指标。

getAggregatedFailedCanaryMetric()

返回金丝雀是否发出不带维度的 Failed 指标。

getAggregatedFailedRequestsMetric()

返回金丝雀是否发出不带维度的 Failed requests 指标。

getAggregated5xxMetric()

返回金丝雀是否发出不带维度的 5xx 指标。

getFailedCanaryMetric()

返回金丝雀是否发出带 CanaryName 维度的 Failed 指标。

getFailedRequestsMetric()

返回金丝雀是否发出带 CanaryName 维度的 Failed requests 指标。

getStepDurationMetric()

返回金丝雀是否发出带有此金丝雀的 CanaryName 维度的 Duration 指标。

getStepSuccessMetric()

返回金丝雀是否发出带有此金丝雀的 CanaryName 维度的 StepSuccess 指标。

with2xxMetric(_2xxMetric)

接受一个布尔参数，该参数指定是否为此金丝雀发出带 CanaryName 维度的 2xx 指标。

with4xxMetric(_4xxMetric)

接受一个布尔参数，该参数指定是否为此金丝雀发出带 CanaryName 维度的 4xx 指标。

with5xxMetric(_5xxMetric)

接受一个布尔参数，该参数指定是否为此金丝雀发出带 CanaryName 维度的 5xx 指标。

withAggregated2xxMetric(aggregated2xxMetric)

接受一个布尔参数，该参数指定是否为此金丝雀发出不带维度的 2xx 指标。

withAggregated4xxMetric(aggregated4xxMetric)

接受一个布尔参数，该参数指定是否为此金丝雀发出不带维度的 4xx 指标。

withAggregated5xxMetric(aggregated5xxMetric)

接受一个布尔参数，该参数指定是否为此金丝雀发出不带维度的 5xx 指标。

withAggregatedFailedCanaryMetric(aggregatedFailedCanaryMetric)

接受一个布尔参数，该参数指定是否为此金丝雀发出不带维度的 Failed 指标。

withAggregatedFailedRequestsMetric(aggregatedFailedRequestsMetric)

接受一个布尔参数，该参数指定是否为此金丝雀发出不带维度的 Failed requests 指标。

withFailedCanaryMetric(failedCanaryMetric)

接受一个布尔参数，该参数指定是否为此金丝雀发出带 CanaryName 维度的 Failed 指标。

withFailedRequestsMetric(failedRequestsMetric)

接受一个布尔参数，该参数指定是否为此金丝雀发出带 CanaryName 维度的 Failed requests 指标。

withStepDurationMetric(stepDurationMetric)

接受一个布尔参数，该参数指定是否为此金丝雀发出带 CanaryName 维度的 Duration 指标。

withStepSuccessMetric(stepSuccessMetric)

接受一个布尔参数，该参数指定是否为此金丝雀发出带 CanaryName 维度的 StepSuccess 指标。

启用或禁用其他功能的方法

withHarFile()

接受一个布尔参数，该参数指定是否为此金丝雀创建 HAR 文件。

withStepsReport()

接受一个布尔参数，该参数指定是否报告此金丝雀的步骤执行摘要。

withIncludeUrlPassword()

接受一个布尔参数，该参数指定是否在日志和报告中包含 URL 中出现的密码。

withRestrictedUrlParameters()

接受要编辑的 URL 路径或查询参数的数组。这适用于出现在日志、报告和错误中的 URL。您可以传递星号 (*) 作为值来编辑所有 URL 路径和查询参数值

withLogRequest()

接受一个布尔参数，该参数指定是否将每个请求记录在金丝雀的日志中。

withLogResponse()

接受一个布尔参数，该参数指定是否将每个响应记录在金丝雀的日志中。

withLogRequestBody()

接受一个布尔参数，该参数指定是否将每个请求体记录在金丝雀的日志中。

withLogResponseBody()

接受一个布尔参数，该参数指定是否将每个响应体记录在金丝雀的日志中。

withLogRequestHeaders()

接受一个布尔参数，该参数指定是否将每个请求标头记录在金丝雀的日志中。

withLogResponseHeaders()

接受一个布尔参数，该参数指定是否将每个响应标头记录在金丝雀日志中。

getHarFile()

返回金丝雀是否创建 HAR 文件。

getStepsReport()

返回金丝雀是否报告步骤执行摘要。

getIncludeUrlPassword()

返回金丝雀是否在日志和报告中包含 URL 中出现的密码。

getRestrictedUrlParameters()

返回金丝雀是否编辑 URL 路径或查询参数。

getLogRequest()

返回金丝雀是否将每个请求记录在金丝雀的日志中。

getLogResponse()

返回金丝雀是否将每个响应记录在金丝雀的日志中。

getLogRequestBody()

返回金丝雀是否将每个请求体记录在金丝雀的日志中。

getLogResponseBody()

返回金丝雀是否将每个响应体记录在金丝雀的日志中。

getLogRequestHeaders()

返回金丝雀是否将每个请求标头记录在金丝雀的日志中。

getLogResponseHeaders()

返回金丝雀是否将每个响应标头记录在金丝雀的日志中。

所有金丝雀的函数

用于 UI 金丝雀的 setConfig(options)

对于 UI 金丝雀，setConfig 可包含以下布尔参数：

启用或禁用屏幕截图的方法

disableStepScreenshots()

禁用所有屏幕截图选项（screenshotOnStepStart、screenshotOnStepSuccess 和 screenshotOnStepFailure）。

enableStepScreenshots()

启用所有屏幕截图选项（screenshotOnStepStart、screenshotOnStepSuccess 和 screenshotOnStepFailure）。预设情况下，这些方法均未启用。

getScreenshotOnStepFailure()

返回金丝雀是否在步骤失败后捕获屏幕截图。

getScreenshotOnStepStart()

返回金丝雀是否在开始步骤之前捕获屏幕截图。

getScreenshotOnStepSuccess()

返回金丝雀是否在成功完成步骤后捕获屏幕截图。

withScreenshotOnStepStart(screenshotOnStepStart)

接受一个布尔参数，该参数指示是否在开始步骤之前捕获屏幕截图。

withScreenshotOnStepSuccess(screenshotOnStepSuccess)

接受一个布尔参数，该参数指示是否在成功完成步骤后捕获屏幕截图。

withScreenshotOnStepFailure(screenshotOnStepFailure)

接受一个布尔参数，该参数指示是否在步骤失败后捕获屏幕截图。

在 UI 金丝雀中的使用情况

首先，导入 Synthetics 依赖关系并获取配置。

// Import Synthetics dependency
const synthetics = require('Synthetics');

// Get Synthetics configuration
const synConfig = synthetics.getConfiguration();

然后，通过使用以下选项之一调用 setConfig 方法来设置每个选项的配置。

// Set configuration values
    synConfig.setConfig({
        screenshotOnStepStart: true, 
        screenshotOnStepSuccess: false,
        screenshotOnStepFailure: false
    });

Or

synConfig.withScreenshotOnStepStart(false).withScreenshotOnStepSuccess(true).withScreenshotOnStepFailure(true)

若要禁用所有屏幕截图，请使用 disableStepScreenshots() 函数，如本示例所示。

synConfig.disableStepScreenshots();

您可以在代码中的任何位置启用和禁用屏幕截图。例如，若要仅禁用一个步骤的屏幕截图，请在运行该步骤之前禁用屏幕截图，然后在该步骤后启用它们。

用于 API 金丝雀的 setConfig(options)

对于 API 金丝雀，setConfig 可包含以下布尔参数：

可视化监控

可视化监控将在金丝雀运行期间捕获的屏幕截图与在基准金丝雀运行期间捕获的屏幕截图进行比较。如果两个屏幕截图之间的差异超出阈值百分比，则金丝雀失败，您可以在金丝雀运行报告中看到以高亮颜色突出显示的差异区域。运行 syn-puppeteer-node-3.2 和更高版本的金丝雀支持可视化监控。运行 Python 和 Selenium 的金丝雀中目前不支持可视化监控。

若要启用可视化监控，请将以下代码行添加到金丝雀脚本中。有关更多详细信息，请参阅SyntheticsConfiguration 类。

syntheticsConfiguration.withVisualCompareWithBaseRun(true);

将此行添加到脚本后，金丝雀首次成功运行时，它会使用在该运行期间捕获的屏幕截图作为比较基准。在金丝雀的该首次运行之后，您可以使用 CloudWatch 控制台编辑金丝雀以执行以下任一操作：

有关使用 CloudWatch 控制台编辑金丝雀的更多信息，请参阅 编辑或删除金丝雀脚本。

可视化监控的其他选项

syntheticsConfiguration.withVisualVarianceThresholdPercentage(desiredPercentage)

设置可视化对比中屏幕截图差异的可接受百分比。

syntheticsConfiguration.withVisualVarianceHighlightHexColor("#fafa00")

设置在查看使用可视化监控的金丝雀运行报告时指明差异区域的突出显示颜色。

syntheticsConfiguration.withFailCanaryRunOnVisualVariance(failCanary)

设置当存在超过阈值的可视化差异时金丝雀是否失败。默认为金丝雀失败。

Synthetics Logger

SyntheticsLogger 将日志写入控制台和同一日志级别的本地日志文件。仅当日志级别与所调用的日志函数所需的日志记录级别相同或比其级别低时，此日志文件才会写入到这两个位置。

本地日志文件中的日志记录语句前面加上“DEBUG:”、“INFO:”等，以便与所调用的函数的日志级别相匹配。

如果您希望在与 Synthetics 金丝雀日志记录相同的日志级别运行 Synthetics 库，可以使用 SyntheticsLogger。

如果要创建上载到 S3 结果位置的日志文件，不需要使用 SyntheticsLogger。您可以在 /tmp 文件夹中创建不同的日志文件。在 /tmp 文件夹下创建的任何文件都会作为构件上传到 S3 中的结果位置。

要使用 Synthetics 库日志记录程序，请执行以下操作：

const log = require('SyntheticsLogger');

有用的函数定义：

log.debug(message, ex);

参数：message 是要记录的消息。ex 是要记录的异常（如果有）。

例如：

log.debug("Starting step - login.");

log.error(message, ex);

参数：message 是要记录的消息。ex 是要记录的异常（如果有）。

例如：

try {
  await login();
catch (ex) {
  log.error("Error encountered in step - login.", ex);
}

log.info(message, ex);

参数：message 是要记录的消息。ex 是要记录的异常（如果有）。

例如：

log.info("Successfully completed step - login.");

log.log(message, ex);

这是 log.info 的一个别名。

参数：message 是要记录的消息。ex 是要记录的异常（如果有）。

例如：

 log.log("Successfully completed step - login.");

log.warn(message, ex);

参数：message 是要记录的消息。ex 是要记录的异常（如果有）。

例如：

log.warn("Exception encountered trying to publish CloudWatch Metric.", ex);

SyntheticsLogHelper 类

SyntheticsLogHelper 类在 syn-nodejs-puppeteer-3.2 和更高版本的运行时中可用。其已在 CloudWatch Synthetics 库中初始化，并配置了 Synthetics 配置。您可以将它作为依赖项添加到脚本中。此类使您能够清理 URL、标头和错误消息，以编辑敏感信息。

getSanitizedUrl(url, stepConfig = null)

此函数在 syn-nodejs-puppeteer-3.2 和更高版本中可用。它根据配置返回经过清理的 url 字符串。您可以通过设置 restrictedUrlParameters 属性选择编辑敏感 URL 参数（如密码和 access_token）。预设情况下，会编辑 URL 中的密码。如果需要，您可以通过将 includeUrlPassword 设置为 true 来启用 URL 密码。

如果传入的 URL 不是有效 URL，此函数会引发一个错误。

参数

示例

此示例使用以下示例 URL：https://example.com/learn/home?access_token=12345&token_type=Bearer&expires_in=1200。在此示例中，access_token 包含不应记录下来的敏感信息。请注意，Synthetics 服务不会存储任何金丝雀运行构件。日志、屏幕截图和报告等构件都存储在您客户账户的 Amazon S3 存储桶中。

第一步，设置 Synthetics 配置。

// Import Synthetics dependency
const synthetics = require('Synthetics');

// Import Synthetics logger for logging url
const log = require('SyntheticsLogger');

// Get Synthetics configuration
const synConfig = synthetics.getConfiguration();

// Set restricted parameters
synConfig.setConfig({
   restrictedUrlParameters: ['access_token'];
});

接下来，清理并记录 URL

// Import SyntheticsLogHelper dependency
const syntheticsLogHelper = require('SyntheticsLogHelper');

const sanitizedUrl = synthetics.getSanitizedUrl('https://example.com/learn/home?access_token=12345&token_type=Bearer&expires_in=1200');

这一步会将以下内容记录在您的金丝雀日志中。

My example url is: https://example.com/learn/home?access_token=REDACTED&token_type=Bearer&expires_in=1200

您可以通过传入包含 Synthetics 配置选项的可选参数来覆盖 URL 的 Synthetics 配置，如以下示例所示。

const urlConfig = {
   restrictedUrlParameters = ['*']
};
const sanitizedUrl = synthetics.getSanitizedUrl('https://example.com/learn/home?access_token=12345&token_type=Bearer&expires_in=1200', urlConfig);
logger.info('My example url is: ' + sanitizedUrl);

上面的示例编辑了所有查询参数，并记录如下：

My example url is: https://example.com/learn/home?access_token=REDACTED&token_type=REDACTED&expires_in=REDACTED

getSanitizedErrorMessage

此函数在 syn-nodejs-puppeteer-3.2 和更高版本中可用。它根据 Synthetics 配置对所存在的任何 URL 进行清理，返回已清理的错误字符串。您可以选择在调用此函数时通过传递一个可选的 stepConfig 参数来覆盖全局 Synthetics 配置。

参数

示例

此示例使用以下内容：Failed to load url: https://example.com/learn/home?access_token=12345&token_type=Bearer&expires_in=1200

第一步，设置 Synthetics 配置。

// Import Synthetics dependency
const synthetics = require('Synthetics');

// Import Synthetics logger for logging url
const log = require('SyntheticsLogger');

// Get Synthetics configuration
const synConfig = synthetics.getConfiguration();

// Set restricted parameters
synConfig.setConfig({
   restrictedUrlParameters: ['access_token'];
});

接下来，清理并记录错误消息

// Import SyntheticsLogHelper dependency
const syntheticsLogHelper = require('SyntheticsLogHelper');

try {
   // Your code which can throw an error containing url which your script logs
} catch (error) {
    const sanitizedErrorMessage = synthetics.getSanitizedErrorMessage(errorMessage);
    logger.info(sanitizedErrorMessage);
}

这一步会将以下内容记录在您的金丝雀日志中。

Failed to load url: https://example.com/learn/home?access_token=REDACTED&token_type=Bearer&expires_in=1200

getSanitizedHeaders(headers, stepConfig=null)

此函数在 syn-nodejs-puppeteer-3.2 和更高版本中可用。它根据 syntheticsConfiguration 的 restrictedHeaders 属性返回经清理的标头。restrictedHeaders 属性中指定的标头是在日志、HAR 文件和报告中编辑的。

参数

仅适用于 UI 金丝雀的 Node.js 库类和函数

以下用于 Node.js 的 CloudWatch Synthetics 库函数仅适用于 UI 金丝雀。

Synthetics 类

以下函数位于 Synthetics 类中。

async addUserAgent(page, userAgentString);

此函数可将 userAgentString 附加到指定页面的 User-Agent 标头。

例如：

await synthetics.addUserAgent(page, "MyApp-1.0");

结果是页面的 User-Agent 标头被设置为 browsers-user-agent-header-valueMyApp-1.0

async executeStep(stepName, functionToExecute, [stepConfig]);

执行提供的步骤，并使用开始/通过/失败日志记录、开始/通过/失败屏幕截图，以及通过/失败和持续时间指标对其进行包装。

executeStep 函数还执行以下操作：

如果金丝雀使用 syn-nodejs-2.0 或更高版本的运行时，则此函数还将步骤执行摘要添加到金丝雀的报告中。摘要包括有关每个步骤的详细信息，例如开始时间、结束时间、状态 (PASSED/FAILED)、故障原因（如失败）以及在每个步骤执行过程中捕获的屏幕截图。

例如：

await synthetics.executeStep('navigateToUrl', async function (timeoutInMillis = 30000) {
           await page.goto(url, {waitUntil: ['load', 'networkidle0'], timeout: timeoutInMillis});});

响应：

返回 functionToExecute 返回的内容。

syn-nodejs-2.2 的更新

从 syn-nodejs-2.2 开始，您可以选择传递步骤配置来在步骤级别覆盖 CloudWatch Synthetics 配置。有关可以传递给 executeStep 的选项列表，请参阅 SyntheticsConfiguration 类。

在以下示例中，用 true 覆盖 continueOnStepFailure 的默认 false 配置，并指定捕获屏幕截图的时间。

var stepConfig = {
    'continueOnStepFailure': true,
    'screenshotOnStepStart': false,
    'screenshotOnStepSuccess': true,
    'screenshotOnStepFailure': false
}

await executeStep('Navigate to amazon', async function (timeoutInMillis = 30000) {
      await page.goto(url, {waitUntil: ['load', 'networkidle0'], timeout: timeoutInMillis});
 }, stepConfig);

getDefaultLaunchOptions();

getDefaultLaunchOptions() 函数返回 CloudWatch Synthetics 使用的浏览器启动选项。有关更多信息，请参阅 启动选项类型

// This function returns default launch options used by Synthetics.
const defaultOptions = await synthetics.getDefaultLaunchOptions();

getPage();

返回当前打开的页面作为 Puppeteer 对象。有关更多信息，请参阅 Puppeteer API v1.14.0。

例如：

let page = synthetics.getPage();

响应：

在当前浏览器会话中打开的页面（Puppeteer 对象）。

getRequestResponseLogHelper();

将此函数用作生成器模式，用于调整请求和响应日志记录标记。

例如：

synthetics.setRequestResponseLogHelper(getRequestResponseLogHelper().withLogRequestHeaders(false));;

响应：

{RequestResponseLogHelper}

launch(options)

此函数的选项仅在 syn-nodejs-2.1 版本或更高版本的运行时中可用。

此函数仅用于 UI 金丝雀。它的作用是关闭现有浏览器并启动一个新的浏览器。

(options) 是在浏览器上设置的一组可配置的选项。有关更多信息，请参阅 启动选项类型。

如果您在不设置选项的情况下调用此函数，Synthetics 会以默认参数、executablePath 和 defaultViewport 启动浏览器。CloudWatch Synthetics 中的默认视区是 1920 x 1080。

您可以覆盖 CloudWatch Synthetics 使用的启动参数，并在启动浏览器时传递其他参数。例如，以下代码段以默认参数和默认可执行文件路径启动浏览器，但视区为 800 x 600。

await synthetics.launch({
        defaultViewport: { 
            "deviceScaleFactor": 1, 
            "width": 800,
            "height": 600 
    }});

以下示例代码向 CloudWatch Synthetics 启动参数中添加了一个新的 ignoreHTTPSErrors 参数。

await synthetics.launch({
        ignoreHTTPSErrors: true
 });

您可以通过向 CloudWatch Synthetics 启动参数中的参数添加一个 --disable-web-security 标志来禁用 Web 安全：

// This function adds the --disable-web-security flag to the launch parameters
const defaultOptions = await synthetics.getDefaultLaunchOptions();
const launchArgs = [...defaultOptions.args, '--disable-web-security'];
await synthetics.launch({
     args: launchArgs
  });

RequestResponseLogHelper 类

处理精细配置，以及创建请求和响应负载的字符串表示。

class RequestResponseLogHelper {
 
    constructor () {
        this.request = {url: true, resourceType: false, method: false, headers: false, postData: false};
        this.response = {status: true, statusText: true, url: true, remoteAddress: false, headers: false};
    }
 
    withLogRequestUrl(logRequestUrl);
    
    withLogRequestResourceType(logRequestResourceType);
    
    withLogRequestMethod(logRequestMethod);
    
    withLogRequestHeaders(logRequestHeaders);
    
    withLogRequestPostData(logRequestPostData);

        
    withLogResponseStatus(logResponseStatus);
    
    withLogResponseStatusText(logResponseStatusText);
   
    withLogResponseUrl(logResponseUrl);
 
    withLogResponseRemoteAddress(logResponseRemoteAddress);
    
    withLogResponseHeaders(logResponseHeaders);

例如：

synthetics.setRequestResponseLogHelper(getRequestResponseLogHelper()
.withLogRequestPostData(true)
.withLogRequestHeaders(true)
.withLogResponseHeaders(true));

响应：

{RequestResponseLogHelper}

setRequestResponseLogHelper();

将此函数用作成生器模式，用于设置请求和响应日志记录标记。

例如：

synthetics.setRequestResponseLogHelper().withLogRequestHeaders(true).withLogResponseHeaders(true);

响应：

{RequestResponseLogHelper}

async takeScreenshot(name, suffix);

捕获当前页面的屏幕截图 (.PNG) 并命名和添加后缀（可选）。

例如：

await synthetics.takeScreenshot("navigateToUrl", "loaded")

在此示例中，捕获了名为 01-navigateToUrl-loaded.png 的屏幕截图并将其上载到金丝雀的 S3 存储桶。

您可以传递 stepName 作为第一个参数，捕获特定金丝雀步骤的屏幕截图。屏幕截图会链接到报告中的金丝雀步骤，以帮助您在调试时跟踪每个步骤。

CloudWatch Synthetics 金丝雀会在开始步骤之前（executeStep 函数）和步骤完成后自动捕获屏幕截图（除非您将金丝雀配置为禁用屏幕截图）。您可以通过将步骤名称传入 takeScreenshot 函数来捕获多个屏幕截图。

在以下示例中，捕获屏幕截图并将 signupForm 作为 stepName 的值。屏幕截图将被命名为 02-signupForm-address，并链接到金丝雀报告中名为 signupForm 的步骤。

await synthetics.takeScreenshot('signupForm', 'address')

BrokenLinkCheckerReport 类

此类提供了添加 Synthetics 链接的方法。仅在使用 syn-nodejs-2.0-beta 或更高版本运行时的金丝雀上支持此类。

若要使用 BrokenLinkCheckerReport，脚本中需包括以下行：

const BrokenLinkCheckerReport = require('BrokenLinkCheckerReport');
            
const brokenLinkCheckerReport = new BrokenLinkCheckerReport();

有用的函数定义：

addLink(syntheticsLink, isBroken)

syntheticsLink 是一个 SyntheticsLink 对象，表示链接。此函数根据状态代码添加链接。预设情况下，如果状态代码不可用或状态代码为 400 或以上，则其会将链接视为无效。您可以通过传入可选参数 isBrokenLink（带有值 true 或 false）来覆盖此默认行为。

此函数无返回值。

getLinks()

此函数返回一组 SyntheticsLink 对象，这些对象包含在无效链接检查器报告。

getTotalBrokenLinks()

此函数返回一个表示无效链接总数的数字。

getTotalLinksChecked()

此函数返回一个表示包含在报告中的链接总数的数字。

如何使用 BrokenLinkCheckerReport

以下金丝雀脚本代码段展示了导航到链接并将其添加到无效链接检查器报告的示例。

SyntheticsLink 类

此类提供了包装信息的方法。仅在使用 syn-nodejs-2.0-beta 或更高版本运行时的金丝雀上支持此类。

若要使用 SyntheticsLink，脚本中需包括以下行：

const SyntheticsLink = require('SyntheticsLink');

const syntheticsLink = new SyntheticsLink("https://www.amazon.com");

此函数返回 syntheticsLinkObject

有用的函数定义：

withUrl(url)

url 是一个 URL 字符串。此函数返回 syntheticsLinkObject

withText(text)

text 是一个表示锚文本的字符串。此函数返回 syntheticsLinkObject。它会添加与链接相对应的锚文本。

withParentUrl(parentUrl)

parentUrl 是一个表示父（源页面）URL 的字符串。此函数返回 syntheticsLinkObject

withStatusCode(statusCode)

statusCode 是一个表示状态代码的字符串。此函数返回 syntheticsLinkObject

withFailureReason(failureReason)

failureReason 是一个表示故障原因的字符串。此函数返回 syntheticsLinkObject

addScreenshotResult(screenshotResult)

screenshotResult 是一个对象。它是 Synthetics 函数 takeScreenshot 返回的 ScreenshotResult 的实例。此对象包括以下属性：

仅适用于 API 金丝雀的 Node.js 库类和函数

以下用于 Node.js 的 CloudWatch Synthetics 库函数仅适用于 API 金丝雀。

executeHttpStep(stepName, requestOptions, [callback], [stepConfig])

作为步骤执行提供的 HTTP 请求，并发布 SuccessPercent（通过/失败）和 Duration 指标。

executeHttpStep 在后台使用 HTTP 或 HTTPS 本机函数，具体取决于请求中指定的协议。

此函数还将步骤执行摘要添加到金丝雀的报告中。摘要中包括有关每个 HTTP 请求的详细信息，如下所示：

参数

stepName(String)

指定步骤的名称。此名称也用于发布此步骤的 CloudWatch 指标。

requestOptions(Object or String)

此参数的值可以是 URL、URL 字符串或对象。如果为对象，则必须是用以发出 HTTP 请求的一组可配置选项。其支持 Node.js 文档中 http.request(options[, callback]) 中的所有选项。

除了这些 Node.js 选项之外，requestOptions 支持附加参数 body。您可以使用 body 参数将数据作为请求体传递。

callback(response)

（可选）此函数是与 HTTP 响应一起调用的用户函数。响应的类型为 Class: http.IncomingMessage。

stepConfig(object)

（可选）使用此参数，可以用此步骤的不同配置覆盖全局 synthetics 配置。

executeHttpStep 的使用示例

以下一系列示例相互依存，以说明此选项的各种用途。

第一个示例展示配置请求参数。您可以将 URL 作为 requestOptions 传递：

let requestOptions = 'https://www.amazon.com';

或者，您也可以传递一组选项：

let requestOptions = {
        'hostname': 'myproductsEndpoint.com',
        'method': 'GET',
        'path': '/test/product/validProductName',
        'port': 443,
        'protocol': 'https:'
    };

在下一个示例中，创建一个接受响应的回调函数。预设情况下，如果您未指定 callback，CloudWatch Synthetics 会验证状态是否介于 200 和 299 之间（含）。

// Handle validation for positive scenario
    const callback = async function(res) {
        return new Promise((resolve, reject) => {
            if (res.statusCode < 200 || res.statusCode > 299) {
                throw res.statusCode + ' ' + res.statusMessage;
            }
     
            let responseBody = '';
            res.on('data', (d) => {
                responseBody += d;
            });
     
            res.on('end', () => {
                // Add validation on 'responseBody' here if required. For ex, your status code is 200 but data might be empty
                resolve();
            });
        });
    };

下一个示例展示为此步骤创建覆盖全局 CloudWatch Synthetics 配置的配置。在本示例中，步骤配置允许报告中包含请求标头、响应标头、请求体（发布数据）和响应体，并限制了“X-Amz-Security-Token”和“Authorization”标头值。预设情况下，出于安全原因，报告中不包括这些值。如果您选择将它们包含在报告中，则这些数据仅存储在 S3 存储桶中。

// By default headers, post data, and response body are not included in the report for security reasons. 
// Change the configuration at global level or add as step configuration for individual steps
let stepConfig = {
    includeRequestHeaders: true, 
    includeResponseHeaders: true,
    restrictedHeaders: ['X-Amz-Security-Token', 'Authorization'], // Restricted header values do not appear in report generated.
    includeRequestBody: true,
    includeResponseBody: true
};

最后一个例子展示将请求传递给 executeHttpStep 并对步骤命名。

await synthetics.executeHttpStep('Verify GET products API', requestOptions, callback, stepConfig);

在这组示例中，CloudWatch Synthetics 将每个步骤的详细信息添加在报告中，并使用 stepName 生成每个步骤的指标。

您将看到 Verify GET products API 步骤的 successPercent 和 duration 指标。您可以通过监控 API 调用步骤的指标来监控 API 性能。

有关使用这些函数的完整脚本示例，请参阅 多步骤 API 金丝雀。