# Canary スクリプトの作成
次のセクションでは、Canary スクリプトの作成方法と、Canary を他の AWS のサービス、外部依存関係、ライブラリと統合する方法について説明します。
**Topics**
+ [Java ランタイムを使用した Canary スクリプトの記述](Synthetics_WritingCanary_Java.md)
+ [Playwright ランタイムを使用した Node.js Canary スクリプトの記述](Synthetics_WritingCanary_Nodejs_Playwright.md)
+ [Puppeteer ランタイムを使用した Node.js Canary スクリプトの記述](CloudWatch_Synthetics_Canaries_WritingCanary_Nodejs_Pup.md)
+ [Python Canary スクリプトの記述](CloudWatch_Synthetics_Canaries_WritingCanary_Python.md)
+ [Node.js マルチチェックブループリントの JSON 設定の記述](CloudWatch_Synthetics_WritingCanary_Multichecks.md)
# Java ランタイムを使用した Canary スクリプトの記述
**Topics**
+ [Canary の Java プロジェクトの構造](#Synthetics_canary_Java_package)
+ [Canary プロジェクトのパッケージ化](#Synthetics_canary_Java_package_canary)
+ [ハンドラー名](#Synthetics_canary_Java_handler)
+ [CloudWatch Synthetics の設定](#Synthetics_canary_Java_config)
+ [CloudWatch Synthetics 環境変数](#Synthetics_canary_Java_variables)
## Canary の Java プロジェクトの構造
Java で Canary を作成するには、記述したコードをコンパイルし、コンパイル後のアーティファクトを Synthetics にデプロイする必要があります。Java Lambda プロジェクトはさまざまな方法で初期化できます。例えば、IntelliJ IDEA や Visual Studio Code といった任意の IDE での標準 Java プロジェクト設定などを使用できます。または、必要なファイル構造を手動で作成することもできます。
Synthetics Java プロジェクトの一般的な構造は、次のとおりです。
```
/project-root
└ src
└ main
└ java
└ canarypackage // name of package
| └ ExampleCanary.java // Canary code file
| └ other_supporting_classes
- resources
└ synthetics.json // Synthetics configuration file
└ build.gradle OR pom.xml
```
Maven または Gradle を使用してプロジェクトを構築し、依存関係を管理できます。
上記の構造の `ExampleCanary` クラスは、Canary のエントリポイントまたはハンドラーです。
**Java Canary クラスの例**
この例では、Canary が Lambda 環境変数 *TESTING\$1URL* に格納されている URL に対して、get リクエストを実行しています。Canary は Synthetics ランタイムのメソッドは使用しません。
```
package canarypackage;
import java.net.HttpURLConnection;
import java.net.URL;
// Handler value: canary.ExampleCanary::canaryCode
public class ExampleCanary {
public void canaryCode() throws Exception{
URL url = new URL(System.getenv("TESTING_URL"));
HttpURLConnection con=(HttpURLConnection)url.openConnection();
con.setRequestMethod("GET");
con.setConnectTimeout(5000);
con.setReadTimeout(5000);
int status=con.getResponseCode();
if(status!=200){
throw new Exception("Failed to load " + url + ", status code: " + status);
}
}
}
```
Synthetics のライブラリ関数 `executeStep` を使用して、Canary をモジュール化することを強くお勧めします。Canary は環境変数 URL1 および URL2 から取得した 2 つの URL に対して `get` 呼び出しを実行します。
**注記**
`executeStep` の機能を使用するには、Canary のハンドラーメソッドで、次に示すようにタイプ Synthetics のパラメータを使用する必要があります。
```
package canarypackage;
import com.amazonaws.synthetics.Synthetics;
import java.net.HttpURLConnection;
import java.net.URL;
// Handler value: canary.ExampleCanary::canaryCode
public class ExampleCanary {
public void canaryCode(Synthetics synthetics) throws Exception {
createStep("Step1", synthetics, System.getenv("URL1"));
createStep("Step2", synthetics, System.getenv("URL2"));
return;
}
private void createStep(String stepName, Synthetics synthetics, String url) throws Exception{
synthetics.executeStep(stepName,()->{
URL obj=new URL(url);
HttpURLConnection con=(HttpURLConnection)obj.openConnection();
con.setRequestMethod("GET");
con.setConnectTimeout(5000);
con.setReadTimeout(5000);
int status=con.getResponseCode();
if(status!=200){
throw new Exception("Failed to load" + url + "status code:" + status);
}
return null;
}).get();
}
}
```
## Canary プロジェクトのパッケージ化
Synthetics は Java Canary のコードを *zip* 形式で受け入れます。Canary コードの zip は、Canary コード用のクラスファイル、サードパーティーの依存関係用の jar ファイル、Synthetics の設定ファイルで構成されます。
Synthetics Java の zip ファイルの一般的な構造は、次のとおりです。
```
example-canary
└ lib
| └ //third party dependency jars
└ java-canary.jar
└ synthetics.json
```
上記のプロジェクト構造からこの zip をビルドするには、gradle (build.gradle) または maven (pom.xml) を使用します。以下はその例です。
Synthetics ライブラリのコンパイル時の依存関係やインターフェイスについては、[aws-cloudwatch-synthetics-sdk-java](https://github.com/aws/aws-cloudwatch-synthetics-sdk-java/tree/main) の README を参照してください。
```
plugins {
id 'java'
}
repositories {
mavenCentral()
}
dependencies {
// Third party dependencies
// example: implementation 'software.amazon.awssdk:s3:2.31.9'
// Declares dependency on Synthetics interfaces for compiling only
// Refer https://github.com/aws/aws-cloudwatch-synthetics-sdk-java for building from source.
compileOnly 'software.amazon.synthetics:aws-cloudwatch-synthetics-sdk-java:1.0.0'}
test {
useJUnitPlatform()
}
// Build the zip to be used as Canary code.
task buildZip(type: Zip) {
archiveFileName.set("example-canary.zip")
destinationDirectory.set(file("$buildDir"))
from processResources
into('lib') {
from configurations.runtimeClasspath
from(tasks.named("jar"))
}
from "src/main/java/resources/synthetics.json"
doLast {
println "Artifact written to: ${archiveFile.get().asFile.absolutePath}"
}
}
java {
toolchain {
languageVersion = JavaLanguageVersion.of(21)
}
}
tasks.named("build") {
dependsOn "buildZip"
}
```
## ハンドラー名
ハンドラー名は Canary のエントリポイントです。Java ランタイムの場合、ハンドラーは次の形式になります。
```
<>::<>
// for above code: canarypackage.ExampleCanary::canaryCode
```
## CloudWatch Synthetics の設定
Synthetics Java ランタイムの動作を設定するには、`synthetics.json` という名前のオプション JSON 設定ファイルを指定します。このファイルは、パッケージ化して zip パッケージのルートディレクトリに配置する必要があります。設定ファイルはオプションですが、設定ファイルを指定しない場合、または設定キーがない場合、CloudWatch はデフォルトを使用します。
サポートされている設定値とそのデフォルト値を次に示します。
```
{
"step": {
"stepSuccessMetric": true,
"stepDurationMetric": true,
"continueOnStepFailure": false,
"stepsReport": true
},
"logging": {
"logRequest": false,
"logResponse": false
},
"httpMetrics": {
"metric_2xx": true,
"metric_4xx": true,
"metric_5xx": true,
"aggregated2xxMetric": true,
"aggregated4xxMetric": true,
"aggregated5xxMetric": true
},
"canaryMetrics": {
"failedCanaryMetric": true,
"aggregatedFailedCanaryMetric": true
}
}
```
**ステップ設定**
+ *continueOnStepFailure* – ステップが失敗した後もスクリプトを続行するかどうかを決定します。デフォルトは False です。
+ *stepSuccessMetric* – ステップの ` SuccessPercent` メトリクスが出力されるかどうかを決定します。ステップの `SuccessPercent` メトリクスは、ステップが成功した場合は Canary 実行の値が *100* になり、ステップが失敗した場合は *0* になります。デフォルトは *True* です。
+ *stepDurationMetric* – ステップの *Duration* メトリクスが出力されるかどうかを決定します。出力される *Duration* メトリクスは、ミリ秒単位でステップの経過時間を表します。デフォルトは *true* です。
**ロギング設定**
CloudWatch Synthetics によって生成されたログに適用されます。リクエストログとレスポンスログの詳細度を制御します。
+ *logRequest* - すべてのリクエストを Canary ログに記録するかどうかを指定します。デフォルトは False です。
+ *logResponse* - すべてのレスポンスを Canary ログに記録するかどうかを指定します。デフォルトは False です。
**HTTP メトリクス設定**
この Canary の CloudWatch Synthetics によって出力される、異なる HTTP ステータスコードを持つネットワークリクエストの数に関連するメトリクスの設定。
+ *metric\$12xx* – この Canary の *2xx* メトリクスを (canaryName ディメンションと一緒に) 出力するかどうかを指定します。デフォルトは *True* です。
+ *metric\$14xx* – この Canary の *4xx* メトリクスを (canaryName ディメンションと一緒に) 出力するかどうかを指定します。デフォルトは *True* です。
+ *metric\$15xx* – この Canary の *5xx* メトリクスを (canaryName ディメンションと一緒に) 出力するかどうかを指定します。デフォルトは *True* です。
+ *aggregated2xxMetric* – この Canary の *2xx* メトリクスを (canaryName ディメンションは出力せずに) 出力するかどうかを指定します。デフォルトは *True* です。
+ *aggregated4xxMetric* – この Canary の *4xx* メトリクスを (canaryName ディメンションは出力せずに) 出力するかどうかを指定します。デフォルトは *True* です。
+ *aggregated5xxMetric* – この Canary の *5xx* メトリクスを (canaryName ディメンションは出力せずに) 出力するかどうかを指定します。デフォルトは *True* です。
**Canary メトリクス設定**
CloudWatch Synthetics によって出力される他のメトリクスの設定。
+ *failedCanaryMetric* Network Access Analyzer でこの Canary の *Failed* メトリクスを (canaryName ディメンションと一緒に) 出力するかどうかを指定します。デフォルトは *True* です。
+ *aggregatedFailedCanaryMetric* – この Canary の *Failed* メトリクスを (CanaryName ディメンションは出力せずに) 出力するかどうかを指定します。デフォルトは *True* です。
## CloudWatch Synthetics 環境変数
環境変数を使用してログ記録レベルと形式を設定できます。
**ログ形式**
CloudWatch Synthetics Java ランタイムは、Canary の実行ごとに CloudWatch ログを作成します。ログは、クエリしやすいように JSON 形式で書き込まれます。必要に応じて、ログ形式を *TEXT* に変更できます。
+ *環境変数名* – CW\$1SYNTHETICS\$1LOG\$1FORMAT
+ *サポートされる値* – JSON、TEXT
+ *デフォルト* – JSON
**ログレベル**
+ *環境変数名* – CW\$1SYNTHETICS\$1LOG\$1LEVEL
+ *サポートされる値* – TRACE、DEBUG、INFO、WARN、ERROR、FATAL
+ *デフォルト* – INFO
上記の環境変数以外に、Java ランタイム用のデフォルトの環境変数、`AWS_LAMBDA-EXEC_WRAPPER` 環境変数が関数に追加され、その値が `/opt/synthetics-otel-instrument` に設定されます。この環境変数によりテレメトリの関数の起動時動作が変更されます。この環境変数が既に存在する場合は、必要な値に設定されていることを確認してください。
# Playwright ランタイムを使用した Node.js Canary スクリプトの記述
**Topics**
+ [Playwright ランタイム用の Node.js Canary ファイルのパッケージ化](#Synthetics_canary_Nodejs_Playwright_package)
+ [既存の Playwright スクリプトを変更して CloudWatch Synthetics の Canary として使用する](#CloudWatch_Synthetics_canary_edit_Playwright_script)
+ [CloudWatch Synthetics の設定](#Synthetics_canary_configure_Playwright_script)
## Playwright ランタイム用の Node.js Canary ファイルのパッケージ化
Canary スクリプトは、Synthetics ハンドラーコードを含む `.js` (CommonJS 構文) または `.mjs` (ES 構文) ファイルと、コードが依存する追加のパッケージやモジュールで構成されます。ES (ECMAScript) 形式で作成されたスクリプトは、拡張子として .mjs を使用するか、"type": "module" フィールドが設定された package.json ファイルを含める必要があります。Node.js Puppeteer などの他のランタイムとは異なり、スクリプトを特定のフォルダ構造に保存する必要はありません。スクリプトを直接パッケージ化できます。任意の `zip` ユーティリティを使用して、ハンドラーファイルをルートに置く `.zip` ファイルを作成します。Canary スクリプトが Synthetics ランタイムに含まれていない追加のパッケージまたはモジュールに依存している場合は、これらの依存関係を `.zip` ファイルに追加できます。そのためには、`npm install` コマンドを実行して、関数に必要なライブラリを `node_modules` ディレクトリにインストールします。次の CLI コマンドの例では、`index.js` または `index.mjs` ファイル (Synthetics ハンドラー) とその依存関係を含む `my_deployment_package.zip` という名前の `.zip` ファイルを作成します。この例では、`npm` パッケージマネージャーを使用して依存関係をインストールします。
```
~/my_function
├── index.mjs
├── synthetics.json
├── myhelper-util.mjs
└── node_modules
├── mydependency
```
プロジェクトフォルダの内容を含む `.zip` ファイルをルートに作成します。次の例で示すように `r` (再帰的) オプションを使用して、`zip` がサブフォルダを確実に圧縮するようにします。
```
zip -r my_deployment_package.zip .
```
Synthetics 設定ファイルを追加して、CloudWatch Synthetics の動作を設定します。`synthetics.json` ファイルを作成し、エントリポイントまたはハンドラーファイルと同じパスに保存できます。
オプションで、選択したフォルダ構造にエントリポイントファイルを保存することもできます。ただし、フォルダパスがハンドラー名で指定されていることを確認してください。
**ハンドラー名**
スクリプトのエントリポイント (ハンドラー) のファイル名に一致するように、Canary のスクリプトのエントリポイントを ` myCanaryFilename.functionName` として設定します。オプションで Canary を ` myFolder/my_canary_filename.mjs` などの別のフォルダに保存できます。別のフォルダに保存する場合は、スクリプトエントリポイントでそのパスを指定します (` myFolder/my_canary_filename.functionName` など)。
## 既存の Playwright スクリプトを変更して CloudWatch Synthetics の Canary として使用する
Node.js と Playwright の既存のスクリプトを編集して Canary として使用できます。Playwright の詳細については、「[Playwright ライブラリ](https://playwright.dev/docs/api/class-playwright)」のドキュメントを参照してください。
ファイル ` exampleCanary.mjs` に保存されている次の Playwright スクリプトを使用できます。
```
import { chromium } from 'playwright';
import { expect } from '@playwright/test';
const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto('https://example.com', {timeout: 30000});
await page.screenshot({path: 'example-home.png'});
const title = await page.title();
expect(title).toEqual("Example Domain");
await browser.close();
```
次のステップを実行してスクリプトを変換します。
1. `handler` 関数を作成してエクスポートします。このハンドラーは、スクリプトのエントリポイント関数です。ハンドラー関数には任意の名前を選択できますが、スクリプトで使用される関数は Canary ハンドラーと同じである必要があります。スクリプト名が `exampleCanary.mjs` で、ハンドラ関数名が `myhandler` の場合、Canary ハンドラの名前は `exampleCanary.myhandler` になります。次の例では、ハンドラー関数名は `handler` です。
```
exports.handler = async () => {
// Your script here
};
```
1. `Synthetics Playwright module` を依存関係としてインポートします。
```
import { synthetics } from '@aws/synthetics-playwright';
```
1. Synthetics `Launch` 関数を使用してブラウザを起動します。
```
const browser = await synthetics.launch();
```
1. Synthetics `newPage` 関数を使用して新しい Playwright ページを作成します。
```
const page = await synthetics.newPage();
```
これで、スクリプトを Synthetics の Canary として実行できるようになりました。更新されたスクリプトは次のとおりです。
**ES6 形式で更新されたスクリプト**
`.mjs` 拡張子を付けて保存されたスクリプトファイル。
```
import { synthetics } from '@aws/synthetics-playwright';
import { expect } from '@playwright/test';
export const handler = async (event, context) => {
try {
// Launch a browser
const browser = await synthetics.launch();
// Create a new page
const page = await synthetics.newPage(browser);
// Navigate to a website
await page.goto('https://www.example.com', {timeout: 30000});
// Take screenshot
await page.screenshot({ path: '/tmp/example.png' });
// Verify the page title
const title = await page.title();
expect(title).toEqual("Example Domain");
} finally {
// Ensure browser is closed
await synthetics.close();
}
};
```
**CommonJS 形式で更新されたスクリプト**
`.js` 拡張子を付けて保存されたスクリプトファイル。
```
const { synthetics } = require('@aws/synthetics-playwright');
const { expect } = require('@playwright/test');
exports.handler = async (event) => {
try {
const browser = await synthetics.launch();
const page = await synthetics.newPage(browser);
await page.goto('https://www.example.com', {timeout: 30000});
await page.screenshot({ path: '/tmp/example.png' });
const title = await page.title();
expect(title).toEqual("Example Domain");
} finally {
await synthetics.close();
}
};
```
## CloudWatch Synthetics の設定
Synthetics Playwright ランタイムの動作を設定するには、`synthetics.json` という名前のオプション JSON 設定ファイルを指定します。このファイルは、ハンドラーファイルと同じ場所にパッケージ化する必要があります。設定ファイルはオプションですが、設定ファイルを指定しない場合、または設定キーがない場合、CloudWatch はデフォルトを引き受けます。
**設定ファイルのパッケージ化**
サポートされている設定値とそのデフォルト値を次に示します。
```
{
"step": {
"screenshotOnStepStart": false,
"screenshotOnStepSuccess": false,
"screenshotOnStepFailure": false,
"stepSuccessMetric": true,
"stepDurationMetric": true,
"continueOnStepFailure": true,
"stepsReport": true
},
"report": {
"includeRequestHeaders": true,
"includeResponseHeaders": true,
"includeUrlPassword": false,
"includeRequestBody": true,
"includeResponseBody": true,
"restrictedHeaders": ['x-amz-security-token', 'Authorization'], // Value of these headers is redacted from logs and reports
"restrictedUrlParameters": ['Session', 'SigninToken'] // Values of these url parameters are redacted from logs and reports
},
"logging": {
"logRequest": false,
"logResponse": false,
"logResponseBody": false,
"logRequestBody": false,
"logRequestHeaders": false,
"logResponseHeaders": false
},
"httpMetrics": {
"metric_2xx": true,
"metric_4xx": true,
"metric_5xx": true,
"failedRequestsMetric": true,
"aggregatedFailedRequestsMetric": true,
"aggregated2xxMetric": true,
"aggregated4xxMetric": true,
"aggregated5xxMetric": true
},
"canaryMetrics": {
"failedCanaryMetric": true,
"aggregatedFailedCanaryMetric": true
},
"userAgent": "",
"har": true
}
```
**ステップ設定**
+ `screenshotOnStepStart` – ステップの開始前に Synthetics がスクリーンショットをキャプチャするかどうかを決定します。デフォルトは `true` です。
+ `screenshotOnStepSuccess` – ステップが成功した後に Synthetics がスクリーンショットをキャプチャするかどうかを決定します。デフォルトは `true` です。
+ `screenshotOnStepFailure` – ステップが失敗した後に Synthetics がスクリーンショットをキャプチャするかどうかを決定します。デフォルトは `true` です。
+ `continueOnStepFailure` – ステップが失敗した後もスクリプトを続行するかどうかを決定します。デフォルトは `false` です。
+ `stepSuccessMetric` - ステップの ` SuccessPercent` メトリクスが出力されるかどうかを決定します。ステップの `SuccessPercent` メトリクスは、ステップが成功した場合は Canary 実行の `100` となり、ステップが失敗した場合は `0` となります。デフォルトは `true` です。
+ `stepDurationMetric` – ステップの `Duration` メトリクスが出力されるかどうかを決定します。`Duration` メトリクスは、ステップの実行時間としてミリ秒単位で出力されます。デフォルトは `true` です。
**レポート設定**
HAR ファイルや Synthetics ステップレポートなど、CloudWatch Synthetics によって生成されたすべてのレポートが含まれます。機密データの編集フィールド `restrictedHeaders` と `restrictedUrlParameters` は、Synthetics によって生成されたログにも適用されます。
+ `includeRequestHeaders` – レポートにリクエストヘッダーを含めるかどうか。デフォルトは `false` です。
+ `includeResponseHeaders` – レポートにレスポンスヘッダーを含めるかどうか。デフォルトは `false` です。
+ `includeUrlPassword` — URL に表示されるパスワードを含めるかどうか。デフォルトでは、機密データの開示を防ぐために、URL に表示されるパスワードはログとレポートで墨消しされます。デフォルトは `false` です。
+ `includeRequestBody` – レポートにリクエスト本文を含めるかどうか。デフォルトは `false` です。
+ `includeResponseBody` – レポートにレスポンス本文を含めるかどうか。デフォルトは `false` です。
+ `restrictedHeaders` – ヘッダーが含まれている場合に無視するヘッダー値のリスト。これは、リクエストヘッダーとレスポンスヘッダーの両方に適用されます。例えば、`includeRequestHeaders` を true として、`restrictedHeaders` を `['Authorization']` として渡すことで、認証情報を非表示にできます。
+ `restrictedUrlParameters` — 編集する URL パスまたはクエリパラメータのリスト。これは、ログ、レポート、エラーに表示される URL に適用されます。パラメータ名では大文字と小文字が区別されます。アスタリスク (`*`) を値として渡すと、すべての URL パスおよびクエリパラメータ値を墨消しできます。デフォルトは、空白の配列です。
+ `har` – HTTP アーカイブ (HAR) を生成するかどうかを決定します。デフォルトは `true` です。
以下はレポート設定ファイルの例です。
```
"includeRequestHeaders": true,
"includeResponseHeaders": true,
"includeUrlPassword": false,
"includeRequestBody": true,
"includeResponseBody": true,
"restrictedHeaders": ['x-amz-security-token', 'Authorization'], // Value of these headers is redacted from logs and reports
"restrictedUrlParameters": ['Session', 'SigninToken'] // Values of these URL parameters are redacted from logs and reports
```
**ロギング設定**
CloudWatch Synthetics によって生成されたログに適用されます。リクエストログとレスポンスログの詳細度を制御します。
+ `logRequest` - すべてのリクエストを Canary ログに記録するかどうか。UI Canary の場合、ブラウザから送信された各リクエストがログに記録されます。デフォルトは ` false` です。
+ `logResponse` - すべてのレスポンスを Canary ログに記録するかどうか。UI Canary の場合、ブラウザが受信したすべてのレスポンスをログに記録します。デフォルトは ` false` です。
+ `logRequestBody` -リクエスト本文を Canary ログのリクエストとともに記録するかどうか。この設定は、`logRequest` が true である場合にのみ適用されます。デフォルトは `false` です。
+ `logResponseBody` -リクエスト本文を Canary ログのリクエストとともに記録するかどうか。この設定は、`logResponse` が true である場合にのみ適用されます。デフォルトは `false` です。
+ `logRequestHeaders` -リクエストヘッダーを Canary ログのリクエストとともに記録するかどうか。この設定は、` logRequest` が true である場合にのみ適用されます。デフォルトは `false` です。
+ `logResponseHeaders` -レスポンスヘッダーを Canary ログのレスポンスとともに記録するかどうか。この設定は、` logResponse` が true である場合にのみ適用されます。デフォルトは `false` です。
**HTTP メトリクス設定**
この Canary の CloudWatch Synthetics によって出力される、異なる HTTP ステータスコードを持つネットワークリクエストの数に関連するメトリクスの設定。
+ `metric_2xx` – この Canary の `2xx` メトリクス (`CanaryName` ディメンションを含む) を出力するかどうか。デフォルトは ` true` です。
+ `metric_4xx` – この Canary の `4xx` メトリクス (`CanaryName` ディメンションを含む) を出力するかどうか。デフォルトは ` true` です。
+ `metric_5xx` – この Canary の `5xx` メトリクス (`CanaryName` ディメンションを含む) を出力するかどうか。デフォルトは ` true` です。
+ `failedRequestsMetric` – この Canary の ` failedRequests` メトリクス (`CanaryName` ディメンションを含む) を出力するかどうか。デフォルトは `true` です。
+ `aggregatedFailedRequestsMetric` – この Canary の ` failedRequests` メトリクス (`CanaryName` ディメンションを含まない) を出力するかどうか。デフォルトは `true` です。
+ `aggregated2xxMetric` – この Canary の `2xx` メトリクス (`CanaryName` ディメンションを含まない) を出力するかどうか。デフォルトは `true` です。
+ `aggregated4xxMetric` – この Canary の `4xx` メトリクス (`CanaryName` ディメンションを含まない) を出力するかどうか。デフォルトは `true` です。
+ `aggregated5xxMetric` – この Canary の `5xx` メトリクス (`CanaryName` ディメンションを含まない) を出力するかどうか。デフォルトは `true` です。
**Canary メトリクス設定**
CloudWatch Synthetics によって出力される他のメトリクスの設定。
+ `failedCanaryMetric` – この Canary の `Failed` メトリクス (`CanaryName` ディメンションを含む) を出力するかどうか。デフォルトは ` true` です。
+ `aggregatedFailedCanaryMetric` – この Canary の ` Failed` メトリクス (`CanaryName` ディメンションを含まない) を出力するかどうか。デフォルトは `true` です。
**その他の設定**
+ `userAgent` – ユーザーエージェントに追加する文字列。ユーザーエージェントは、リクエストヘッダーに含まれる文字列であり、ヘッドレスブラウザの使用時にアクセスしたウェブサイトに対してブラウザを識別します。CloudWatch Synthetics は `CloudWatchSynthetics/canary-arn to the user agent` を自動的に追加します。指定された設定は、生成されたユーザーエージェントに追加されます。追加するデフォルトのユーザーエージェント値は空の文字列 (`""`) です。
### CloudWatch Synthetics 環境変数
環境変数を使用してログ記録レベルと形式を設定します。
**ログ形式**
CloudWatch Synthetics Playwright ランタイムは、Canary の実行ごとに CloudWatch ログを作成します。ログは、クエリしやすいように JSON 形式で書き込まれます。必要に応じて、ログ形式を `TEXT` に変更できます。
+ `Environment variable name` – CW\$1SYNTHETICS\$1LOG\$1FORMAT
+ `Supported values` – JSON、テキスト
+ `Default` – JSON
**ログレベル**
`Debug` モードを有効にすると詳細度は高くなりますが、トラブルシューティングに役立ちます。
+ `Environment variable name` – CW\$1SYNTHETICS\$1LOG\$1LEVEL
+ `Supported values` – TRACE、DEBUG、INFO、WARN、ERROR、FATAL
+ `Default` – INFO
# Puppeteer ランタイムを使用した Node.js Canary スクリプトの記述
**Topics**
+ [CloudWatch Synthetics Canary を最初から作成する](#CloudWatch_Synthetics_Canaries_write_from_scratch)
+ [Node.js Canary ファイルのパッケージング](#CloudWatch_Synthetics_Canaries_package)
+ [既存の Puppeteer スクリプトを変更して Synthetics の Canary として使用する](#CloudWatch_Synthetics_Canaries_modify_puppeteer_script)
+ [環境変数](#CloudWatch_Synthetics_Environment_Variables)
+ [Canary と他の AWS のサービスとの統合](#CloudWatch_Synthetics_Canaries_AWS_integrate)
+ [Canary に静的 IP アドレスの使用を強制する](#CloudWatch_Synthetics_Canaries_staticIP)
## CloudWatch Synthetics Canary を最初から作成する
次の例は、Synthetics の最小の Canary スクリプトを示しています。このスクリプトは、合格して正常な実行となり、文字列を返します。不合格となる Canary の例を確認するには、`let fail = false;` を `let fail = true;` に変更します。
Canary スクリプトのエントリポイント関数を定義する必要があります。Canary の `ArtifactS3Location` として指定した先の Amazon S3 にファイルがアップロードされる方法を確認するには、これらのファイルを `/tmp` フォルダに作成します。Canary アーティファクトは書き込み可能な唯一のディレクトリであるため、すべて `/tmp` に保存する必要があります。スクリプトによって作成されたスクリーンショットやその他のファイルについては、スクリーンショットパスが `/tmp` に設定されていることを確認してください。Synthetics は、` /tmp` のファイルを S3 バケットに自動的にアップロードします。
```
/tmp/
```
スクリプトを実行すると、合格/不合格のステータスと所要時間のメトリクスが CloudWatch に発行され、`/tmp` の下のファイルが S3 にアップロードされます。
```
const basicCustomEntryPoint = async function () {
// Insert your code here
// Perform multi-step pass/fail check
// Log decisions made and results to /tmp
// Be sure to wait for all your code paths to complete
// before returning control back to Synthetics.
// In that way, your canary will not finish and report success
// before your code has finished executing
// Throw to fail, return to succeed
let fail = false;
if (fail) {
throw "Failed basicCanary check.";
}
return "Successfully completed basicCanary checks.";
};
exports.handler = async () => {
return await basicCustomEntryPoint();
};
```
次に、AWS SDK を使用して、Synthetics のログ記録を使用して呼び出しを行うようにスクリプトが拡張されます。デモのために、このスクリプトは Amazon DynamoDB クライアントを作成し、DynamoDB listTables API を呼び出します。リクエストに対するレスポンスを記録し、リクエストが成功したかどうかに応じて合格または不合格を記録します。
```
const log = require('@aws/synthetics-logger');
const AWS = require('aws-sdk');
// Require any dependencies that your script needs
// Bundle additional files and dependencies into a .zip file with folder structure
// nodejs/node_modules/additional files and folders
const basicCustomEntryPoint = async function () {
log.info("Starting DynamoDB:listTables canary.");
let dynamodb = new AWS.DynamoDB();
var params = {};
let request = await dynamodb.listTables(params);
try {
let response = await request.promise();
log.info("listTables response: " + JSON.stringify(response));
} catch (err) {
log.error("listTables error: " + JSON.stringify(err), err.stack);
throw err;
}
return "Successfully completed DynamoDB:listTables canary.";
};
exports.handler = async () => {
return await basicCustomEntryPoint();
};
```
## Node.js Canary ファイルのパッケージング
**syn-nodejs-puppeteer-11.0 以降の場合**
古いパッケージング構造 (syn-nodejs-puppeteer-10.0 以前) は、新しいバージョンでも引き続きサポートされています。
以下のいずれかのオプションを使用してスクリプトを作成します。
+ .js ファイル (CommonJS 構文)
+ .mjs ファイル (ES モジュール構文)
ES モジュールの場合は、以下のいずれかのオプションを使用します。
+ .js ファイル (CommonJS 構文)
+ .mjs ファイル (ES モジュール構文)
パッケージ構造は以下のとおりです。
+ ルートレベルのハンドラーファイル (index.js/index.mjs)
+ オプションの設定ファイル (synthetics.json)
+ node\$1modules の追加依存関係 (必要な場合)
パッケージング構造の例:
```
my_function/
├── index.mjs
├── synthetics.json
├── helper-utils.mjs
└── node_modules/
└── dependencies
```
パッケージ化するには、以下のステップに従います。
1. 依存関係 (存在する場合) をインストールします。
```
npm install
```
1. .zip パッケージを作成します。
```
zip -r my_deployment_package.zip
```
**syn-nodejs-puppeteer-11.0 以下の場合**
Amazon S3 を使用する場合は、以下の構造が必要です。
```
nodejs/
└── node_modules/
└── myCanaryFilename.js
```
**syn-nodejs-puppeteer-3.4\$1 でオプションのサブフォルダサポートを追加するには:**
```
nodejs/
└── node_modules/
└── myFolder/
└── myCanaryFilename.js
```
**注記**
設定のハンドラーパスは、ファイルの場所と一致する必要があります。
**ハンドラー名**
スクリプトのエントリポイント (ハンドラー) のファイル名に一致するように、Canary のスクリプトのエントリポイントを ` myCanaryFilename.functionName` として設定します。`syn-nodejs-puppeteer-3.4` より前のランタイムを使用している場合は、`functionName` は `handler` である必要があります。` syn-nodejs-puppeteer-3.4` 以降を使用している場合、ハンドラーとして任意の関数名を選択できます。`syn-nodejs-puppeteer-3.4` 以降を使用している場合、オプションで Canary を ` nodejs/node_modules/myFolder/my_canary_filename` などの別のフォルダに保存することもできます。別のフォルダに保存する場合は、スクリプトエントリポイントでそのパスを指定します (` myFolder/my_canary_filename.functionName` など)。
## 既存の Puppeteer スクリプトを変更して Synthetics の Canary として使用する
このセクションでは、Puppeteer スクリプトを変更して Synthetics の Canary スクリプトとして実行する方法について説明します。Puppeteer の詳細については、「[Puppeteer API v1.14.0](https://github.com/puppeteer/puppeteer/blob/v1.14.0/docs/api.md)」を参照してください。
まず、次の Puppeteer スクリプトの例から始めます。
```
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('https://example.com');
await page.screenshot({path: 'example.png'});
await browser.close();
})();
```
変更の手順は次のとおりです。
+ `handler` 関数を作成してエクスポートします。このハンドラーは、スクリプトのエントリポイント関数です。` syn-nodejs-puppeteer-3.4` より前のランタイムを使用している場合、ハンドラー関数には `handler` という名前を付ける必要があります。`syn-nodejs-puppeteer-3.4` 以降を使用している場合、関数には任意の名前を付けることができますが、スクリプトで使用されている名前と同じである必要があります。また、`syn-nodejs-puppeteer-3.4` 以降を使用している場合は、スクリプトを任意のフォルダに保存し、そのフォルダをハンドラー名の一部として指定できます。
```
const basicPuppeteerExample = async function () {};
exports.handler = async () => {
return await basicPuppeteerExample();
};
```
+ `Synthetics` 依存関係を使用します。
```
var synthetics = require('@aws/synthetics-puppeteer');
```
+ Puppeteer の `Page` オブジェクトを取得するには、`Synthetics.getPage` 関数を使用します。
```
const page = await synthetics.getPage();
```
Synthetics.getPage 関数から返されるページオブジェクトには、ログ記録用にインストルメント化された **page.on**、`request`、`response`、および ` requestfailed` の各イベントがあります。また、Synthetics は、ページのリクエストおよびレスポンス用の HAR ファイルの生成を設定し、ページの送信リクエストのユーザーエージェントヘッダーに Canary ARN を追加します。
これで、スクリプトを Synthetics の Canary として実行できるようになりました。更新されたスクリプトは次のとおりです。
```
var synthetics = require('@aws/synthetics-puppeteer'); // Synthetics dependency
const basicPuppeteerExample = async function () {
const page = await synthetics.getPage(); // Get instrumented page from Synthetics
await page.goto('https://example.com');
await page.screenshot({path: '/tmp/example.png'}); // Write screenshot to /tmp folder
};
exports.handler = async () => { // Exported handler function
return await basicPuppeteerExample();
};
```
## 環境変数
Canary を作成する際に環境変数を使用できます。これにより、単一の Canary スクリプトを記述し、そのスクリプトを異なる値で使用して、同様のタスクを持つ複数の Canary をすばやく作成できます。
例えば、組織が、ソフトウェア開発のさまざまな段階向けに `prod`、` dev`、`pre-release` などのエンドポイントを有しており、これらの各エンドポイントをテストするために Canary を作成する必要があるとします。ソフトウェアをテストする 1 つの Canary スクリプトを記述し、3 つの Canary をそれぞれ作成するときに、エンドポイント環境変数に異なる値を指定できます。その後、Canary を作成するときに、環境変数に使用するスクリプトと値を指定します。
環境変数の名前には、文字、数字、およびアンダースコアを使用できます。文字で始まり、少なくとも 2 文字である必要があります。環境変数の合計サイズは 4 KB を超えることはできません。Lambda の予約済み環境変数を環境変数の名前として指定することはできません。予約済み環境変数の詳細については、「[ランタイム環境変数](https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars.html#configuration-envvars-runtime)」をご参照ください。
**重要**
環境変数のキーと値は、保管時に AWS が所有する AWS KMS キーを使用して暗号化されます。ただし、クライアント側で環境変数が暗号化されます。機密情報は保存しないでください。
次のスクリプト例では、2 つの環境変数を使用しています。このスクリプトは、ウェブページが利用可能かどうかをチェックする Canary 用です。環境変数を使用して、チェックする URL と、使用する CloudWatch Synthetics ログレベルの両方をパラメータ化します。
次の関数は、`LogLevel` を ` LOG_LEVEL` 環境変数の値に設定します。
```
synthetics.setLogLevel(process.env.LOG_LEVEL);
```
この関数は、`URL` を `URL` 環境変数の値に設定します。
```
const URL = process.env.URL;
```
これは完全なスクリプトです。このスクリプトを使用して Canary を作成するときは、`LOG_LEVEL` および `URL` 環境変数の値を指定します。
```
var synthetics = require('@aws/synthetics-puppeteer');
const log = require('@aws/synthetics-logger');
const pageLoadEnvironmentVariable = async function () {
// Setting the log level (0-3)
synthetics.setLogLevel(process.env.LOG_LEVEL);
// INSERT URL here
const URL = process.env.URL;
let page = await synthetics.getPage();
//You can customize the wait condition here. For instance,
//using 'networkidle2' may be less restrictive.
const response = await page.goto(URL, {waitUntil: 'domcontentloaded', timeout: 30000});
if (!response) {
throw "Failed to load page!";
}
//Wait for page to render.
//Increase or decrease wait time based on endpoint being monitored.
await page.waitFor(15000);
await synthetics.takeScreenshot('loaded', 'loaded');
let pageTitle = await page.title();
log.info('Page title: ' + pageTitle);
log.debug('Environment variable:' + process.env.URL);
//If the response status code is not a 2xx success code
if (response.status() < 200 || response.status() > 299) {
throw "Failed to load page!";
}
};
exports.handler = async () => {
return await pageLoadEnvironmentVariable();
};
```
### 環境変数をスクリプトに渡す
コンソールで Canary を作成するときに環境変数をスクリプトに渡すには、コンソールの [**Environment variables**] (環境変数) セクションで環境変数のキーと値を指定します。詳細については、「[Canary を作成する](CloudWatch_Synthetics_Canaries_Create.md)」を参照してください。
API または AWS CLI を介して環境変数を渡すには、`RunConfig` セクションの ` EnvironmentVariables` パラメータを使用します。以下は、キー `Environment` とキー `Region` を持つ 2 つの環境変数を使用する Canary を作成する AWS CLI コマンドの例です。
```
aws synthetics create-canary --cli-input-json '{
"Name":"nameofCanary",
"ExecutionRoleArn":"roleArn",
"ArtifactS3Location":"s3://amzn-s3-demo-bucket-123456789012-us-west-2",
"Schedule":{
"Expression":"rate(0 minute)",
"DurationInSeconds":604800
},
"Code":{
"S3Bucket": "canarycreation",
"S3Key": "cwsyn-mycanaryheartbeat-12345678-d1bd-1234-abcd-123456789012-12345678-6a1f-47c3-b291-123456789012.zip",
"Handler":"pageLoadBlueprint.handler"
},
"RunConfig": {
"TimeoutInSeconds":60,
"EnvironmentVariables": {
"Environment":"Production",
"Region": "us-west-1"
}
},
"SuccessRetentionPeriodInDays":13,
"FailureRetentionPeriodInDays":13,
"RuntimeVersion":"syn-nodejs-2.0"
}'
```
## Canary と他の AWS のサービスとの統合
すべての Canary では AWS SDK ライブラリを使用できます。このライブラリを Canary の作成時に使用すると、Canary を他の AWS のサービスと統合できます。
これを行うには、Canary に次のコードを追加する必要があります。これらの例では、Canary に統合されているサービスとして AWS Secrets Manager が使用されます。
+ AWS SDK をインポートします。
```
const AWS = require('aws-sdk');
```
+ 統合する AWS のサービスのクライアントを作成します。
```
const secretsManager = new AWS.SecretsManager();
```
+ このクライアントを使用して、サービスへの API コールを行います。
```
var params = {
SecretId: secretName
};
return await secretsManager.getSecretValue(params).promise();
```
次の Canary スクリプトのコードスニペットは、Secrets Manager との統合例をより詳細に示しています。
```
var synthetics = require('@aws/synthetics-puppeteer');
const log = require('@aws/synthetics-logger');
const AWS = require('aws-sdk');
const secretsManager = new AWS.SecretsManager();
const getSecrets = async (secretName) => {
var params = {
SecretId: secretName
};
return await secretsManager.getSecretValue(params).promise();
}
const secretsExample = async function () {
let URL = "";
let page = await synthetics.getPage();
log.info(`Navigating to URL: ${URL}`);
const response = await page.goto(URL, {waitUntil: 'domcontentloaded', timeout: 30000});
// Fetch secrets
let secrets = await getSecrets("secretname")
/**
* Use secrets to login.
*
* Assuming secrets are stored in a JSON format like:
* {
* "username": "",
* "password": ""
* }
**/
let secretsObj = JSON.parse(secrets.SecretString);
await synthetics.executeStep('login', async function () {
await page.type(">USERNAME-INPUT-SELECTOR<", secretsObj.username);
await page.type(">PASSWORD-INPUT-SELECTOR<", secretsObj.password);
await Promise.all([
page.waitForNavigation({ timeout: 30000 }),
await page.click(">SUBMIT-BUTTON-SELECTOR<")
]);
});
// Verify login was successful
await synthetics.executeStep('verify', async function () {
await page.waitForXPath(">SELECTOR<", { timeout: 30000 });
});
};
exports.handler = async () => {
return await secretsExample();
};
```
## Canary に静的 IP アドレスの使用を強制する
静的 IP アドレスを使用するように Canary を設定できます。
**Canary に静的 IP アドレスの使用を強制するには**
1. 新しい VPC を作成します。詳細については、「[VPC での DNS の使用](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-dns.html)」を参照してください。
1. 新しいインターネットゲートウェイを作成します。詳細については、「[インターネットゲートウェイを VPC に追加する](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Internet_Gateway.html#working-with-igw)」を参照してください。
1. 新しい VPC 内にパブリックサブネットを作成します。
1. 新しいルートテーブルを VPC に追加します。
1. `0.0.0.0/0` からインターネットゲートウェイに向かうルートを、新しいルートテーブルに追加します。
1. 新しいルートテーブルをパブリックサブネットに関連付けます。
1. Elastic IP アドレスを作成します。詳細については、「[Elastic IP アドレス](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/elastic-ip-addresses-eip.html)」を参照してください。
1. 新しい NAT ゲートウェイを作成し、パブリックサブネットと Elastic IP アドレスに割り当てます。
1. VPC の内部にプライベートサブネットを作成します。
1. `0.0.0.0/0` から NAT ゲートウェイへのルートを VPC デフォルトルートテーブルに追加する
1. Canary を作成します。
# Python Canary スクリプトの記述
このスクリプトは、合格して正常な実行となり、文字列を返します。失敗した Canary がどのように見えるかを確認するには、fail = False を fail = True に変更します
```
def basic_custom_script():
# Insert your code here
# Perform multi-step pass/fail check
# Log decisions made and results to /tmp
# Be sure to wait for all your code paths to complete
# before returning control back to Synthetics.
# In that way, your canary will not finish and report success
# before your code has finished executing
fail = False
if fail:
raise Exception("Failed basicCanary check.")
return "Successfully completed basicCanary checks."
def handler(event, context):
return basic_custom_script()
```
## Python Canary ファイルのパッケージング
複数の .py ファイルがある場合、またはスクリプトに依存関係がある場合は、それらすべてを単一の ZIP ファイルにバンドルできます。`syn-python-selenium-1.1` ランタイムを使用する場合、ZIP ファイルには、`python/my_canary_filename.py` などの `python` フォルダ内にメインの Canary .py ファイルが含まれている必要があります。` syn-python-selenium-1.1` 以降を使用する場合は、オプションで、`python/myFolder/my_canary_filename.py` などの別のフォルダを使用できます。
この ZIP ファイルには、必要なすべてのフォルダとファイルが含まれている必要がありますが、他のファイルは `python` フォルダ内にある必要はありません。
スクリプトのエントリポイントのファイル名および関数名に一致するように、Canary のスクリプトのエントリポイントを ` my_canary_filename.functionName` として設定します。`syn-python-selenium-1.0` ランタイムを使用している場合は、`functionName` は `handler` である必要があります。` syn-python-selenium-1.1` 以降を使用している場合、このハンドラー名の制限は適用されません。また、オプションで Canary を ` python/myFolder/my_canary_filename.py` などの別のフォルダに保存することもできます。別のフォルダに保存する場合は、スクリプトエントリポイントでそのパスを指定します (` myFolder/my_canary_filename.functionName` など)。
## Synthetics Canary を使用するようにするための既存の Selenium の変更
Canary として使用するために、Python と Selenium の既存のスクリプトをすばやく変更できます。Selenium の詳細については、[www.selenium.dev/](https://www.selenium.dev/) をご参照ください。
この例では、次の Selenium スクリプトから始めます。
```
from selenium import webdriver
def basic_selenium_script():
browser = webdriver.Chrome()
browser.get('https://example.com')
browser.save_screenshot('loaded.png')
basic_selenium_script()
```
変更の手順は次のとおりです。
**Selenium スクリプトを Canary として使用するように変換するには**
1. ` aws_synthetics` モジュールから Selenium を使用するように `import` ステートメントを変更します。
```
from aws_synthetics.selenium import synthetics_webdriver as webdriver
```
`aws_synthetics` の Selenium モジュールは、Canary がメトリクスとログを出力し、HAR ファイルを生成し、他の CloudWatch Synthetics 機能で動作することを保証します。
1. ハンドラ関数を作成し、Selenium メソッドを呼び出します。このハンドラーは、スクリプトのエントリポイント関数です。
`syn-python-selenium-1.0` を使用している場合、ハンドラー関数には `handler` という名前を付ける必要があります。`syn-python-selenium-1.1` 以降を使用している場合、関数には任意の名前を付けることができますが、スクリプトで使用されている名前と同じである必要があります。また、`syn-python-selenium-1.1` 以降を使用している場合は、スクリプトを任意のフォルダに保存し、そのフォルダをハンドラー名の一部として指定できます。
```
def handler(event, context):
basic_selenium_script()
```
これで、スクリプトが CloudWatch Synthetics Canary に更新されました。更新されたスクリプトは次のとおりです。
`webdriver` は [SyntheticsWebDriver](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries_Library_Python.html#CloudWatch_Synthetics_Library_Python_SyntheticsWebDriver) クラスのインスタンスであり、`webdriver.Chrome()` によって返されるブラウザは [SyntheticsBrowser](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries_Library_Python.html#CloudWatch_Synthetics_Library_Python_SyntheticsBrowser) のインスタンスです。
```
from aws_synthetics.selenium import synthetics_webdriver as webdriver
def basic_selenium_script():
browser = webdriver.Chrome()
browser.get('https://example.com')
browser.save_screenshot('loaded.png')
def handler(event, context):
basic_selenium_script()
```
## 既存の Puppeteer Synthetics スクリプトを変更して非標準の証明書を認証する
Synthetics Canaries の重要なユースケースの 1 つは、独自のエンドポイントをモニタリングすることです。外部トラフィックに対応していないエンドポイントをモニタリングする場合、信頼できるサードパーティーの認証局によって署名された適切な証明書が存在しない可能性があります。
このシナリオで考えられる解決策は、次の 2 つです。
+ クライアント証明書を認証するには、「[How to validate authentication using Amazon CloudWatch Synthetics – Part 2](https://aws.amazon.com/blogs/mt/how-to-validate-authentication-using-amazon-cloudwatch-synthetics-part-2/)」を参照してください。
+ 自己署名証明書を認証するには、「[How to validate authentication with self-signed certificates in Amazon CloudWatch Synthetics](https://aws.amazon.com/blogs/mt/how-to-validate-authentication-with-self-signed-certificates-in-amazon-cloudwatch-synthetics/)」を参照してください。
CloudWatch Synthetics Canary を使用する場合は、これら 2 つのオプションに限定されません。Canary コードを拡張することで、これらの機能を拡張し、ビジネスロジックを追加できます。
**注記**
Python ランタイムで実行される Synthetics Canary は、もともと ` --ignore-certificate-errors` フラグが有効になっているため、これらの Canary が非標準の証明書構成のサイトに到達しても問題ないはずです。
# Node.js マルチチェックブループリントの JSON 設定の記述
Node.js マルチチェックブループリントを使用すると、1 回の Canary 実行内で複数の検証チェックを実行する Canary を作成できます。このブループリントは、複数のエンドポイントをテストしたり、アプリケーションのさまざまな側面を検証したり、関連する一連のチェックを順番に実行したりする場合に便利です。
**Topics**
+ [ルート設定構造](#root-configuration-structure)
+ [[Global settings] (グローバル設定)](#global-settings)
+ [変数とデータ管理](#variables-data-management)
+ [ステップの定義](#step-definitions)
+ [チェックタイプ](#check-types)
+ [認証方法](#authentication-methods)
+ [アサーションと検証](#assertions-validation)
+ [データ抽出](#data-extraction)
## ルート設定構造
ルート設定は、高度な API ブループリント Canary の全体的な構造を定義します。
**スキーマプロパティ**
| プロパティ | タイプ | 必須 | 説明 |
| --- | --- | --- | --- |
| globalSettings | オブジェクト | いいえ | すべてのステップに適用されるデフォルト設定 |
| variables | オブジェクト | いいえ | ステップ間で再利用可能な値 (最大 10) |
| steps | オブジェクト | あり | モニタリングステップのコレクション (1～10 ステップ) |
**例**
```
{
"globalSettings": {
"stepTimeout": 30000,
"userAgent": "CloudWatch-Synthetics-Advanced/1.0"
},
"variables": {
"baseUrl": "https://api.example.com",
"apiVersion": "v1"
},
"steps": {
"1": {
"stepName": "healthCheck",
"checkerType": "HTTP",
"url": "${baseUrl}/health",
"httpMethod": "GET"
}
}
}
```
**検証ルール**
+ 少なくとも 1 つのステップを含める必要があります
+ 最大 10 ステップまで可能
+ `globalSettings`、` variables`、`steps` 以外の追加プロパティは不可
## [Global settings] (グローバル設定)
グローバル設定は、ステップレベルで上書きされない限り、すべてのステップに適用されるデフォルト設定を指定します。
**プロパティ**
**グローバル設定のプロパティ**
| プロパティ | タイプ | デフォルト | Range | 説明 |
| --- | --- | --- | --- | --- |
| stepTimeout | integer | 30000 | 5000～300000 | すべてのステップのデフォルトのタイムアウト (ミリ秒) |
**例**
```
{
"globalSettings": {
"stepTimeout": 60000,
}
}
```
## 変数とデータ管理
変数を使用すると、`${variableName}` 構文を使用して設定全体で参照できる再利用可能な値を定義できます。
**変数プロパティ**
| プロパティ | 型 | 説明 |
| --- | --- | --- |
| 変数名 | string | パターン ^[a-zA-Z][a-zA-Z0-9\$1]\$1\$1 と一致する必要があります |
| 変数値 | string | 任意の文字列値 |
**制限事項**
+ 設定ごとに最大 10 個の変数
+ 変数名は英字で始まる必要があります
+ 名前には、英字、数字、下線のみを含めることができます
+ スキーマで指定されていない最大長
**例**
```
{
"variables": {
"baseUrl": "https://api.example.com",
"apiKey": "${AWS_SECRET:my-api-key}",
"timeout": "30000",
"userEmail": "test@example.com"
}
}
```
**設定の使用方法**
```
{
"steps": {
"1": {
"url": "${baseUrl}/users",
"timeout": "${timeout}",
"headers": {
"Authorization": "Bearer ${apiKey}"
}
}
}
}
```
## ステップの定義
ステップは、個々のモニタリングオペレーションを定義します。各ステップには 1～10 の番号が付けられ、特定のタイプのチェックが含まれます。
*一般的なステップのプロパティ*
| プロパティ | タイプ | 必須 | 説明 |
| --- | --- | --- | --- |
| stepName | 文字列 | あり | ステップの一意の識別子 |
| checkerType | string | あり | チェックのタイプ: HTTP、DNS、SSL、 TCP |
| extractors | array | いいえ | データ抽出設定 |
*ステップ名の検証*
+ パターン - ^[a-zA-Z][a-zA-Z0-9\$1-]\$1\$1
+ 最大文字数 - 64 文字
+ 英字で始まっている必要があります
*ステップの番号付け*
+ ステップには、文字列キーとして「1」、「2」、...、「10」という番号が付けられます。
+ パターン: ^([1-9]\$110)\$1
+ 最低 1 ステップが必要
+ 最大 10 ステップまで可能
*例*
```
{
"steps": {
"1": {
"stepName": "loginAPI",
"checkerType": "HTTP",
"url": "https://api.example.com/login",
"httpMethod": "POST"
},
"2": {
"stepName": "dnsCheck",
"checkerType": "DNS",
"domain": "example.com"
}
}
}
```
## チェックタイプ
### HTTP チェック
包括的なリクエストとレスポンスの検証を使用して、ウェブエンドポイントと API をモニタリングします。
**必要なプロパティ**
| プロパティ | 型 | 説明 |
| --- | --- | --- |
| url | string | ターゲット URL (有効な URI 形式である必要があります) |
| httpMethod | string | HTTP method: GET、POST、PUT、 PATCH、DELETE、HEAD、OPTIONS |
**オプションのプロパティ**
| プロパティ | タイプ | デフォルト | Range | 説明 |
| --- | --- | --- | --- | --- |
| timeout | integer | 30000 | 5000～300000 | リクエストタイムアウト (ミリ秒) |
| waitTime | integer | 0 | 0-60 | リクエスト前の遅延 (秒) |
| headers | オブジェクト | - | - | カスタム HTTP ヘッダー |
| body | string | - | - | POST/PUT オペレーションのリクエスト本文 |
| authentication | オブジェクト | - | - | 認証の設定 |
| assertions | array | - | - | レスポンス検証ルール |
**例**
```
{
"stepName": "createUser",
"checkerType": "HTTP",
"url": "https://api.example.com/users",
"httpMethod": "POST",
"timeout": 15000,
"headers": {
"Content-Type": "application/json",
"X-API-Version": "v1"
},
"body": "{\"name\":\"John Doe\",\"email\":\"john@example.com\"}",
"authentication": {
"type": "API_KEY",
"apiKey": "${AWS_SECRET:api-credentials}",
"headerName": "X-API-Key"
},
"assertions": [
{
"type": "STATUS_CODE",
"operator": "EQUALS",
"value": 201
}
]
}
```
### DNS チェック
DNS 解決を検証し、情報を記録します。
**必要なプロパティ**
| プロパティ | 型 | 説明 |
| --- | --- | --- |
| domain | string | クエリするドメイン名 (ホスト名形式) |
**オプションのプロパティ**
| プロパティ | タイプ | デフォルト | 説明 |
| --- | --- | --- | --- |
| recordType | string | 「A」 | DNS レコードタイプ: A、CNAME、MX、 TXT、NS |
| nameserver | string | - | クエリする特定の DNS サーバー |
| timeout | integer | 30000 | クエリタイムアウト (5000～300000 ms) |
| port | integer | 53 | DNS サーバーポート (1～65535) |
| protocol | string | 「UDP」 | プロトコル: UDP または TCP |
| assertions | array | - | DNS レスポンス検証ルール |
**例**
```
{
"stepName": "dnsResolution",
"checkerType": "DNS",
"domain": "example.com",
"recordType": "A",
"nameserver": "8.8.8.8",
"timeout": 10000,
"assertions": [
{
"type": "RECORD_VALUE",
"operator": "CONTAINS",
"value": "192.168"
}
]
}
```
### SSL チェック
SSL 証明書のヘルスと設定をモニタリングします。
**必要なプロパティ**
| プロパティ | 型 | 説明 |
| --- | --- | --- |
| hostname | string | ターゲットホスト名 (ホスト名形式) |
**オプションのプロパティ**
| プロパティ | タイプ | デフォルト | 説明 |
| --- | --- | --- | --- |
| port | integer | 443 | SSL ポート (1～65535) |
| timeout | integer | 30000 | 接続タイムアウト (5000～300000 ms) |
| sni | boolean | TRUE | サーバー名の表示 |
| verifyHostname | boolean | TRUE | ホスト名の検証 |
| allowSelfSigned | ブール値 | FALSE | 自己署名証明書の受け入れ |
| assertions | array | - | 証明書検証ルール |
**例**
```
{
"stepName": "sslCertCheck",
"checkerType": "SSL",
"hostname": "secure.example.com",
"port": 443,
"sni": true,
"verifyHostname": true,
"assertions": [
{
"type": "CERTIFICATE_EXPIRY",
"operator": "GREATER_THAN",
"value": 30,
"unit": "DAYS"
}
]
}
```
### TCP チェック
TCP ポートの接続とレスポンス検証をテストします。
**必要なプロパティ**
| プロパティ | 型 | 説明 |
| --- | --- | --- |
| hostname | string | ターゲットホスト名 (ホスト名形式) |
| port | integer | ターゲットポート (1～65535) |
**オプションのプロパティ**
| プロパティ | タイプ | デフォルト | 説明 |
| --- | --- | --- | --- |
| timeout | integer | 30000 | 全体的なタイムアウト (5000～300000 ms) |
| connectionTimeout | integer | 3000 | 接続タイムアウト (5000～300000 ms) |
| readTimeout | integer | 2000 | データ読み取りタイムアウト (5000～300000 ms) |
| sendData | string | - | 接続後に送信するデータ |
| expectedResponse | string | - | 予想されるレスポンスデータ |
| encoding | string | 「UTF-8」 | データエンコーディング: UTF-8、ASCII、HEX |
| assertions | array | - | 接続とレスポンスの検証 |
**例**
```
{
"stepName": "databaseConnection",
"checkerType": "TCP",
"hostname": "db.example.com",
"port": 3306,
"connectionTimeout": 5000,
"sendData": "SELECT 1",
"expectedResponse": "1",
"assertions": [
{
"type": "CONNECTION_SUCCESSFUL",
"value": true
}
]
}
```
## 認証方法
**認証なし**
```
{
"type": "NONE"
}
```
**基本認証**
| プロパティ | タイプ | 必須 | 説明 |
| --- | --- | --- | --- |
| type | 文字列 | あり | "BASIC" を指定してください |
| username | string | あり | 認証用のユーザー名 |
| password | string | あり | 認証用のパスワード |
**例**
```
{
"type": "BASIC",
"username": "admin",
"password": "${AWS_SECRET:basic-auth:password}"
}
```
**API キー認証**
| プロパティ | タイプ | 必須 | デフォルト | 説明 |
| --- | --- | --- | --- | --- |
| type | 文字列 | あり | - | "API\$1KEY" を指定してください |
| apiKey | string | あり | - | API キー値 |
| headerName | string | いいえ | 「X-API-Key」 | API キーのヘッダー名 |
**例**
```
{
"type": "API_KEY",
"apiKey": "${AWS_SECRET:api-credentials}",
"headerName": "Authorization"
}
```
**OAuth クライアントの認証情報**
| プロパティ | タイプ | 必須 | デフォルト | 説明 |
| --- | --- | --- | --- | --- |
| type | 文字列 | あり | - | "OAUTH\$1CLIENT\$1CREDENTIALS" を指定してください |
| tokenUrl | string | あり | - | OAuth トークンエンドポイント URL |
| clientId | string | あり | - | OAuth クライアント ID |
| clientSecret | string | あり | - | OAuth クライアントシークレット |
| scope | string | いいえ | - | OAuth スコープ |
| audience | string | いいえ | - | OAuth 対象者 |
| resource | string | いいえ | - | OAuth リソース |
| tokenApiAuth | array | いいえ | - | トークン API 認証メソッド: BASIC\$1AUTH\$1HEADER、REQUEST\$1BODY |
| tokenCacheTtl | integer | いいえ | 3600 | トークンキャッシュ TTL (60 秒以上) |
**例**
```
{
"type": "OAUTH_CLIENT_CREDENTIALS",
"tokenUrl": "https://auth.example.com/oauth/token",
"clientId": "${AWS_SECRET:oauth-creds:client_id}",
"clientSecret": "${AWS_SECRET:oauth-creds:client_secret}",
"scope": "read write",
"tokenCacheTtl": 7200
}
```
**AWS Signature (バージョン 4)**
| プロパティ | タイプ | 必須 | 説明 |
| --- | --- | --- | --- |
| type | 文字列 | あり | "SIGV4" を指定してください |
| service | string | あり | AWS サービスの名前 (「execute-api」など) |
| region | string | あり | AWS リージョン |
| roleArn | string | あり | 署名用の IAM ロール ARN |
**例**
```
{
"type": "SIGV4",
"service": "execute-api",
"region": "us-east-1",
"roleArn": "arn:aws:iam::123456789012:role/SyntheticsRole"
}
```
## アサーションと検証
### HTTP アサーション
**ステータスコードアサーション**
| プロパティ | タイプ | 必須 | 説明 |
| --- | --- | --- | --- |
| type | 文字列 | あり | "STATUS\$1CODE" を指定してください |
| operator | string | あり | EQUALS, NOT\$1EQUALS, GREATER\$1THAN, LESS\$1THAN, IN\$1RANGE |
| value | 整数 | 条件付き | HTTP ステータスコード (100～599) |
| rangeMin | 整数 | 条件付き | 最小範囲値 (IN\$1RANGE の場合) |
| rangeMax | 整数 | 条件付き | 最大範囲値 (IN\$1RANGE の場合) |
```
{
"type": "STATUS_CODE",
"operator": "EQUALS",
"value": 200
}
```
**応答時間のアサーション**
| プロパティ | タイプ | 必須 | デフォルト | 説明 |
| --- | --- | --- | --- | --- |
| type | 文字列 | あり | - | "RESPONSE\$1TIME" を指定してください |
| operator | string | あり | - | LESS\$1THAN, GREATER\$1THAN, EQUALS |
| value | 数値 | あり | - | 時間値 (最小 0) |
| unit | string | いいえ | 「MILLISECONDS」 | "MILLISECONDS" を指定してください |
```
{
"type": "RESPONSE_TIME",
"operator": "LESS_THAN",
"value": 500,
"unit": "MILLISECONDS"
}
```
**ヘッダーアサーション**
| プロパティ | タイプ | 必須 | 説明 |
| --- | --- | --- | --- |
| type | 文字列 | あり | "HEADER" を指定してください |
| headerName | string | あり | 検証するヘッダーの名前 |
| operator | string | あり | EQUALS, NOT\$1EQUALS, CONTAINS, NOT\$1CONTAINS, REGEX\$1MATCH, EXIST |
| value | 文字列/ブール型 | 条件付き | 予想される値 (EXIST 演算子のブール値) |
```
{
"type": "HEADER",
"headerName": "Content-Type",
"operator": "CONTAINS",
"value": "application/json"
}
```
**本文アサーション**
| プロパティ | タイプ | 必須 | デフォルト | 説明 |
| --- | --- | --- | --- | --- |
| type | 文字列 | あり | - | "BODY" を指定してください |
| target | string | いいえ | 「JSON」 | JSON、または TEXT |
| path | string | 条件付き | - | JSONPath (JSON ターゲットに必須) |
| operator | string | あり | - | CONTAINS, NOT\$1CONTAINS, EQUALS, NOT\$1EQUALS, EXISTS |
| value | 文字列/ブール型 | あり | - | 予想される値 (EXISTS 演算子のブール値) |
```
{
"type": "BODY",
"target": "JSON",
"path": "$.users[0].name",
"operator": "EQUALS",
"value": "John Doe"
}
```
### DNS アサーション
**レコード値のアサーション**
| プロパティ | タイプ | 必須 | Range | 説明 |
| --- | --- | --- | --- | --- |
| type | 文字列 | あり | - | "RECORD\$1VALUE" を指定してください |
| operator | string | あり | - | EQUALS, NOT\$1EQUALS, CONTAINS, NOT\$1CONTAINS, REGEX\$1MATCH |
| value | string | あり | - | 予想されるレコード値 |
**レコード数のアサーション**
| プロパティ | タイプ | 必須 | Range | 説明 |
| --- | --- | --- | --- | --- |
| type | 文字列 | あり | - | "RECORD\$1COUNT" を指定してください |
| operator | string | あり | - | EQUALS, GREATER\$1THAN, LESS\$1THAN |
| value | integer | あり | ≥ 0 | 予想される個数 (最小 0) |
**認可アサーション**
| プロパティ | タイプ | 必須 | Range | 説明 |
| --- | --- | --- | --- | --- |
| type | 文字列 | あり | - | "AUTHORITATIVE" を指定してください |
| value | boolean | あり | - | 想定される認可ステータス |
**TTL アサーション**
| プロパティ | タイプ | 必須 | Range | 説明 |
| --- | --- | --- | --- | --- |
| type | 文字列 | あり | - | "TTL" を指定してください |
| operator | string | あり | - | EQUALS, GREATER\$1THAN, LESS\$1THAN |
| value | integer | あり | ≥ 0 | 予想される TTL (最小 0) |
### SSL アサーション
**証明書の有効期限のアサーション**
| プロパティ | タイプ | 必須 | デフォルト | 説明 |
| --- | --- | --- | --- | --- |
| type | 文字列 | あり | - | "CERTIFICATE\$1EXPIRY" を指定してください |
| operator | string | あり | - | GREATER\$1THAN, LESS\$1THAN |
| value | integer | あり | - | 時間値 (最小 0) |
| unit | string | いいえ | 「DAYS」 | DAYS, HOURS |
**証明書のサブジェクトのアサーション**
| プロパティ | タイプ | 必須 | デフォルト | 説明 |
| --- | --- | --- | --- | --- |
| type | 文字列 | あり | - | "CERTIFICATE\$1SUBJECT" を指定してください |
| field | string | あり | - | サブジェクトフィールド: CN、O、OU、C、ST、L |
| operator | string | あり | - | CONTAINS, EQUALS, REGEX\$1MATCH |
| value | string | あり | - | 予想されるフィールド値 |
**証明書発行者のアサーション**
| プロパティ | タイプ | 必須 | デフォルト | 説明 |
| --- | --- | --- | --- | --- |
| type | 文字列 | あり | - | "CERTIFICATE\$1ISSUER" を指定してください |
| field | string | あり | - | 発行者フィールド: CN、O |
| operator | string | あり | - | CONTAINS, EQUALS |
| value | string | あり | - | 予想されるフィールド値 |
### TCP アサーション
**接続成功アサーション**
| プロパティ | タイプ | 必須 | デフォルト | 説明 |
| --- | --- | --- | --- | --- |
| type | 文字列 | あり | - | "CONNECTION\$1SUCCESSFUL" を指定してください |
| value | boolean | あり | - | 予想される接続ステータス |
**レスポンスデータのアサーション**
| プロパティ | タイプ | 必須 | デフォルト | 説明 |
| --- | --- | --- | --- | --- |
| type | 文字列 | あり | - | "RESPONSE\$1DATA" を指定してください |
| operator | string | あり | - | CONTAINS, EQUALS, NOT\$1CONTAINS, REGEX\$1MATCH, STARTS\$1WITH, ENDS\$1WITH |
| value | string | あり | - | 予想されるレスポンスデータ |
| encoding | string | いいえ | 「UTF-8」 | UTF-8, ASCII, HEX |
## データ抽出
エクストラクターを使用すると、後続のステップでの使用やレポートのために、レスポンスからデータをキャプチャできます。
**抽出プロパティ**
| プロパティ | タイプ | 必須 | デフォルト | 説明 |
| --- | --- | --- | --- | --- |
| name | 文字列 | あり | - | 抽出されたデータの変数名 |
| type | string | あり | - | 抽出タイプ: BODY |
| path | string | いいえ | - | 本文抽出用の JSONPath |
| regex | string | いいえ | - | 正規表現パターン |
| regexGroup | integer | いいえ | 0 | 正規表現キャプチャグループ (最小 0) |
**抽出名の検証**
+ パターン: `^[a-zA-Z][a-zA-Z0-9_]*$`
+ 英字で始まっている必要があります
+ 英字、数字、下線のみを含めることができます
**制限** – 置換は、特定の ENUM 値を持つスキーマのフィールドには適用されません。
**抽出タイプ**
```
{
"name": "userId",
"type": "BODY",
"path": "$.user.id"
}
```
```
{
"stepName": "loginAndExtract",
"checkerType": "HTTP",
"url": "https://api.example.com/login",
"httpMethod": "POST",
"body": "{\"username\":\"test\",\"password\":\"pass\"}",
"extractors": [
{
"name": "textVariable",
"type": "BODY",
"path": "$.myvalue"
}
]
},
{
"stepName": "substituteVariable",
"checkerType": "HTTP",
"url": "https://api.example.com/get/${textVariable}",
"httpMethod": "GET",
"assertions": [
{
"type": "BODY",
"target": "JSON",
"path": "$.users[0].name",
"operator": "EQUALS",
"value": "${textVariable}"
}
]
}
```