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 (オプション)

syn-nodejs-puppeteer-3.1 以降を使用する Canary の場合、setConfig の (options) には、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 に対して 2xx ディメンションを持つ CanaryName メトリクスを出力するかどうかを指定します。

with4xxMetric(_4xxMetric)

ブール引数を受け入れます。この引数は、この Canary に対して 4xx ディメンションを持つ CanaryName メトリクスを出力するかどうかを指定します。

with5xxMetric(_5xxMetric)

ブール引数を受け入れます。この引数は、この Canary に対して 5xx ディメンションを持つ CanaryName メトリクスを出力するかどうかを指定します。

withAggregated2xxMetric(aggregated2xxMetric)

ブール引数を受け入れます。この引数は、この Canary に対してディメンションを持たない 2xx メトリクスを出力するかどうかを指定します。

withAggregated4xxMetric(aggregated4xxMetric)

ブール引数を受け入れます。この引数は、この Canary に対してディメンションを持たない 4xx メトリクスを出力するかどうかを指定します。

withAggregated5xxMetric(aggregated5xxMetric)

ブール引数を受け入れます。この引数は、この Canary に対してディメンションを持たない 5xx メトリクスを出力するかどうかを指定します。

withAggregatedFailedCanaryMetric(aggregatedFailedCanaryMetric)

ブール引数を受け入れます。この引数は、この Canary に対してディメンションを持たない Failed メトリクスを出力するかどうかを指定します。

withAggregatedFailedRequestsMetric(aggregatedFailedRequestsMetric)

ブール引数を受け入れます。この引数は、この Canary に対してディメンションを持たない Failed requests メトリクスを出力するかどうかを指定します。

withFailedCanaryMetric(failedCanaryMetric)

ブール引数を受け入れます。この引数は、この Canary に対して Failed ディメンションを持つ CanaryName メトリクスを出力するかどうかを指定します。

withFailedRequestsMetric(failedRequestsMetric)

ブール引数を受け入れます。この引数は、この Canary に対して Failed requests ディメンションを持つ CanaryName メトリクスを出力するかどうかを指定します。

withStepDurationMetric(stepDurationMetric)

ブール引数を受け入れます。この引数は、この Canary に対して Duration ディメンションを持つ CanaryName メトリクスを出力するかどうかを指定します。

withStepSuccessMetric(stepSuccessMetric)

ブール引数を受け入れます。この引数は、この Canary に対して StepSuccess ディメンションを持つ CanaryName メトリクスを出力するかどうかを指定します。

他の機能を有効または無効にする方法

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

ログおよびレポートの URL に表示されるパスワードを、Canary に含めるかどうかを返します。

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 での使用

まず、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
    });

または

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

すべてのスクリーンショットを無効にするには、次の例のように disableStepScreenshots() 関数を使用します。

synConfig.disableStepScreenshots();

コード内の任意の個所でスクリーンショットを有効または無効にすることができます。例えば、1 つのステップでのみスクリーンショットを無効にするには、そのステップを実行する前にスクリーンショットを無効にしてステップの実行後に有効にします。

API Canary の setConfig(options)

API Canary の場合、setConfig には次のブール値のパラメータを含めることができます。

ビジュアルモニターリング

ビジュアルモニターリングは、Canary 実行中に撮影されたスクリーンショットと、ベースライン Canary 実行中に撮影されたスクリーンショットを比較します。2 つのスクリーンショットの不一致がしきい値のパーセンテージを超えると、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

SyntheticsLogger は、コンソールと、同じログレベルのローカルログファイルの両方にログを書き込みます。このログファイルは、ログレベルが、呼び出されたログ関数の該当するログ記録レベル以下である場合にのみ、両方の場所に書き込まれます。

ローカルログファイルのログ記録ステートメントには、呼び出された関数のログレベルに合わせて「DEBUG:」や「INFO:」などが先頭に追加されます。

SyntheticsLogger は、Synthetics Canary ログ記録と同じログレベルで Synethetics ライブラリを実行する場合に使用できます。

S3 の結果の場所にアップロードされるログファイルを作成する場合、SyntheticsLogger を使用する必要はありません。代わりに、別のログファイルを /tmp フォルダ内に作成できます。/tmp フォルダ内に作成したファイルは、アーティファクトとして S3 の結果の場所にアップロードされます。

