# 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 のみに適用されるライブラリクラスおよび関数](#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` のいずれかを有効にした場合、aws-sdk v3 クライアントを含む、一部の API からのレスポンスではデータオブジェクトが返されません。これは、Node.js の制限と使用されるレスポンスオブジェクトのタイプに起因する現象です。
**CloudWatch メトリクスに関する setConfig (オプション)**
`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 に適用されます。パラメータ名では大文字と小文字が区別されます。アスタリスク (\*) を値として渡すと、すべての URL パスおよびクエリパラメータ値を墨消しできます。デフォルトは、空白の配列です。
+ `logRequest`（ブール値）-すべてのリクエストを Canary ログに記録するかどうか。UI Canary の場合、ブラウザから送信された各リクエストがログに記録されます。デフォルトは `true` です。
+ `logResponse`（ブール値）-すべてのレスポンスを Canary ログに記録するかどうか。UI Canary の場合、ブラウザが受信したすべてのレスポンスをログに記録します。デフォルトは `true` です。
+ `logRequestBody`（ブール値）-リクエスト本文を Canary ログのリクエストとともに記録するかどうか。この設定は、`logRequest` が `true` である場合にのみ適用されます。デフォルトは `false` です。
+ `logResponseBody`（ブール値）-レスポンス本文を Canary ログのレスポンスとともに記録するかどうか。この設定は、`logResponse` が `true` である場合にのみ適用されます。デフォルトは ` false` です。
**重要**
`includeResponseBody` または ` logResponseBody` のいずれかを有効にした場合、aws-sdk v3 クライアントを含む、一部の API からのレスポンスではデータオブジェクトが返されません。これは、Node.js の制限と使用されるレスポンスオブジェクトのタイプに起因する現象です。
+ `logRequestHeaders`（ブール値）-リクエストヘッダーを Canary ログのリクエストとともに記録するかどうか。この設定は、`logRequest` が `true` である場合にのみ適用されます。デフォルトは ` false` です。
`includeRequestHeaders` は、アーティファクトのヘッダーを有効にすることに注意してください。
+ `logResponseHeaders`（ブール値）-レスポンスヘッダーを Canary ログのレスポンスとともに記録するかどうか。この設定は、`logResponse` が `true` である場合にのみ適用されます。デフォルトは ` false` です。
`includeResponseHeaders` は、アーティファクトのヘッダーを有効にすることに注意してください。
**注記**
`Duration` メトリクスと `SuccessPercent` メトリクスは、`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 の関数**
+ `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 での使用**
まず、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
});
```
または
```
synConfig.withScreenshotOnStepStart(false).withScreenshotOnStepSuccess(true).withScreenshotOnStepFailure(true)
```
すべてのスクリーンショットを無効にするには、次の例のように `disableStepScreenshots()` 関数を使用します。
```
synConfig.disableStepScreenshots();
```
コード内の任意の個所でスクリーンショットを有効または無効にすることができます。例えば、1 つのステップでのみスクリーンショットを無効にするには、そのステップを実行する前にスクリーンショットを無効にしてステップの実行後に有効にします。
##### API Canary の setConfig(options)
API Canary の場合、**setConfig** には次のブール値のパラメータを含めることができます。
+ `continueOnHttpStepFailure` (ブール値) – HTTP ステップが失敗した後も Canary スクリプトの実行を続行するかどうか (これは **executeHttpStep** 関数を参照します)。いずれかのステップが失敗しても、Canary 実行は失敗としてマークされます。デフォルト: `true`。
#### ビジュアルモニターリング
ビジュアルモニターリングは、Canary 実行中に撮影されたスクリーンショットと、ベースライン Canary 実行中に撮影されたスクリーンショットを比較します。2 つのスクリーンショットの不一致がしきい値のパーセンテージを超えると、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("\#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('@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 は、Synthetics の構成設定 `restrictedUrlParameters` に基づいて、ログ、レポート、HAR ファイル、および Canary 実行エラーに含める前に、ログに記録されるすべての URL とエラーメッセージをサニタイズします。` getSanitizedUrl` または `getSanitizedErrorMessage` は、スクリプトに URL またはエラーを記録している場合にのみ使用できます。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`1を設定することで、パスワードや access\_token などの機密性の高い URL を編集するように選択できます。デフォルトでは、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 実行 Artifact を保存しないことに注意してください。ログ、スクリーンショット、レポートなどの Artifact は、すべてカスタマーアカウントの 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 をサニタイズすることによって、サニタイズされたエラー文字列を返します。この関数を呼び出すときに、オプションの`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);
}
```
これは、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 ファイル、およびレポートから編集されます。
**パラメータ**
+ {{headers}} は、サニタイズするヘッダーを含むオブジェクトです。
+ {{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)
+ [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);
この関数は、指定されたページの user-agent ヘッダーに {{userAgentString}} を追加します。
例:
```
await synthetics.addUserAgent(page, "MyApp-1.0");
```
ページの user-agent ヘッダーが `{{ browsers-user-agent-header-value}}MyApp-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 のレポートに追加します。要約には、開始時刻、終了時刻、ステータス (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)」を参照してください。
次の例では、` 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 で使用するブラウザ起動オプションを返します。詳細については、「[起動オプションの種類](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 クラス](#CloudWatch_Synthetics_Library_RequestResponseLogHelper) を使用してください。
この関数は、リクエストとレスポンスのログ記録フラグを調整するためのビルダーパターンとして使用します。
例:
```
synthetics.setRequestResponseLogHelper(getRequestResponseLogHelper().withLogRequestHeaders(false));;
```
レスポンス:
```
{RequestResponseLogHelper}
```
#### launch(options)
この関数のオプションは、`syn-nodejs-2.1` ランタイムバージョン以降でのみ使用できます。
この関数は UI Canary でのみ使用します。これは、既存のブラウザを閉じ、新しいブラウザを起動します。
**注記**
CloudWatch Synthetics は、スクリプトの実行を開始する前に、必ずブラウザを起動します。カスタムオプションを使用して新しいブラウザを起動する場合を除いては、launch() を呼び出す必要はありません。
(options) は、ブラウザで設定する構成可能なオプションのセットです。詳細については、「[起動オプションの種類](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` フラグを追加します。
```
// 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` 以降のランタイムを使用する Canary で、このクラスは廃止予定です。このクラスを使用すると、Canary ログに警告が表示されます。この関数は、将来のランタイムバージョンで削除されます。この関数を使用している場合は、代わりに [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` 以降のランタイムを使用する Canary で、この関数は `RequestResponseLogHelper` クラスと共に廃止予定です。この関数を使用すると、Canary ログに警告が表示されます。この関数は、将来のランタイムバージョンで削除されます。この関数を使用している場合は、代わりに [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` という名前のスクリーンショットをキャプチャし、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('@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);
```
### SyntheticsLink クラス
このクラスは、情報をラップするメソッドを提供します。これは、`syn-nodejs-2.0-beta` 以降のバージョンのランタイムを使用する Canary でのみサポートされています。
`SyntheticsLink` を使用するには、スクリプトに次の行を含めます。
```
const SyntheticsLink = require('@aws/synthetics-link');
const syntheticsLink = new SyntheticsLink("https://www.amazon.com");
```
この関数は、`syntheticsLink{{Object}}` を返します
有用な関数定義:
**withUrl({{url}})**
` {{url}} ` は URL 文字列です。この関数は、`syntheticsLink{{Object}}` を返します
**withText({{text}})**
` {{text}} ` はアンカーテキストを表す文字列です。この関数は `syntheticsLink{{Object}}` を返します。リンクに対応するアンカーテキストを追加します。
**withParentUrl({{parentUrl}})**
` {{parentUrl}} ` は、親 (ソースページ) URL を表す文字列です。この関数は、`syntheticsLink{{ Object}}` を返します
**withStatusCode({{statusCode}})**
` {{statusCode}} ` は、ステータスコードを表す文字列です。この関数は、`syntheticsLink{{Object}}` を返します
**withFailureReason({{failureReason}})**
` {{failureReason}} ` は、エラーの理由を表す文字列です。この関数は、`syntheticsLink{{ Object}}` を返します
**addScreenshotResult({{screenshotResult}})**
` {{screenshotResult}} ` はオブジェクトです。これは、Synthetics 関数 `ScreenshotResult` によって返された `takeScreenshot` のインスタンスです。このオブジェクトには以下が含まれています。
+ `fileName` – ` screenshotFileName` を表す文字列
+ `pageUrl` (オプション)
+ `error` (オプション)
## API Canary のみに適用されるライブラリクラスおよび関数
以下の CloudWatch Synthetics ライブラリ関数は、API Canary についてのみ有用です。
**Topics**
+ [executeHttpStep(stepName, requestOptions, [callback], [stepConfig])](#CloudWatch_Synthetics_Library_executeHttpStep)
### executeHttpStep(stepName, requestOptions, [callback], [stepConfig])
提供された HTTP リクエストをステップとして実行し、`SuccessPercent` (pass/fail) および `Duration` メトリクスを発行します。
**executeHttpStep** は、リクエストで指定されたプロトコルに応じて、HTTP または HTTPS ネイティブ関数のいずれかを内部で使用します。
この関数は、Canary のレポートにステップ実行の概要も追加します。概要には、次のような各 HTTP リクエストの詳細が含まれます。
+ 開始時間
+ 終了時間
+ ステータス (PASSED/FAILED)
+ 失敗の理由 (失敗した場合)
+ リクエスト/レスポンスヘッダー、本文、ステータスコード、ステータスメッセージ、パフォーマンスタイミングなどの HTTP 呼び出しの詳細。
**Topics**
+ [パラメータ](#CloudWatch_Synthetics_Library_executeHttpStep_parameters)
+ [executeHttpStep の使用例](#CloudWatch_Synthetics_Library_executeHttpStep_examples)
#### パラメータ
**stepName({{文字列}})**
ステップの名前を指定します。この名前は、このステップの CloudWatch メトリクスを発行する場合にも使用されます。
**requestOptions({{オブジェクトまたは文字列}})**
このパラメータの値には、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({{レスポンス}})**
(オプション) これは HTTP レスポンスで呼び出されるユーザー関数です。レスポンスは、[Class: http.IncomingMessage](https://nodejs.org/api/http.html#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](CloudWatch_Synthetics_Canaries_Samples.md#CloudWatch_Synthetics_Canaries_Samples_APIsteps)」を参照してください。