本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 適用於使用 Puppeteer 之 Node.js Canary 指令碼的程式庫函式
本節說明適用於 Node.js Canary 指令碼的程式庫函式。
**Topics**
+ [適用於所有 Canary 的 Node.js 程式庫類別和函數](#CloudWatch_Synthetics_Library_allcanaries)
+ [僅適用於 UI Canary 的 Node.js 程式庫類別和函數](#CloudWatch_Synthetics_Library_UIcanaries)
+ [僅適用於 API Canary 的 Node.js 程式庫類別和函數](#CloudWatch_Synthetics_Library_APIcanaries)
## 適用於所有 Canary 的 Node.js 程式庫類別和函數
下列適用於 Node.js 的 CloudWatch Synthetics 程式庫函數可用於所有 Canary。
**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 類別
以下適用於所有 Canary 的函數都在 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` 為您的 Canary 設定執行錯誤。它會在不中斷指令碼執行的情況下使 Canary 失敗。它也不會影響您的 `successPercent` 指標。
只有在錯誤表示 Canary 指令碼成功或失敗並不重要時，才應將錯誤追蹤為執行錯誤。
`addExecutionError` 的使用範例如下所示。您正在監控端點的可用性，並在頁面載入後擷取螢幕擷取畫面。由於擷取螢幕擷取畫面的失敗並不會決定端點的可用性，因此您可以捕捉擷取螢幕擷取畫面時遇到的任何錯誤，並將它們新增為執行錯誤。您的可用性指標仍會顯示端點已啟動並執行，但您的 Canary 狀態會標示為失敗。下面的範本程式碼區塊可捕獲這樣的錯誤，並將其新增為執行錯誤。
```
try {
await synthetics.takeScreenshot(stepName, "loaded");
} catch(ex) {
synthetics.addExecutionError('Unable to take screenshot ', ex);
}
```
#### getCanaryName();
傳回 Canary 的名稱。
#### getCanaryArn();
傳回 Canary 的 ARN。
#### getCanaryUserAgentString();
傳回 Canary 的自訂使用者代理程式。
#### getRuntimeVersion();
此函數在執行時間版本 `syn-nodejs-puppeteer-3.0` 和更新版本中可用。其會傳回 Canary 的 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 組態，這些組態適用於所有 Canary 步驟。也可以透過傳遞組態鍵值對來在步驟層級覆寫這些組態。
您可以在步驟層級傳遞選項。如需範例，請參閱 [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 ` 是一個物件，適用於您的 Canary 的可設定選項集。以下各節會說明了 ` options ` 中的可能欄位。
##### 適用於所有 Canary 的 setConfig(options)
對於使用 `syn-nodejs-puppeteer-3.2`或更新版本的 Canary，**setConfig** 的 **（選項）** 可以包含下列參數：
+ `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`或更新版本的 Canary，**setConfig** 的 **（選項）** 可以包含下列布林值參數，以決定 Canary 發佈哪些指標。這些選項的預設值為 `true`。以 `aggregated` 開頭的選項可判斷是否會發出沒有 ` CanaryName` 維度的指標。您可以使用這些指標來查看所有 Canary 的彙總結果。其他選項可判斷是否會發出具有 `CanaryName` 維度的指標。您可以使用這些指標來查看每個 Canary 的結果。
如需 Canary 發出的 CloudWatch 指標清單，請參閱 [Canary 公佈的 CloudWatch 指標](CloudWatch_Synthetics_Canaries_metrics.md)。
+ `failedCanaryMetric` (布林值)— 是否為此 canary 發出 ` Failed` 指標 (具有 `CanaryName` 維度)。預設值為 `true`。
+ `failedRequestsMetric` (布林值)— 是否為此 canary 發出 `Failed requests` 指標 (具有 `CanaryName` 維度)。預設值為 `true`。
+ `_2xxMetric` (布林值)— 是否為此 canary 發出 `2xx` 指標 (具有 `CanaryName` 維度)。預設值為 `true`。
+ `_4xxMetric` (布林值)— 是否為此 canary 發出 `4xx` 指標 (具有 `CanaryName` 維度)。預設值為 `true`。
+ `_5xxMetric` (布林值)— 是否為此 canary 發出 `5xx` 指標 (具有 `CanaryName` 維度)。預設值為 `true`。
+ `stepDurationMetric` (布林值)— 是否為此 canary 發出 `Step duration` 指標 (具有 `CanaryName` `StepName` 維度)。預設值為 `true`。
+ `stepSuccessMetric` (布林值)— 是否為此 canary 發出 `Step success` 指標 (具有 `CanaryName` `StepName` 維度)。預設值為 `true`。
+ `aggregatedFailedCanaryMetric` (布林值)— 是否為此 canary 發出 `Failed` 指標 (沒有 `CanaryName` 維度)。預設值為 `true`。
+ `aggregatedFailedRequestsMetric` (布林值)— 是否為此 canary 發出 `Failed Requests` 指標 (沒有 `CanaryName` 維度)。預設值為 `true`。
+ `aggregated2xxMetric` (布林值)— 是否為此 canary 發出 ` 2xx` 指標 (沒有 `CanaryName` 維度)。預設值為 `true`。
+ `aggregated4xxMetric` (布林值)— 是否為此 canary 發出 ` 4xx` 指標 (沒有 `CanaryName` 維度)。預設值為 `true`。
+ `aggregated5xxMetric` (布林值)— 是否為此 canary 發出 ` 5xx` 指標 (沒有 `CanaryName` 維度)。預設值為 `true`。
+ `visualMonitoringSuccessPercentMetric` (布林值)— 是否為此 canary 發出 `visualMonitoringSuccessPercent` 指標。預設值為 `true`。
+ `visualMonitoringTotalComparisonsMetric` (布林值)— 是否為此 canary 發出 `visualMonitoringTotalComparisons` 指標。預設值為 `false`。
+ `includeUrlPassword`(布林值) — 是否要包含在 URL 中顯示的密碼。依預設，在 URL 中顯示的密碼會從日誌和報告進行修訂，以防止揭露敏感資料。預設值為 `false`。
+ `restrictedUrlParameters` (陣列)— 要修訂的 URL 路徑或查詢參數清單。這適用於出現在日誌、報告和錯誤中的 URL。參數區分大小寫。您可以將星號 (\$1) 傳遞為數值，以修訂所有 URL 路徑和查詢參數值。預設為空陣列。
+ `logRequest` (布林值)— 是否要在 Canary 日誌中記錄每個請求。對於 UI Canary，這會記錄瀏覽器傳送的每個請求。預設值為 `true`。
+ `logResponse` (布林值)— 是否要在 Canary 日誌中記錄每個回應。對於 UI Canary，這會記錄瀏覽器收到的每個回應。預設值為 `true`。
+ `logRequestBody` (布林值)— 是否要在 Canary 日誌中記錄請求內文及請求。此組態僅在 `logRequest` 為 `true` 時適用。預設值為 `false`。
+ `logResponseBody` (布林值)— 是否要在 Canary 日誌中記錄回應內文及回應。此組態僅在 `logResponse` 為 `true` 時適用。預設值為 ` false`。
**重要**
如果您啟用 `includeResponseBody` 或 ` logResponseBody`，資料物件不會在部分 API 的回應中傳回，例如 aws-sdk v3 用戶端。這是因為 Node.js 的限制和使用的回應物件類型造成的。
+ `logRequestHeaders` (布林值)— 是否要在 Canary 日誌中記錄請求標頭及請求。此組態僅在 `logRequest` 為 `true` 時適用。預設值為 ` false`。
請注意，`includeRequestHeaders` 會啟用成品中的標頭。
+ `logResponseHeaders` (布林值)— 是否要在 Canary 日誌中記錄回應標頭及回應。此組態僅在 `logResponse` 為 `true` 時適用。預設值為 ` false`。
請注意，`includeResponseHeaders` 會啟用成品中的標頭。
**注意**
總是會針對每個 Canary 發出 `Duration` 和 `SuccessPercent` 指標，而無論是否有 `CanaryName` 指標。
##### 啟用或停用指標的方法
**disableAggregatedRequestMetrics()**
禁止 Canary 發出所有沒有 `CanaryName` 維度發出的請求指標。
**disableRequestMetrics()**
停用所有請求指標，包括每個 Canary 指標和彙總所有 Canary 的指標。
**disableStepMetrics()**
停用所有步驟指標，包括步驟成功指標和步驟持續時間指標。
**enableAggregatedRequestMetrics()**
啟用 Canary，使其可以發出所有沒有 ` CanaryName` 維度發出的請求指標。
**enableRequestMetrics()**
啟用所有請求指標，包括每個 Canary 指標和彙總所有 Canary 的指標。
**enableStepMetrics()**
啟用所有步驟指標，包括步驟成功指標和步驟持續時間指標。
**get2xxMetric()**
傳回 Canary 是否發出具有 ` CanaryName` 維度的 `2xx` 指標。
**get4xxMetric()**
傳回 Canary 是否發出具有 ` CanaryName` 維度的 `4xx` 指標。
**get5xxMetric()**
傳回 Canary 是否發出具有 ` CanaryName` 維度的 `5xx` 指標。
**getAggregated2xxMetric()**
傳回 Canary 是否發出沒有維度的 `2xx` 指標。
**getAggregated4xxMetric()**
傳回 Canary 是否發出沒有維度的 `4xx` 指標。
**getAggregatedFailedCanaryMetric()**
傳回 Canary 是否發出沒有維度的 `Failed` 指標。
**getAggregatedFailedRequestsMetric()**
傳回 Canary 是否發出沒有維度的 `Failed requests` 指標。
**getAggregated5xxMetric()**
傳回 Canary 是否發出沒有維度的 `5xx` 指標。
**getFailedCanaryMetric()**
傳回 Canary 是否發出具有 ` CanaryName` 維度的 `Failed` 指標。
**getFailedRequestsMetric()**
傳回 Canary 是否發出具有 `CanaryName` 維度的 `Failed requests` 指標。
**getStepDurationMetric()**
傳回 Canary 是否為此 Canary 發出具有 ` CanaryName` 維度的 `Duration` 指標。
**getStepSuccessMetric()**
傳回 Canary 是否為此 Canary 發出具有 ` CanaryName` 維度的 `StepSuccess` 指標。
**with2xxMetric(\$12xxMetric)**
接受布林值引數，它會指定是否為此 Canary 發出具有 `CanaryName` 維度的 `2xx` 指標。
**with4xxMetric(\$14xxMetric)**
接受布林值引數，它會指定是否為此 Canary 發出具有 `CanaryName` 維度的 `4xx` 指標。
**with5xxMetric(\$15xxMetric)**
接受布林值引數，它會指定是否為此 Canary 發出具有 `CanaryName` 維度的 `5xx` 指標。
**withAggregated2xxMetric(aggregated2xxMetric)**
接受布林值引數，它會指定是否為此 Canary 發出沒有維度的 `2xx` 指標。
**withAggregated4xxMetric(aggregated4xxMetric)**
接受布林值引數，它會指定是否為此 Canary 發出沒有維度的 `4xx` 指標。
**withAggregated5xxMetric(aggregated5xxMetric)**
接受布林值引數，它會指定是否為此 Canary 發出沒有維度的 `5xx` 指標。
** withAggregatedFailedCanaryMetric(aggregatedFailedCanaryMetric)**
接受布林值引數，它會指定是否為此 Canary 發出沒有維度的 `Failed` 指標。
** withAggregatedFailedRequestsMetric(aggregatedFailedRequestsMetric)**
接受布林值引數，它會指定是否為此 Canary 發出沒有維度的 `Failed requests` 指標。
**withFailedCanaryMetric(failedCanaryMetric)**
接受布林值引數，它會指定是否為此 Canary 發出具有 `CanaryName` 維度的 `Failed` 指標。
**withFailedRequestsMetric(failedRequestsMetric)**
接受布林值引數，它會指定是否為此 Canary 發出具有 `CanaryName` 維度的 `Failed requests` 指標。
**withStepDurationMetric(stepDurationMetric)**
接受布林值引數，它會指定是否為此 Canary 發出具有 `CanaryName` 維度的 `Duration` 指標。
**withStepSuccessMetric(stepSuccessMetric)**
接受布林值引數，它會指定是否為此 Canary 發出具有 `CanaryName` 維度的 ` StepSuccess` 指標。
##### 啟用或停用其他功能的方法
**withHarFile()**
接受布林值引數，它會指定是否為此 Canary 建立 HAR 檔案。
**withStepsReport()**
接受布林值引數，它會指定是否為此 Canary 報告步驟摘要。
**withIncludeUrlPassword()**
接受布林值引數，它會指定是否要在日誌和報告中包含在 URL 中顯示的密碼。
**withRestrictedUrlParameters()**
接受要修訂的 URL 路徑或查詢參數陣列。這適用於出現在日誌、報告和錯誤中的 URL。您可以將星號 (\$1) 傳遞為數值，以修訂所有 URL 路徑和查詢參數值
**withLogRequest()**
接受布林值引數，它會指定是否要在 Canary 日誌中記錄每個請求。
**withLogResponse()**
接受布林值引數，它會指定是否要在 Canary 日誌中記錄每個回應。
**withLogRequestBody()**
接受布林值引數，它會指定是否要在 Canary 日誌中記錄每個請求內文。
**withLogResponseBody()**
接受布林值引數，它會指定是否要在 Canary 日誌中記錄每個回應內文。
**withLogRequestHeaders()**
接受布林值引數，它會指定是否要在 Canary 日誌中記錄每個請求標頭。
**withLogResponseHeaders()**
接受布林值引數，它會指定是否要在 Canary 日誌中記錄每個回應。
**getHarFile()**
傳回 Canary 是否建立 HAR 檔案。
**getStepsReport()**
傳回 Canary 是否報告步驟執行摘要。
**getIncludeUrlPassword()**
傳回 Canary 是否要在日誌和報告中包含在 URL 中顯示的密碼。
**getRestrictedUrlParameters()**
傳回 Canary 是否修訂 URL 路徑或查詢參數。
**getLogRequest()**
傳回 Canary 是否記錄 Canary 日誌中的每個請求。
**getLogResponse()**
傳回 Canary 是否記錄 Canary 日誌中的每個回應。
**getLogRequestBody()**
傳回 Canary 是否記錄 Canary 日誌中的每個請求內文。
**getLogResponseBody()**
傳回 Canary 是否記錄 Canary 日誌中的每個回應內文。
**getLogRequestHeaders()**
傳回 Canary 是否記錄 Canary 日誌中的每個請求標頭。
**getLogResponseHeaders()**
傳回 Canary 是否記錄 Canary 日誌中的每個回應標頭。
**適用於所有 Canary 的函數**
+ `withIncludeRequestHeaders`(includeRequestHeaders)
+ `withIncludeResponseHeaders`(includeResponseHeaders)
+ `withRestrictedHeaders`(restrictedHeaders)
+ `withIncludeRequestBody`(includeRequestBody)
+ `withIncludeResponseBody`(includeResponseBody)
+ `enableReportingOptions`()— 啟用所有報告選項 – **includeRequestHeaders**、**includeResponseHeaders**、**includeRequestBody** 和 **includeResponseBody**、。
+ `disableReportingOptions`()— 停用所有報告選項 – **includeRequestHeaders**、**includeResponseHeaders**、**includeRequestBody** 和 **includeResponseBody**、。
##### 適用於 UI Canary 的 setConfig(options)
對於 UI Canary，**setConfig** 可以包括下列布林值參數：
+ `continueOnStepFailure` （布林值） — 是否在步驟失敗後繼續執行 Canary 指令碼 （這是指 ** executeStep** 函數）。如果任何步驟失敗，Canary 執行仍將被標記為失敗。預設值為 `false`。
+ `harFile` (布林值)— 是否建立 HAR 檔案。預設值為 `True`。
+ `screenshotOnStepStart` (布林值)— 是否在開始步驟之前擷取螢幕擷取畫面。
+ `screenshotOnStepSuccess` (布林值)— 是否在成功完成步驟之後擷取螢幕擷取畫面。
+ `screenshotOnStepFailure` (布林值)— 是否在步驟失敗之後擷取螢幕擷取畫面。
##### 啟用或停用螢幕擷取畫面的方法
**disableStepScreenshots()**
停用所有螢幕擷取畫面選項 (screenshotOnStepStart、screenshotOnStepSuccess 和 screenshotOnStepFailure)。
**enableStepScreenshots()**
啟用所有螢幕擷取畫面選項 (screenshotOnStepStart、screenshotOnStepSuccess 和 screenshotOnStepFailure)。預設不會啟用所有這些方法。
**getScreenshotOnStepFailure()**
傳回 Canary 是否在步驟失敗之後擷取螢幕擷取畫面。
**getScreenshotOnStepStart()**
傳回 Canary 是否在開始步驟之前擷取螢幕擷取畫面。
**getScreenshotOnStepSuccess()**
傳回 Canary 是否在成功完成步驟之後擷取螢幕擷取畫面。
**withScreenshotOnStepStart(screenshotOnStepStart)**
接受布林值引數，它會指示是否在開始步驟之前擷取螢幕擷取畫面。
**withScreenshotOnStepSuccess(screenshotOnStepSuccess)**
接受布林值引數，它會指示是否在成功完成步驟之後擷取螢幕擷取畫面。
**withScreenshotOnStepFailure(screenshotOnStepFailure)**
接受布林值引數，它會指示是否在步驟失敗之後擷取螢幕擷取畫面。
**在 UI Canary 中的使用方式**
首先，匯入綜合相依性並擷取組態。
```
// 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
});
```
或
```
synConfig.withScreenshotOnStepStart(false).withScreenshotOnStepSuccess(true).withScreenshotOnStepFailure(true)
```
若要停用所有螢幕擷取畫面，請使用本範例中的 `disableStepScreenshots()` 函式。
```
synConfig.disableStepScreenshots();
```
您可以在程式碼中的任何時候啟用和停用螢幕擷取畫面。例如，若只要停用一個步驟的螢幕擷取畫面，請在執行該步驟之前停用這些螢幕擷取畫面，然後在步驟之後予以啟用。
##### 適用於 API Canary 的 setConfig(options)
對於 API Canary，**setConfig** 可以包括下列布林值參數：
+ `continueOnHttpStepFailure` (布林值)— 是否在步驟失敗之後繼續執行 Canary 指令碼 (其代表 **executeHttpStep** 函數)。如果任何步驟失敗，Canary 執行仍將被標記為失敗。預設值為 `true`。
#### 視覺化監控
視覺化監控可比較在 Canary 執行期間擷取的螢幕擷取畫面與基準 Canary 執行期間擷取的螢幕擷取畫面。如果兩個螢幕擷取畫面之間的差異超出臨界值百分比，則 Canary 會失敗，您可以在 Canary 執行報告中看到顏色差異的區域。在執行 **syn-puppeteer-node-3.2** 或更新版本的 Canary 中支援視覺化監控。目前，執行 Python 和 Selenium 的 Canary 不支援它。
若要啟用視覺化監控，請將下列程式碼行新增至 Canary 指令碼。如需詳細資訊，請參閱[SyntheticsConfiguration 類別](#CloudWatch_Synthetics_Library_SyntheticsConfiguration)。
```
syntheticsConfiguration.withVisualCompareWithBaseRun(true);
```
將此行新增至指令碼之後，Canary 第一次成功執行時，它會使用該執行期間擷取的螢幕擷取畫面作為比較基準。在第一次 Canary 執行之後，您可以使用 CloudWatch 主控台編輯 Canary 來執行以下任何操作：
+ 將 Canary 的下一個執行設定為新基準。
+ 在目前的基準螢幕擷取畫面上繪製邊界，以指定要在視覺化比較期間忽略的螢幕擷取畫面區域。
+ 移除用於視覺化監控的螢幕擷取畫面。
如需使用 CloudWatch 主控台編輯 Canary 的詳細資訊，請參閱 [編輯或刪除 Canary](synthetics_canaries_deletion.md)。
**其他視覺化監控選項**
** syntheticsConfiguration.withVisualVarianceThresholdPercentage(desiredPercentage)**
在視覺化效果比較中，設定螢幕擷取畫面差異的可接受百分比。
** syntheticsConfiguration.withVisualVarianceHighlightHexColor("\$1fafa00")**
當您查看使用視覺化監控的 Canary 執行報告時，設定指定差異區域的反白顏色。
** syntheticsConfiguration.withFailCanaryRunOnVisualVariance(failCanary)**
設定當有視覺化差異超過閾值時，Canary 是否失敗。預設為 Canary 失敗。
### Synthetics Logger
Synthetics Logger 會將日誌同時寫入至主控台和相同日誌層級的本機日誌檔案。只有在日誌層級等於或低於呼叫之日誌函數所需的日誌層級時，才會將此日誌檔案同時寫入至這兩個位置。
本機日誌檔案中的日誌陳述式會加上「偵錯」、「資訊」等前綴，以符合呼叫之函數的日誌層級。
您可以使用 SyntheticsLogger，假設您要執行 Synthetics Library 的日誌層級與 Synthetics Canary 日誌相同。
使用 Synthetics Logger 並不需要建立上傳至 S3 結果位置的日誌檔案。您可改為在 ` /tmp` 資料夾中建立不同的日誌檔案。`/tmp` 資料夾下所建立的任何檔案都會上傳至 S3 中的結果位置作為成品。
如何使用 Synthetics 程式庫記錄器：
```
const log = require('@aws/synthetics-logger');
```
實用的函數定義：
**log.debug(*message*， *ex* )；**
參數：*訊息*是要記錄的訊息。*例如*，如果有，則是要記錄的例外狀況。
範例：
```
log.debug("Starting step - login.");
```
**log.error(*message*， *ex* )；**
參數：*訊息*是要記錄的訊息。*例如*，如果有，則是要記錄的例外狀況。
範例：
```
try {
await login();
catch (ex) {
log.error("Error encountered in step - login.", ex);
}
```
**log.info (*訊息*，*例如* )；**
參數：*訊息*是要記錄的訊息。*例如*，如果有，則是要記錄的例外狀況。
範例：
```
log.info("Successfully completed step - login.");
```
**log.log(*message*， *ex* )；**
這是 `log.info` 的別名。
參數：*訊息*是要記錄的訊息。*例如*，如果有，則是要記錄的例外狀況。
範例：
```
log.log("Successfully completed step - login.");
```
**log.warn(*message*， *ex* )；**
參數：*訊息*是要記錄的訊息。*例如*，如果有，則是要記錄的例外狀況。
範例：
```
log.warn("Exception encountered trying to publish CloudWatch Metric.", ex);
```
### SyntheticsLogHelper 類別
`SyntheticsLogHelper` 類別在執行時間 ` syn-nodejs-puppeteer-3.2` 和更新版本的執行時間中可用。它已經在 CloudWatch Synthetics 程式庫中初始化，並使用 Synthetics 組態進行設定。您可以在指令碼中將其新增為相依性。此類別可讓您淨化 URL、標頭和錯誤訊息，以修訂敏感資訊。
**注意**
Synthetics 會根據 Synthetics 器組態設定 `restrictedUrlParameters`，淨化其記錄的所有 URL 和錯誤訊息，然後在將它們納入日誌、報告、HAR 檔案和 Canary 執行錯誤。僅當您在指令碼中記錄 URL 或錯誤時，才必須使用 ` getSanitizedUrl` 或 `getSanitizedErrorMessage`。Synthetics 不會存放任何 Canary 成品，除了指令碼擲出的 Canary 錯誤。Canary 執行成品會存放於您的客戶帳戶中。如需詳細資訊，請參閱[Synthetics Canary 的安全考量](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 中的密碼已經修訂。如果需要，您可以啟用 URL 密碼，方法是將 `includeUrlPassword` 設定為 true。
如果傳入的 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 服務不會存放任何 Canary 執行成品。日誌、螢幕擷取畫面和報告等成品都儲存在客戶帳戶中的 Simple Storage Service (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');
```
這樣一來，將在您的 Canary 日誌中記錄以下內容。
```
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 傳回淨化的錯誤字串。當您呼叫此函數時，您可以選擇覆寫全域 Synthetics 組態，方法是傳遞選用 `stepConfig` 參數。
**參數**
+ *錯誤*是要淨化的錯誤。它可以是一個 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);
}
```
這樣一來，將在您的 Canary 日誌中記錄以下內容。
```
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 檔案和報告中進行修訂。
**參數**
+ *標頭*是一個包含要淨化的標頭的物件。
+ *stepConfig* (選用) 會覆寫此函數的全域 Synthetics 組態。如果 `stepConfig` 沒有傳入，則全域組態可用於淨化標頭。
## 僅適用於 UI Canary 的 Node.js 程式庫類別和函數
下列適用於 Node.js 的 CloudWatch Synthetics 程式庫函數僅可用於 UI Canary。
**Topics**
+ [Synthetics 類別](#CloudWatch_Synthetics_Library_Synthetics_Class)
+ [BrokenLinkCheckerReport 類別](#CloudWatch_Synthetics_Library_BrokenLinkCheckerReport)
+ [Synthetics 類別](#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 class](#CloudWatch_Synthetics_Library_RequestResponseLogHelper)
+ [setRequestResponseLogHelper();](#CloudWatch_Synthetics_Library_setRequestResponseLogHelper)
+ [async takeScreenshot(name, suffix);](#CloudWatch_Synthetics_Library_takeScreenshot)
#### async addUserAgent(page, userAgentString);
此函數會將 *userAgentString* 附加至指定頁面的使用者代理程式標頭。
範例：
```
await synthetics.addUserAgent(page, "MyApp-1.0");
```
頁面使用者代理程式標頭中的結果設為 ` 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` 已擲回的錯誤。
如果 canary 使用 `syn-nodejs-2.0` 執行時間或更新版本，此函數也會將步驟執行摘要新增至 Canary 報告。摘要包括每個步驟的詳細資訊，例如開始時間、結束時間、狀態 (通過/失敗)、失敗原因 (如果失敗)，以及每個步驟執行期間擷取的螢幕擷取畫面。
範例：
```
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)。
下列範例會將 ` continueOnStepFailure` 的預設 `false` 組態覆寫為 `true`，並指定何時擷取螢幕擷取畫面。
```
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 使用的瀏覽器啟動選項。如需詳細資訊，請參閱 [LaunchOptions type](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` 執行時間或更新版本的 Canary 中，此函數會與 `RequestResponseLogHelper` 類別一起被取代。此函數的任何用法都會導致您的 Canary 日誌中出現警告。未來的執行時間版本中將會移除此函數。如果您正在使用此函數，請改用 [RequestResponseLogHelper class](#CloudWatch_Synthetics_Library_RequestResponseLogHelper)。
使用此函數作為建置器模式，調整請求和回應日誌旗標。
範例：
```
synthetics.setRequestResponseLogHelper(getRequestResponseLogHelper().withLogRequestHeaders(false));;
```
回應：
```
{RequestResponseLogHelper}
```
#### launch(options)
此函數的選項僅適用於 `syn-nodejs-2.1` 執行時間版本或更新版本。
此函數僅用於 UI Canary。它會關閉現有的瀏覽器並啟動一個新的瀏覽器。
**注意**
CloudWatch Synthetics 始終會在開始執行指令碼之前啟動瀏覽器。除非您想啟動具有自訂選項的新瀏覽器，否則不需要呼叫 launch()。
(選項) 是可設定選項集，可在瀏覽器上設定。如需詳細資訊，請參閱[啟動選項類型](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
}});
```
下列範本程式碼會向新的 `ignoreHTTPSErrors` 參數新增至 CloudWatch Synthetics 啟動參數：
```
await synthetics.launch({
ignoreHTTPSErrors: true
});
```
您可以透過將 `--disable-web-security` 旗標新增至 CloudWatch Synthetics 啟動參數中的引數：
```
// 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
**重要**
在使用 `syn-nodejs-puppeteer-3.2` 執行時間或更新版本的 Canary 中，此類別會被取代。此類別的任何用法都會導致您的 Canary 日誌中出現警告。未來的執行時間版本中將會移除此函數。如果您正在使用此函數，請改用 [RequestResponseLogHelper class](#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` 執行時間或更新版本的 Canary 中，此函數會與 `RequestResponseLogHelper` 類別一起被取代。此函數的任何用法都會導致您的 Canary 日誌中出現警告。未來的執行時間版本中將會移除此函數。如果您正在使用此函數，請改用 [RequestResponseLogHelper class](#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` 的螢幕擷取畫面至 Canary 的 S3 儲存貯體。
您可以透過將 ` stepName` 傳遞為第一個參數，擷取特定 Canary 的螢幕擷取畫面。螢幕擷取畫面會連結至報告中的 Canary 步驟，以協助您在偵錯時追蹤每個步驟。
CloudWatch Synthetics Canary 會在開始步驟之前 (`executeStep` 函數)，並在步驟完成後自動擷取螢幕擷取畫面 (除非您將 Canary 設定為停用螢幕擷取畫面)。您可以透過在 `takeScreenshot` 函數中傳入步驟名稱，來擷取更多的螢幕擷取畫面。
下列範例以 `signupForm` 為 `stepName` 的值擷取了螢幕擷取畫面。螢幕擷取畫面會命名為` 02-signupForm-address`，並將連結到 Canary 報告中名為 ` signupForm` 的步驟
```
await synthetics.takeScreenshot('signupForm', 'address')
```
### BrokenLinkCheckerReport 類別
此類別提供了新增綜合連結的方法。它只支援使用執行時間的 `syn-nodejs-2.0-beta` 版本或更新版本的 Canary。
若要使用 `BrokenLinkCheckerReport`，請在指令碼中包含下列幾行：
```
const BrokenLinkCheckerReport = require('@aws/synthetics-broken-link-checker-report');
const brokenLinkCheckerReport = new BrokenLinkCheckerReport();
```
實用的函數定義：
**addLink(*syntheticsLink*, isBroken)**
` syntheticsLink ` 是可代表連結的 ` SyntheticsLink` 物件。該函數可根據狀態碼新增連結。根據預設，如果狀態碼不可用或狀態碼為 400 或更高，則會將連結視為中斷。您可以透過傳入值為 `true` 或 `false` 的選用參數 `isBrokenLink` 來覆寫此預設行為。
此函數沒有傳回值。
**getLinks()**
此函數會傳回包含在中斷連結檢查程式報告中的 `SyntheticsLink` 物件陣列。
**getTotalBrokenLinks()**
該函數會傳回表示中斷連結總數的數字。
**getTotalLinksChecked()**
該函數會傳回一個數字，表示報告中包含的中斷連結總數。
**如何使用 BrokenLinkCheckerReport**
下面的 Canary 指令碼程式碼片段示範了導覽至連結，並將其新增至中斷連結檢查程式報告的範例。
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。如此一來，將針對每個 Canary 執行在您的 S3 儲存貯體中建立一個名為 ` BrokenLinkCheckerReport.json` JSON 檔案。您可以在主控台中看到每個 Canary 執行的連結報告，以及螢幕擷取畫面、日誌和 HAR 檔案。
```
await synthetics.addReport(brokenLinkCheckerReport);
```
### Synthetics 類別
此類別提供了可包裝資訊的方法。它只支援使用執行時間的 `syn-nodejs-2.0-beta` 版本或更新版本的 Canary 。
若要使用 `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 Canary 的 Node.js 程式庫類別和函數
下列適用於 Node.js 的 CloudWatch Synthetics 程式庫函數僅可用於 API Canary。
**Topics**
+ [executeHttpStep(stepName, requestOptions, [callback], [stepConfig])](#CloudWatch_Synthetics_Library_executeHttpStep)
### executeHttpStep(stepName, requestOptions, [callback], [stepConfig])
執行提供的 HTTP 請求作為一個步驟，並發布 `SuccessPercent` (通過/失敗) 和 `Duration` 指標。
**executeHttpStep** 根據請求中指定的通訊協定，深入使用 HTTP 或 HTTPS 原生函數。
此函數也會將步驟執行摘要新增至 Canary 報告。摘要包含每個 HTTP 請求的詳細資訊，如下所示：
+ 開始時間
+ 結束時間
+ 狀態 (通過/失敗)
+ 失敗的原因，如果失敗
+ HTTP 呼叫詳細資訊，如請求/回應標頭、內文、狀態碼、狀態訊息和效能計時。
**Topics**
+ [Parameters](#CloudWatch_Synthetics_Library_executeHttpStep_parameters)
+ [使用 executeHttpStep 的範例](#CloudWatch_Synthetics_Library_executeHttpStep_examples)
#### Parameters
**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*)**
(選用) 使用此參數，以此步驟的不同組態覆寫全域綜合組態。
#### 使用 executeHttpStep 的範例
以下範例系列會建立會相互建置，以說明此選項的各種用途。
這第一個範例設定了請求參數。您可以傳遞 URL 做為 ** requestOptions**：
```
let requestOptions = 'https://www.amazon.com';
```
或者你可以傳遞選項集：
```
let requestOptions = {
'hostname': 'myproductsEndpoint.com',
'method': 'GET',
'path': '/test/product/validProductName',
'port': 443,
'protocol': 'https:'
};
```
下一個範例會建立接受回應的回呼函數。預設情況下，如果未指定**回呼**，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 Canary](CloudWatch_Synthetics_Canaries_Samples.md#CloudWatch_Synthetics_Canaries_Samples_APIsteps)。