本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

使用 Puppeteer 的 Node.js Canary 指令碼可用的程式庫函數

本節說明適用於 Node.js Canary 指令碼的程式庫函數。

適用於所有 Canary 的 Node.js 程式庫類別和函數

下列適用於 Node.js 的 CloudWatch Synthetics 程式庫函數可用於所有 Canary。

Synthetics 類別

以下適用於所有 Canary 的函數都在 Synthetics 類別中。

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 程式庫的目前日誌層級。可能的值如下：

範例：

let logLevel = synthetics.getLogLevel();

setLogLevel();

設定 Synthetics 程式庫的日誌層級。可能的值如下：

範例：

synthetics.setLogLevel(0);

SyntheticsConfiguration 類別

此類別僅在 syn-nodejs-2.1 執行時間版本或更新版本中可用。

您可以使用 SyntheticsConfiguration類別來設定 Synthetics 程式庫函數的行為。例如，您可以使用此類別來將 executeStep() 函數設定為不擷取螢幕擷取畫面。

您可以在全域層級設定 CloudWatch Synthetics 組態，這些組態適用於所有 Canary 步驟。您也可以透過傳遞組態金鑰和值對，在步驟層級覆寫這些組態。

您可以在步驟層級傳遞選項。如需範例，請參閱 async executeStep(stepName, functionToExecute, [stepConfig]); 和 executeHttpStep(stepName, requestOptions, [callback], [stepConfig])

setConfig(options)

options 是一個物件，適用於您的 Canary 的可設定選項集。以下各節會說明了 options 中的可能欄位。

適用於所有 Canary 的 setConfig(options)

對於使用 syn-nodejs-puppeteer-3.2 或更新版本的 Canary，setConfig 的 (選項) 可以包含以下參數：

關於 CloudWatch 指標的 setConfig(options)

對於使用 syn-nodejs-puppeteer-3.1 或更新版本的 Canary，setConfig 的 (選項) 可以包含以下布林值參數，可確定 Canary 發佈哪些指標。這些選項的預設值為 true。以 aggregated 開頭的選項可判斷是否會發出沒有 CanaryName 維度的指標。您可以使用這些指標來查看所有 Canary 的彙總結果。其他選項可判斷是否會發出具有 CanaryName 維度的指標。您可以使用這些指標來查看每個 Canary 的結果。

啟用或停用指標的方法

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(_2xxMetric)

接受布林值引數，它會指定是否為此 Canary 發出具有 CanaryName 維度的 2xx 指標。

with4xxMetric(_4xxMetric)

接受布林值引數，它會指定是否為此 Canary 發出具有 CanaryName 維度的 4xx 指標。

with5xxMetric(_5xxMetric)

接受布林值引數，它會指定是否為此 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。您可以將星號 (*) 傳遞為數值，以修訂所有 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 的函數

適用於 UI Canary 的 setConfig(options)

對於 UI Canary，setConfig 可以包括下列布林值參數：

啟用或停用螢幕擷取畫面的方法

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('Synthetics');

// 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 可以包括下列布林值參數：

視覺化監控

視覺化監控可比較在 Canary 執行期間擷取的螢幕擷取畫面與基準 Canary 執行期間擷取的螢幕擷取畫面。如果兩個螢幕擷取畫面之間的差異超出臨界值百分比，則 Canary 會失敗，您可以在 Canary 執行報告中看到顏色差異的區域。在執行 syn-puppeteer-node-3.2 或更新版本的 Canary 中支援視覺化監控。目前，執行 Python 和 Selenium 的 Canary 不支援它。

若要啟用視覺化監控，請將下列程式碼行新增至 Canary 指令碼。如需詳細資訊，請參閱SyntheticsConfiguration 類別。

syntheticsConfiguration.withVisualCompareWithBaseRun(true);

將此行新增至指令碼之後，Canary 第一次成功執行時，它會使用該執行期間擷取的螢幕擷取畫面作為比較基準。在第一次 Canary 執行之後，您可以使用 CloudWatch 主控台編輯 Canary 來執行以下任何操作：

如需使用 CloudWatch 主控台編輯 Canary 的詳細資訊，請參閱 編輯或刪除 Canary。

其他視覺化監控選項

syntheticsConfiguration.withVisualVarianceThresholdPercentage(desiredPercentage)

