# 可用于使用 Puppeteer 的 Node.js Canary 脚本的库函数
本节描述了可用于 Node.js Canary 脚本的库函数。
**Topics**
+ [适用于所有金丝雀的 Node.js 库类和函数](#CloudWatch_Synthetics_Library_allcanaries)
+ [仅适用于 UI 金丝雀的 Node.js 库类和函数](#CloudWatch_Synthetics_Library_UIcanaries)
+ [仅适用于 API 金丝雀的 Node.js 库类和函数](#CloudWatch_Synthetics_Library_APIcanaries)
## 适用于所有金丝雀的 Node.js 库类和函数
以下用于 Node.js 的 CloudWatch Synthetics 库函数适用于所有金丝雀。
**Topics**
+ [Synthetics 类](#CloudWatch_Synthetics_Library_Synthetics_Class_all)
+ [SyntheticsConfiguration 类](#CloudWatch_Synthetics_Library_SyntheticsConfiguration)
+ [Synthetics Logger](#CloudWatch_Synthetics_Library_SyntheticsLogger)
+ [SyntheticsLogHelper 类](#CloudWatch_Synthetics_Library_SyntheticsLogHelper)
### Synthetics 类
以下适用于所有金丝雀的函数都属于 Synthetics 类。
**Topics**
+ [addExecutionError(errorMessage, ex);](#CloudWatch_Synthetics_Library_addExecutionError)
+ [getCanaryName();](#CloudWatch_Synthetics_Library_getCanaryName)
+ [getCanaryArn();](#CloudWatch_Synthetics_Library_getCanaryARN)
+ [getCanaryUserAgentString();](#CloudWatch_Synthetics_Library_getCanaryUserAgentString)
+ [getRuntimeVersion();](#CloudWatch_Synthetics_Library_getRuntimeVersion)
+ [getLogLevel();](#CloudWatch_Synthetics_Library_getLogLevel)
+ [setLogLevel();](#CloudWatch_Synthetics_Library_setLogLevel)
#### 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 库的当前日志级别。可能的值包括：
+ `0` – 调试
+ `1` – 信息
+ `2` – 警告
+ `3` – 错误
示例：
```
let logLevel = synthetics.getLogLevel();
```
#### setLogLevel();
设置 Synthetics 库的日志级别。可能的值包括：
+ `0` – 调试
+ `1` – 信息
+ `2` – 警告
+ `3` – 错误
示例：
```
synthetics.setLogLevel(0);
```
### SyntheticsConfiguration 类
此类仅在 `syn-nodejs-2.1` 或更高版本的运行时中可用。
您可以使用 `SyntheticsConfiguration` 类来配置 Synthetics 库函数的行为。例如，您可以使用此类将 `executeStep()` 函数配置为不捕获屏幕截图。
您可以在全局级别设置 CloudWatch Synthetics 配置，这些配置会应用于金丝雀的所有步骤。您还可以通过传递配置键和值对，在步骤级别覆盖这些配置。
您可以在步骤级别传入选项。有关示例，请参阅 [async executeStep(stepName, functionToExecute, [stepConfig]);](#CloudWatch_Synthetics_Library_executeStep) 和 [executeHttpStep(stepName, requestOptions, [callback], [stepConfig])](#CloudWatch_Synthetics_Library_executeHttpStep)。
**Topics**
+ [setConfig(options)](#CloudWatch_Synthetics_Library_setConfig)
+ [可视化监控](#CloudWatch_Synthetics_Library_SyntheticsLogger_VisualTesting)
#### setConfig(options)
` options ` 是一个对象，它是一组适用于您的金丝雀的可配置选项。以下各节将介绍 ` options ` 中的可能字段。
##### 所有金丝雀的 setConfig(options)
对于使用 `syn-nodejs-puppeteer-3.2` 或更新版本的金丝雀，**setConfig** 的 **(options)** 可包含以下参数：
+ `includeRequestHeaders`（布尔值）– 是否在报告中包含请求标头。默认值为 `false`。
+ `includeResponseHeaders`（布尔值）– 是否在报告中包含响应标头。默认值为 `false`。
+ `restrictedHeaders`（数组）– 要忽略的标头值列表（如果包含标头）。这对请求标头和响应标头均适用。例如，您可以将 **includeRequestHeaders** 传递为 `true` 并将 **restrictedHeaders** 传递为 `['Authorization']`，来隐藏凭证。
+ `includeRequestBody`（布尔值）– 是否在报告中包含请求体。默认值为 `false`。
+ `includeResponseBody`（布尔值）– 是否在报告中包含响应体。默认值为 `false`。
**重要**
如果您启用了 `includeResponseBody` 或 ` logResponseBody`，则某些 API（例如 aws-sdk v3 客户端）的响应中不会返回该数据对象。这是因为 Node.js 和所用响应对象类型的限制。
**CloudWatch 指标的相关 setConfig(options)**
对于使用 `syn-nodejs-puppeteer-3.1` 或更新版本的金丝雀，**setConfig** 的 **(options)** 可包含以下布尔参数，这些参数决定将由金丝雀发布的指标。其中每个选项的默认值均为 `true`。以 `aggregated` 开头的选项决定是否不带 ` CanaryName` 维度发出指标。您可以使用该等指标查看所有金丝雀的聚合结果。其他选项决定是否带 `CanaryName` 维度发出指标。您可以使用该等指标查看每个金丝雀的结果。
有关金丝雀发出的 CloudWatch 指标的列表，请参阅 [金丝雀发布的 CloudWatch 指标](CloudWatch_Synthetics_Canaries_metrics.md)。
+ `failedCanaryMetric`（布尔值）– 是否发出此金丝雀的 ` Failed` 指标（带 `CanaryName` 维度）。默认值为 `true`。
+ `failedRequestsMetric`（布尔值）– 是否发出此金丝雀的 `Failed requests` 指标（带 `CanaryName` 维度）。默认值为 `true`。
+ `_2xxMetric`（布尔值）– 是否发出此金丝雀的 `2xx` 指标（带 `CanaryName` 维度）。默认值为 `true`。
+ `_4xxMetric`（布尔值）– 是否发出此金丝雀的 `4xx` 指标（带 `CanaryName` 维度）。默认值为 `true`。
+ `_5xxMetric`（布尔值）– 是否发出此金丝雀的 `5xx` 指标（带 `CanaryName` 维度）。默认值为 `true`。
+ `stepDurationMetric`（布尔值）– 是否发出此金丝雀的 `Step duration` 指标（带 `CanaryName` `StepName` 维度）。默认值为 `true`。
+ `stepSuccessMetric`（布尔值）– 是否发出此金丝雀的 `Step success` 指标（带 `CanaryName` `StepName` 维度）。默认值为 `true`。
+ `aggregatedFailedCanaryMetric`（布尔值）– 是否发出此金丝雀的 `Failed` 指标（不带 `CanaryName` 维度）。默认值为 `true`。
+ `aggregatedFailedRequestsMetric`（布尔值）– 是否发出此金丝雀的 `Failed Requests` 指标（不带 `CanaryName` 维度）。默认值为 `true`。
+ `aggregated2xxMetric`（布尔值）– 是否发出此金丝雀的 ` 2xx` 指标（不带 `CanaryName` 维度）。默认值为 `true`。
+ `aggregated4xxMetric`（布尔值）– 是否发出此金丝雀的 ` 4xx` 指标（不带 `CanaryName` 维度）。默认值为 `true`。
+ `aggregated5xxMetric`（布尔值）– 是否发出此金丝雀的 ` 5xx` 指标（不带 `CanaryName` 维度）。默认值为 `true`。
+ `visualMonitoringSuccessPercentMetric`（布尔值）– 是否发出此金丝雀的 `visualMonitoringSuccessPercent` 指标。默认值为 `true`。
+ `visualMonitoringTotalComparisonsMetric`（布尔值）– 是否发出此金丝雀的 `visualMonitoringTotalComparisons` 指标。默认值为 `false`。
+ `includeUrlPassword`（布尔值）– 是否包含 URL 中显示的密码。预设情况下，URL 中显示的密码会在日志和报告中进行编辑，以防泄露敏感数据。默认值为 `false`。
+ `restrictedUrlParameters`（数组）– 要编辑的 URL 路径或查询参数的列表。这适用于出现在日志、报告和错误中的 URL。此参数区分大小写。您可以传递星号 (\$1) 作为值来编辑所有 URL 路径和查询参数值。默认值为空数组。
+ `logRequest`（布尔值）– 是否将每个请求都记录在金丝雀日志中。对于 UI 金丝雀，这会记录浏览器发送的每个请求。默认值为 `true`。
+ `logResponse`（布尔值）– 是否将每个响应都记录在金丝雀日志中。对于 UI 金丝雀，这会记录浏览器收到的每个响应。默认值为 `true`。
+ `logRequestBody`（布尔值）– 是否随请求一起将请求体记录在金丝雀日志中。仅当 `logRequest` 为 `true` 时，此配置才适用。默认为 `false`。
+ `logResponseBody`（布尔值）– 是否随响应一起将响应体记录在金丝雀日志中。仅当 `logResponse` 为 `true` 时，此配置才适用。默认值为 ` false`。
**重要**
如果您启用了 `includeResponseBody` 或 ` logResponseBody`，则某些 API（例如 aws-sdk v3 客户端）的响应中不会返回该数据对象。这是因为 Node.js 和所用响应对象类型的限制。
+ `logRequestHeaders`（布尔值）– 是否随请求一起将请求标头记录在金丝雀日志中。仅当 `logRequest` 为 `true` 时，此配置才适用。默认值为 ` false`。
请注意，`includeRequestHeaders` 会在构件中启用标头。
+ `logResponseHeaders`（布尔值）– 是否随响应一起将响应标头记录在金丝雀日志中。仅当 `logResponse` 为 `true` 时，此配置才适用。默认值为 ` false`。
请注意，`includeResponseHeaders` 会在构件中启用标头。
**注意**
始终会发出每个金丝雀的 `Duration` 和 `SuccessPercent` 指标，这两个指标都会带有和不带 `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(\$12xxMetric)**
接受一个布尔参数，该参数指定是否为此金丝雀发出带 `CanaryName` 维度的 `2xx` 指标。
**with4xxMetric(\$14xxMetric)**
接受一个布尔参数，该参数指定是否为此金丝雀发出带 `CanaryName` 维度的 `4xx` 指标。
**with5xxMetric(\$15xxMetric)**
接受一个布尔参数，该参数指定是否为此金丝雀发出带 `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。您可以传递星号 (\$1) 作为值来编辑所有 URL 路径和查询参数值
**withLogRequest()**
接受一个布尔参数，该参数指定是否将每个请求记录在金丝雀的日志中。
**withLogResponse()**
接受一个布尔参数，该参数指定是否将每个响应记录在金丝雀的日志中。
**withLogRequestBody()**
接受一个布尔参数，该参数指定是否将每个请求体记录在金丝雀的日志中。
**withLogResponseBody()**
接受一个布尔参数，该参数指定是否将每个响应体记录在金丝雀的日志中。
**withLogRequestHeaders()**
接受一个布尔参数，该参数指定是否将每个请求标头记录在金丝雀的日志中。
**withLogResponseHeaders()**
接受一个布尔参数，该参数指定是否将每个响应标头记录在金丝雀日志中。
**getHarFile()**
返回金丝雀是否创建 HAR 文件。
**getStepsReport()**
返回金丝雀是否报告步骤执行摘要。
**getIncludeUrlPassword()**
返回金丝雀是否在日志和报告中包含 URL 中出现的密码。
**getRestrictedUrlParameters()**
返回金丝雀是否编辑 URL 路径或查询参数。
**getLogRequest()**
返回金丝雀是否将每个请求记录在金丝雀的日志中。
**getLogResponse()**
返回金丝雀是否将每个响应记录在金丝雀的日志中。
**getLogRequestBody()**
返回金丝雀是否将每个请求体记录在金丝雀的日志中。
**getLogResponseBody()**
返回金丝雀是否将每个响应体记录在金丝雀的日志中。
**getLogRequestHeaders()**
返回金丝雀是否将每个请求标头记录在金丝雀的日志中。
**getLogResponseHeaders()**
返回金丝雀是否将每个响应标头记录在金丝雀的日志中。
**所有金丝雀的函数**
+ `withIncludeRequestHeaders`(includeRequestHeaders)
+ `withIncludeResponseHeaders`（包括响应标题）
+ `withRestrictedHeaders`(restrictedHeaders)
+ `withIncludeRequestBody`(includeRequestBody)
+ `withIncludeResponseBody`(includeResponseBody)
+ `enableReportingOptions`() – 启用所有报告选项-- **includeRequestHeaders**、**includeResponseHeaders**、**includeRequestBody** 和 **includeResponseBody**。
+ `disableReportingOptions`() – 禁用所有报告选项-- **includeRequestHeaders**、**includeResponseHeaders**、**includeRequestBody** 和 **includeResponseBody**。
##### 用于 UI 金丝雀的 setConfig(options)
对于 UI 金丝雀，**setConfig** 可包含以下布尔参数：
+ `continueOnStepFailure`（布尔值）– 是否在步骤失败（指 **executeStep** 函数）后继续运行金丝雀脚本。如果任何步骤失败，金丝雀运行仍将被标记为失败。默认值为 `false`。
+ `harFile`（布尔值）– 是否创建 HAR 文件。默认值为 `True`。
+ `screenshotOnStepStart`（布尔值）– 是否在开始步骤之前捕获屏幕截图。
+ `screenshotOnStepSuccess`（布尔值）– 是否在成功完成步骤后捕获屏幕截图。
+ `screenshotOnStepFailure`（布尔值）– 是否在步骤失败后捕获屏幕截图。
##### 启用或禁用屏幕截图的方法
**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('@aws/synthetics-puppeteer');
// 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** 可包含以下布尔参数：
+ `continueOnHttpStepFailure`（布尔值）- 是否在 HTTP 步骤（指 **executeHttpStep** 函数）失败后继续运行金丝雀脚本。如果任何步骤失败，金丝雀运行仍将被标记为失败。默认值为 `true`。
#### 可视化监控
可视化监控将在金丝雀运行期间捕获的屏幕截图与在基准金丝雀运行期间捕获的屏幕截图进行比较。如果两个屏幕截图之间的差异超出阈值百分比，则金丝雀失败，您可以在金丝雀运行报告中看到以高亮颜色突出显示的差异区域。运行 **syn-puppeteer-node-3.2** 和更高版本的金丝雀支持可视化监控。运行 Python 和 Selenium 的金丝雀中目前不支持可视化监控。
若要启用可视化监控，请将以下代码行添加到金丝雀脚本中。有关更多详细信息，请参阅[SyntheticsConfiguration 类](#CloudWatch_Synthetics_Library_SyntheticsConfiguration)。
```
syntheticsConfiguration.withVisualCompareWithBaseRun(true);
```
将此行添加到脚本后，金丝雀首次成功运行时，它会使用在该运行期间捕获的屏幕截图作为比较基准。在金丝雀的该首次运行之后，您可以使用 CloudWatch 控制台编辑金丝雀以执行以下任一操作：
+ 将金丝雀的下一次运行设置为新基准。
+ 在当前基准屏幕截图上绘制边界，以指定在可视化比较过程中要忽略的屏幕截图区域。
+ 删除屏幕截图，使其不用于可视化监控。
有关使用 CloudWatch 控制台编辑金丝雀的更多信息，请参阅 [编辑或删除金丝雀脚本](synthetics_canaries_deletion.md)。
**可视化监控的其他选项**
**syntheticsConfiguration.withVisualVarianceThresholdPercentage(desiredPercentage)**
设置可视化对比中屏幕截图差异的可接受百分比。
**syntheticsConfiguration.withVisualVarianceHighlightHexColor("\$1fafa00")**
设置在查看使用可视化监控的金丝雀运行报告时指明差异区域的突出显示颜色。
**syntheticsConfiguration.withFailCanaryRunOnVisualVariance(failCanary)**
设置当存在超过阈值的可视化差异时金丝雀是否失败。默认为金丝雀失败。
### Synthetics Logger
SyntheticsLogger 将日志写入控制台和同一日志级别的本地日志文件。仅当日志级别与所调用的日志函数所需的日志记录级别相同或比其级别低时，此日志文件才会写入到这两个位置。
本地日志文件中的日志记录语句前面加上“DEBUG:”、“INFO:”等，以便与所调用的函数的日志级别相匹配。
如果您希望在与 Synthetics 金丝雀日志记录相同的日志级别运行 Synthetics 库，可以使用 SyntheticsLogger。
如果要创建上载到 S3 结果位置的日志文件，不需要使用 SyntheticsLogger。您可以在 ` /tmp` 文件夹中创建不同的日志文件。在 `/tmp` 文件夹下创建的任何文件都会作为构件上传到 S3 中的结果位置。
要使用 Synthetics 库日志记录程序，请执行以下操作：
```
const log = require('@aws/synthetics-logger');
```
有用的函数定义：
**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、标头和错误消息，以编辑敏感信息。
**注意**
根据 Synthetics 配置设置 `restrictedUrlParameters`，Synthetics 会对其记录的所有 URL 和错误消息进行清理，然后再将它们纳入日志、报告、HAR 文件和金丝雀运行错误中。仅当您在脚本中记录 URL 或错误时，才必须使用 ` getSanitizedUrl` 或 `getSanitizedErrorMessage`。除了脚本引发的金丝雀错误之外，Synthetics 不会存储任何金丝雀构件。金丝雀运行构件存储在您的客户账户中。有关更多信息，请参阅 [Synthetics 金丝雀的安全注意事项](servicelens_canaries_security.md)。
**Topics**
+ [getSanitizedUrl(url, stepConfig = null)](#CloudWatch_Synthetics_Library_getSanitizedUrl)
+ [getSanitizedErrorMessage](#CloudWatch_Synthetics_Library_getSanitizedErrorMessage)
+ [getSanitizedHeaders(headers, stepConfig=null)](#CloudWatch_Synthetics_Library_getSanitizedHeaders)
#### getSanitizedUrl(url, stepConfig = null)
此函数在 `syn-nodejs-puppeteer-3.2` 和更高版本中可用。它根据配置返回经过清理的 url 字符串。您可以通过设置 `restrictedUrlParameters` 属性选择编辑敏感 URL 参数（如密码和 access\$1token）。预设情况下，会编辑 URL 中的密码。如果需要，您可以通过将 `includeUrlPassword` 设置为 true 来启用 URL 密码。
如果传入的 URL 不是有效 URL，此函数会引发一个错误。
**参数 **
+ *url* 是一个字符串，也是要清理的 URL。
+ *StepConfig*（可选）覆盖此函数的全局 Synthetics 配置。如果 `stepConfig` 未传入，则使用全局配置清理 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('@aws/synthetics-puppeteer');
// Import Synthetics logger for logging url
const log = require('@aws/synthetics-logger');
// Get Synthetics configuration
const synConfig = synthetics.getConfiguration();
// Set restricted parameters
synConfig.setConfig({
restrictedUrlParameters: ['access_token'];
});
// Import SyntheticsLogHelper dependency
const syntheticsLogHelper = require('@aws/synthetics-log-helper');
const sanitizedUrl = syntheticsLogHelper.getSanitizedUrl('URL');
const urlConfig = {
restrictedUrlParameters = ['*']
};
const sanitizedUrl = syntheticsLogHelper.getSanitizedUrl('URL', urlConfig);
logger.info('My example url is: ' + sanitizedUrl);
```
接下来，清理并记录 URL
```
// Import SyntheticsLogHelper dependency
const syntheticsLogHelper = require('@aws/synthetics-log-helper');
const sanitizedUrl = syntheticsLogHelper.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 = syntheticsLogHelper.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 配置。
**参数 **
+ *error* 是要清理的错误。它可以是 Error 对象或字符串。
+ *StepConfig*（可选）覆盖此函数的全局 Synthetics 配置。如果 `stepConfig` 未传入，则使用全局配置清理 URL。
**示例 **
此示例使用以下内容：` 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('@aws/synthetics-puppeteer');
// Import Synthetics logger for logging url
const log = require('@aws/synthetics-logger');
// Get Synthetics configuration
const synConfig = synthetics.getConfiguration();
// Set restricted parameters
synConfig.setConfig({
restrictedUrlParameters: ['access_token'];
});
```
接下来，清理并记录错误消息
```
// Import SyntheticsLogHelper dependency
const syntheticsLogHelper = require('@aws/synthetics-log-helper');
try {
// Your code which can throw an error containing url which your script logs
} catch (error) {
const sanitizedErrorMessage = syntheticsLogHelper.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 文件和报告中编辑的。
**参数 **
+ *headers* 是一个包含要清理的标题的对象。
+ *StepConfig*（可选）覆盖此函数的全局 Synthetics 配置。如果 `stepConfig` 未传入，则使用全局配置来清理标头。
## 仅适用于 UI 金丝雀的 Node.js 库类和函数
以下用于 Node.js 的 CloudWatch Synthetics 库函数仅适用于 UI 金丝雀。
**Topics**
+ [Synthetics 类](#CloudWatch_Synthetics_Library_Synthetics_Class)
+ [BrokenLinkCheckerReport 类](#CloudWatch_Synthetics_Library_BrokenLinkCheckerReport)
+ [SyntheticsLink 类](#CloudWatch_Synthetics_Library_SyntheticsLink)
### Synthetics 类
以下函数位于 Synthetics 类中。
**Topics**
+ [async addUserAgent(page, userAgentString);](#CloudWatch_Synthetics_Library_addUserAgent)
+ [async executeStep(stepName, functionToExecute, [stepConfig]);](#CloudWatch_Synthetics_Library_executeStep)
+ [getDefaultLaunchOptions();](#CloudWatch_Synthetics_Library_getDefaultLaunchOptions)
+ [getPage();](#CloudWatch_Synthetics_Library_getPage)
+ [getRequestResponseLogHelper();](#CloudWatch_Synthetics_Library_getRequestResponseLogHelper)
+ [launch(options)](#CloudWatch_Synthetics_Library_LaunchOptions)
+ [RequestResponseLogHelper 类](#CloudWatch_Synthetics_Library_RequestResponseLogHelper)
+ [setRequestResponseLogHelper();](#CloudWatch_Synthetics_Library_setRequestResponseLogHelper)
+ [async takeScreenshot(name, suffix);](#CloudWatch_Synthetics_Library_takeScreenshot)
#### 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]);
执行提供的步骤，并使用开始/通过/失败日志记录、开始/通过/失败屏幕截图，以及通过/失败和持续时间指标对其进行包装。
**注意**
如果您使用的是 `syn-nodejs-2.1` 或更高版本的运行时，您可以配置是否以及何时捕获屏幕截图。有关更多信息，请参阅 [SyntheticsConfiguration 类](#CloudWatch_Synthetics_Library_SyntheticsConfiguration)。
`executeStep` 函数还执行以下操作：
+ 记录步骤开始。
+ 获取名为 `-starting` 的屏幕截图。
+ 启动计时器。
+ 执行提供的函数。
+ 如果函数正常返回，则计为通过。如果函数引发异常，则计为失败。
+ 结束计时器。
+ 记录步骤是通过还是失败
+ 获取名为 `-succeeded` 或 ` -failed` 的屏幕截图。
+ 发出 `stepName` `SuccessPercent` 指标，100 表示通过，0 表示失败。
+ 发出 `stepName` `Duration` 指标，指标的值基于步骤开始和结束时间。
+ 最后，返回 `functionToExecute` 返回的内容或重新抛出 `functionToExecute` 抛出的内容。
如果金丝雀使用 `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 类](#CloudWatch_Synthetics_Library_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 使用的浏览器启动选项。有关更多信息，请参阅 [启动选项类型](https://pptr.dev/browsers-api/browsers.launchoptions/)
```
// This function returns default launch options used by Synthetics.
const defaultOptions = await synthetics.getDefaultLaunchOptions();
```
#### getPage();
返回当前打开的页面作为 Puppeteer 对象。有关更多信息，请参阅 [Puppeteer API v1.14.0](https://github.com/puppeteer/puppeteer/blob/v1.14.0/docs/api.md)。
示例：
```
let page = await synthetics.getPage();
```
响应：
在当前浏览器会话中打开的页面（Puppeteer 对象）。
#### getRequestResponseLogHelper();
**重要**
在使用 `syn-nodejs-puppeteer-3.2` 或更高版本运行时的金丝雀中，此函数将与 `RequestResponseLogHelper` 类一起弃用。对此函数的任何使用都会导致在金丝雀日志中出现警告。将在未来的运行时版本中删除此函数。如果您正在使用此函数，请改为使用 [RequestResponseLogHelper 类](#CloudWatch_Synthetics_Library_RequestResponseLogHelper)。
将此函数用作生成器模式，用于调整请求和响应日志记录标记。
示例：
```
synthetics.setRequestResponseLogHelper(getRequestResponseLogHelper().withLogRequestHeaders(false));;
```
响应：
```
{RequestResponseLogHelper}
```
#### launch(options)
此函数的选项仅在 `syn-nodejs-2.1` 版本或更高版本的运行时中可用。
此函数仅用于 UI 金丝雀。它的作用是关闭现有浏览器并启动一个新的浏览器。
**注意**
在开始运行脚本之前，CloudWatch Synthetics 始终启动浏览器。除非您想使用自定义选项启动新浏览器，否则不需要调用 launch()。
(options) 是在浏览器上设置的一组可配置的选项。有关更多信息，请参阅 [LaunchOptions 类型](https://pptr.dev/browsers-api/browsers.launchoptions/)。
如果您在不设置选项的情况下调用此函数，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 类
**重要**
在使用 `syn-nodejs-puppeteer-3.2` 或更高版本运行时的金丝雀中，此类将被弃用。对此类的任何使用都会导致在金丝雀日志中出现警告。将在未来的运行时版本中删除此函数。如果您正在使用此函数，请改为使用 [RequestResponseLogHelper 类](#CloudWatch_Synthetics_Library_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();
**重要**
在使用 `syn-nodejs-puppeteer-3.2` 或更高版本运行时的金丝雀中，此函数将与 `RequestResponseLogHelper` 类一起弃用。对此函数的任何使用都会导致在金丝雀日志中出现警告。将在未来的运行时版本中删除此函数。如果您正在使用此函数，请改为使用 [RequestResponseLogHelper 类](#CloudWatch_Synthetics_Library_RequestResponseLogHelper)。
将此函数用作成生器模式，用于设置请求和响应日志记录标记。
示例：
```
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('@aws/synthetics-broken-link-checker-report');
const brokenLinkCheckerReport = new BrokenLinkCheckerReport();
```
有用的函数定义：
**addLink(*syntheticsLink*, isBroken)**
` syntheticsLink ` 是一个 ` SyntheticsLink` 对象，表示链接。此函数根据状态代码添加链接。预设情况下，如果状态代码不可用或状态代码为 400 或以上，则其会将链接视为无效。您可以通过传入可选参数 `isBrokenLink`（带有值 `true` 或 `false`）来覆盖此默认行为。
此函数无返回值。
**getLinks()**
此函数返回一组 `SyntheticsLink` 对象，这些对象包含在无效链接检查器报告。
**getTotalBrokenLinks()**
此函数返回一个表示无效链接总数的数字。
**getTotalLinksChecked()**
此函数返回一个表示包含在报告中的链接总数的数字。
**如何使用 BrokenLinkCheckerReport**
以下金丝雀脚本代码段展示了导航到链接并将其添加到无效链接检查器报告的示例。
1. 导入 `SyntheticsLink`、`BrokenLinkCheckerReport` 和 ` Synthetics`。
```
const BrokenLinkCheckerReport = require('@aws/synthetics-broken-link-checker-report');
const SyntheticsLink = require('@aws/synthetics-link');
// Synthetics dependency
const synthetics = require('@aws/synthetics-puppeteer');
```
1. 若要向报告添加链接，请创建 ` BrokenLinkCheckerReport` 实例。
```
let brokenLinkCheckerReport = new BrokenLinkCheckerReport();
```
1. 导航到 URL 并将其添加到无效链接检查器报告中。
```
let url = "https://amazon.com";
let syntheticsLink = new SyntheticsLink(url);
// Navigate to the url.
let page = await synthetics.getPage();
// Create a new instance of Synthetics Link
let link = new SyntheticsLink(url)
try {
const response = await page.goto(url, {waitUntil: 'domcontentloaded', timeout: 30000});
} catch (ex) {
// Add failure reason if navigation fails.
link.withFailureReason(ex);
}
if (response) {
// Capture screenshot of destination page
let screenshotResult = await synthetics.takeScreenshot('amazon-home', 'loaded');
// Add screenshot result to synthetics link
link.addScreenshotResult(screenshotResult);
// Add status code and status description to the link
link.withStatusCode(response.status()).withStatusText(response.statusText())
}
// Add link to broken link checker report.
brokenLinkCheckerReport.addLink(link);
```
1. 将报告添加到 Synthetics。这样，金丝雀每次运行都会在 S3 存储桶中创建一个名为 ` BrokenLinkCheckerReport.json` 的 JSON 文件。您可以在控制台中查看金丝雀每次运行的链接报告以及屏幕截图、日志和 HAR 文件。
```
await synthetics.addReport(brokenLinkCheckerReport);
```
### SyntheticsLink 类
此类提供了包装信息的方法。仅在使用 `syn-nodejs-2.0-beta` 或更高版本运行时的金丝雀上支持此类。
若要使用 `SyntheticsLink`，脚本中需包括以下行：
```
const SyntheticsLink = require('@aws/synthetics-link');
const syntheticsLink = new SyntheticsLink("https://www.amazon.com");
```
此函数返回 `syntheticsLinkObject`
有用的函数定义：
**withUrl(*url*)**
` url ` 是一个 URL 字符串。此函数返回 `syntheticsLinkObject`
**withText(*text*)**
` text ` 是一个表示锚文本的字符串。此函数返回 `syntheticsLinkObject`。它会添加与链接相对应的锚文本。
**withParentUrl(*parentUrl*)**
` parentUrl ` 是一个表示父（源页面）URL 的字符串。此函数返回 `syntheticsLink Object`
**withStatusCode(*statusCode*)**
` statusCode ` 是一个表示状态代码的字符串。此函数返回 `syntheticsLinkObject`
**withFailureReason(*failureReason*)**
` failureReason ` 是一个表示故障原因的字符串。此函数返回 `syntheticsLink Object`
**addScreenshotResult(*screenshotResult*)**
` screenshotResult ` 是一个对象。它是 Synthetics 函数 `takeScreenshot` 返回的 `ScreenshotResult` 的实例。此对象包括以下属性：
+ `fileName` – 表示 ` screenshotFileName` 的字符串
+ `pageUrl`（可选）
+ `error`（可选）
## 仅适用于 API 金丝雀的 Node.js 库类和函数
以下用于 Node.js 的 CloudWatch Synthetics 库函数仅适用于 API 金丝雀。
**Topics**
+ [executeHttpStep(stepName, requestOptions, [callback], [stepConfig])](#CloudWatch_Synthetics_Library_executeHttpStep)
### executeHttpStep(stepName, requestOptions, [callback], [stepConfig])
作为步骤执行提供的 HTTP 请求，并发布 `SuccessPercent`（通过/失败）和 `Duration` 指标。
**executeHttpStep** 在后台使用 HTTP 或 HTTPS 本机函数，具体取决于请求中指定的协议。
此函数还将步骤执行摘要添加到金丝雀的报告中。摘要中包括有关每个 HTTP 请求的详细信息，如下所示：
+ 开始时间
+ 结束时间
+ 状态 (PASSED/FAILED)
+ 故障原因（如失败）
+ HTTP 调用详细信息，如请求/响应标头、请求/响应体、状态代码、状态消息和性能计时。
**Topics**
+ [参数](#CloudWatch_Synthetics_Library_executeHttpStep_parameters)
+ [executeHttpStep 的使用示例](#CloudWatch_Synthetics_Library_executeHttpStep_examples)
#### 参数
**stepName(*String*)**
指定步骤的名称。此名称也用于发布此步骤的 CloudWatch 指标。
**requestOptions(*Object or String*)**
此参数的值可以是 URL、URL 字符串或对象。如果为对象，则必须是用以发出 HTTP 请求的一组可配置选项。其支持 Node.js 文档中 [http.request(options[, callback])](https://nodejs.org/api/http.html#http_http_request_options_callback) 中的所有选项。
除了这些 Node.js 选项之外，**requestOptions** 支持附加参数 `body`。您可以使用 `body` 参数将数据作为请求体传递。
**callback(*response*)**
（可选）此函数是与 HTTP 响应一起调用的用户函数。响应的类型为 [Class: http.IncomingMessage](https://nodejs.org/api/http.html#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 金丝雀](CloudWatch_Synthetics_Canaries_Samples.md#CloudWatch_Synthetics_Canaries_Samples_APIsteps)。