Synthetics Library logger を使用するには:

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 文字列を返します。プロパティ restrictedUrlParameters1を設定することで、パスワードや access_token などの機密性の高い URL を編集するように選択できます。デフォルトでは、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 実行 Artifact を保存しないことに注意してください。ログ、スクリーンショット、レポートなどの Artifact は、すべてカスタマーアカウントの 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');

これは、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 = 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);
}

これは、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);

この関数は、指定されたページの user-agent ヘッダーに userAgentString を追加します。

例:

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

ページの user-agent ヘッダーが browsers-user-agent-header-valueMyApp-1.0 に設定されます。

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

指定されたステップを実行します。ステップは、開始/合格/失敗のログ記録、開始/合格/失敗のスクリーンショット、合格/失敗と所要時間のメトリクスでラップされます。

executeStep 関数は、次のことも行います。

Canary が syn-nodejs-2.0 ランタイム以降を使用する場合、この関数はステップ実行の要約を Canary のレポートに追加します。要約には、開始時刻、終了時刻、ステータス (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 クラス」を参照してください。

次の例では、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 で使用するブラウザ起動オプションを返します。詳細については、「起動オプションの種類」を参照してください

// 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 Canary でのみ使用します。これは、既存のブラウザを閉じ、新しいブラウザを起動します。

(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 フラグを追加します。

// 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 という名前のスクリーンショットをキャプチャし、Canary の S3 バケットにアップロードします。

最初のパラメータとして stepName を渡すことにより、特定の Canary ステップのスクリーンショットを作成できます。スクリーンショットはレポートの Canary ステップにリンクされ、デバッグ中に各ステップを追跡するのに役立ちます。

CloudWatch Synthetics Canary は、ステップ (executeStep 関数) の開始前とステップ完了後に自動的にスクリーンショットを作成します (スクリーンショットを無効にするように Canary を設定している場合を除きます)。takeScreenshot 関数でステップ名を渡すことで、さらに多くのスクリーンショットを作成できます。

次の例では、stepName の値として signupForm を使用してスクリーンショットを作成します。スクリーンショットには 02-signupForm-address という名前が付けられ、Canary レポートで指定された signupForm という名前のステップにリンクされます。

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

BrokenLinkCheckerReport クラス

このクラスは、Synthetics リンクを追加するメソッドを提供します。これは、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 スクリプトコードスニペットは、リンクに移動して、リンク切れチェッカーレポートに追加する例を示しています。

SyntheticsLink クラス

このクラスは、情報をラップするメソッドを提供します。これは、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 関数 ScreenshotResult によって返された takeScreenshot のインスタンスです。このオブジェクトには以下が含まれています。

API Canary のみに適用されるライブラリクラスおよび関数

以下の CloudWatch Synthetics ライブラリ関数は、API Canary についてのみ有用です。

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

提供された HTTP リクエストをステップとして実行し、SuccessPercent (pass/fail) および Duration メトリクスを発行します。

executeHttpStep は、リクエストで指定されたプロトコルに応じて、HTTP または HTTPS ネイティブ関数のいずれかを内部で使用します。

この関数は、Canary のレポートにステップ実行の概要も追加します。概要には、次のような各 HTTP リクエストの詳細が含まれます。

パラメータ

stepName(文字列)

ステップの名前を指定します。この名前は、このステップの CloudWatch メトリクスを発行する場合にも使用されます。

requestOptions(オブジェクトまたは文字列)

このパラメータの値には、URL、URL 文字列、またはオブジェクトを指定できます。オブジェクトの場合、HTTP リクエストを行うために設定可能なオプションのセットである必要があります。Node.js ドキュメントの http.request(options[, callback]) のすべてのオプションをサポートしています。

これらの Node.js オプションに加えて、requestOptions では、追加のパラメータ body がサポートされます。body パラメータを使用して、データをリクエスト本文として渡すことができます。

callback(レスポンス)

(オプション) これは HTTP レスポンスで呼び出されるユーザー関数です。レスポンスは、Class: http.IncomingMessage のタイプです。

stepConfig(オブジェクト)

(オプション) このパラメータを使用して、このステップについて、異なる設定でグローバル Synthetics 設定を上書きします。

executeHttpStep の使用例

次の一連の例は、このオプションのさまざまな用途を説明するために、相互に関連しています。

この最初の例では、リクエストパラメータを設定します。requestOptions として 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」を参照してください。