在視覺化效果比較中，設定螢幕擷取畫面差異的可接受百分比。

syntheticsConfiguration.withVisualVarianceHighlightHexColor("#fafa00")

當您查看使用視覺化監控的 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('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 中的密碼已經修訂。如果需要，您可以啟用 URL 密碼，方法是將 includeUrlPassword 設定為 true。

如果傳入的 URL 不是有效的 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('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');

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('SyntheticsLogHelper');

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 參數。

參數

範例

此範例使用下列錯誤：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 = 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 檔案和報告中進行修訂。

參數

僅適用於 UI Canary 的 Node.js 程式庫類別和函數

下列適用於 Node.js 的 CloudWatch Synthetics 程式庫函數僅可用於 UI Canary。

Synthetics 類別

以下函數都在 Synthetics 類別中。

async addUserAgent(page, userAgentString);

此函數會將 userAgentString 附加至指定頁面的使用者代理程式標頭。

範例：

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

頁面使用者代理程式標頭中的結果設為 browsers-user-agent-header-valueMyApp-1.0

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

執行提供的步驟，使用開始/通過/失敗記錄、開始/通過/失敗螢幕擷取畫面及通過/失敗和持續時間指標進行包裝。

executeStep 函數還會執行下列操作：

如果 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 類別。

下列範例會將 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

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

getPage();

以 Puppeteer 物件形式傳回目前已開啟的頁面。如需詳細資訊，請參閱 Puppeteer API v1.14.0。

範例：

let page = await synthetics.getPage();

回應：

在目前瀏覽器工作階段中目前開啟的頁面 (Puppeteer 物件)。

getRequestResponseLogHelper();

使用此函數作為建置器模式，調整請求和回應日誌旗標。

範例：

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

回應：

{RequestResponseLogHelper}

launch(options)

此函數的選項僅適用於 syn-nodejs-2.1 執行時間版本或更新版本。

此函數僅用於 UI Canary。它會關閉現有的瀏覽器並啟動一個新的瀏覽器。

(選項) 是可設定選項集，可在瀏覽器上設定。如需詳細資訊，啟動選項類型為 。

如果您在沒有選項的情況下呼叫此函數，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

處理精細定義的組態以及請求和回應承載字串顯示方式的建立。

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 的螢幕擷取畫面至 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('BrokenLinkCheckerReport');
            
const brokenLinkCheckerReport = new BrokenLinkCheckerReport();

實用的函數定義：

addLink(syntheticsLink, isBroken)

syntheticsLink 是可代表連結的 SyntheticsLink 物件。該函數可根據狀態碼新增連結。根據預設，如果狀態碼不可用或狀態碼為 400 或更高，則會將連結視為中斷。您可以透過傳入值為 true 或 false 的選用參數 isBrokenLink 來覆寫此預設行為。

此函數沒有傳回值。

getLinks()

此函數會傳回包含在中斷連結檢查程式報告中的 SyntheticsLink 物件陣列。

getTotalBrokenLinks()

該函數會傳回表示中斷連結總數的數字。

getTotalLinksChecked()

該函數會傳回一個數字，表示報告中包含的中斷連結總數。

如何使用 BrokenLinkCheckerReport

下面的 Canary 指令碼程式碼片段示範了導覽至連結，並將其新增至中斷連結檢查程式報告的範例。

Synthetics 類別

此類別提供了可包裝資訊的方法。它只支援使用執行時間的 syn-nodejs-2.0-beta 版本或更新版本的 Canary 。

若要使用 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 Canary 的 Node.js 程式庫類別和函數

下列適用於 Node.js 的 CloudWatch Synthetics 程式庫函數僅可用於 API Canary。

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

執行提供的 HTTP 請求作為一個步驟，並發佈 SuccessPercent (通過/失敗) 和 Duration 指標。

executeHttpStep 根據請求中指定的通訊協定，深入使用 HTTP 或 HTTPS 原生函數。

此函數也會將步驟執行摘要新增至 Canary 報告。摘要包含每個 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)

(選用) 使用此參數，以此步驟的不同組態覆寫全域綜合組態。

使用 executeHttpStep 的範例

以下範例系列會建立會相互建置，以說明此選項的各種用途。

這第一個範例設定了請求參數。您可以將 URL 傳遞請求選項：

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。