# 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\_]\*$ と一致する必要があります |
| 変数値 | 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\_-]\*$
+ 最大文字数 - 64 文字
+ 英字で始まっている必要があります
*ステップの番号付け*
+ ステップには、文字列キーとして「1」、「2」、...、「10」という番号が付けられます。
+ パターン: ^([1-9]\|10)$
+ 最低 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 | ブール値 | 誤 | 自己署名証明書の受け入れ |
| 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\_KEY" を指定してください |
| apiKey | string | はい | - | API キー値 |
| headerName | string | いいえ | 「X-API-Key」 | API キーのヘッダー名 |
**例**
```
{
"type": "API_KEY",
"apiKey": "${AWS_SECRET:api-credentials}",
"headerName": "Authorization"
}
```
**OAuth クライアントの認証情報**
| プロパティ | タイプ | 必須 | デフォルト | 説明 |
| --- | --- | --- | --- | --- |
| type | 文字列 | はい | - | "OAUTH\_CLIENT\_CREDENTIALS" を指定してください |
| tokenUrl | string | はい | - | OAuth トークンエンドポイント URL |
| clientId | string | はい | - | OAuth クライアント ID |
| clientSecret | string | はい | - | OAuth クライアントシークレット |
| scope | string | いいえ | - | OAuth スコープ |
| audience | string | いいえ | - | OAuth 対象者 |
| resource | string | いいえ | - | OAuth リソース |
| tokenApiAuth | array | いいえ | - | トークン API 認証メソッド: BASIC\_AUTH\_HEADER、REQUEST\_BODY |
| 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\_CODE" を指定してください |
| operator | string | はい | EQUALS, NOT\_EQUALS, GREATER\_THAN, LESS\_THAN, IN\_RANGE |
| value | 整数 | 条件付き | HTTP ステータスコード (100～599) |
| rangeMin | 整数 | 条件付き | 最小範囲値 (IN\_RANGE の場合) |
| rangeMax | 整数 | 条件付き | 最大範囲値 (IN\_RANGE の場合) |
```
{
"type": "STATUS_CODE",
"operator": "EQUALS",
"value": 200
}
```
**応答時間のアサーション**
| プロパティ | タイプ | 必須 | デフォルト | 説明 |
| --- | --- | --- | --- | --- |
| type | 文字列 | はい | - | "RESPONSE\_TIME" を指定してください |
| operator | string | はい | - | LESS\_THAN, GREATER\_THAN, 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\_EQUALS, CONTAINS, NOT\_CONTAINS, REGEX\_MATCH, 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\_CONTAINS, EQUALS, NOT\_EQUALS, EXISTS |
| value | 文字列/ブール型 | はい | - | 予想される値 (EXISTS 演算子のブール値) |
```
{
"type": "BODY",
"target": "JSON",
"path": "$.users[0].name",
"operator": "EQUALS",
"value": "John Doe"
}
```
### DNS アサーション
**レコード値のアサーション**
| プロパティ | タイプ | 必須 | Range | 説明 |
| --- | --- | --- | --- | --- |
| type | 文字列 | はい | - | "RECORD\_VALUE" を指定してください |
| operator | string | はい | - | EQUALS, NOT\_EQUALS, CONTAINS, NOT\_CONTAINS, REGEX\_MATCH |
| value | string | はい | - | 予想されるレコード値 |
**レコード数のアサーション**
| プロパティ | タイプ | 必須 | Range | 説明 |
| --- | --- | --- | --- | --- |
| type | 文字列 | はい | - | "RECORD\_COUNT" を指定してください |
| operator | string | はい | - | EQUALS, GREATER\_THAN, LESS\_THAN |
| value | integer | はい | ≥ 0 | 予想される個数 (最小 0) |
**認可アサーション**
| プロパティ | タイプ | 必須 | Range | 説明 |
| --- | --- | --- | --- | --- |
| type | 文字列 | はい | - | "AUTHORITATIVE" を指定してください |
| value | boolean | はい | - | 想定される認可ステータス |
**TTL アサーション**
| プロパティ | タイプ | 必須 | Range | 説明 |
| --- | --- | --- | --- | --- |
| type | 文字列 | はい | - | "TTL" を指定してください |
| operator | string | はい | - | EQUALS, GREATER\_THAN, LESS\_THAN |
| value | integer | はい | ≥ 0 | 予想される TTL (最小 0) |
### SSL アサーション
**証明書の有効期限のアサーション**
| プロパティ | タイプ | 必須 | デフォルト | 説明 |
| --- | --- | --- | --- | --- |
| type | 文字列 | はい | - | "CERTIFICATE\_EXPIRY" を指定してください |
| operator | string | はい | - | GREATER\_THAN, LESS\_THAN |
| value | integer | はい | - | 時間値 (最小 0) |
| unit | string | いいえ | 「DAYS」 | DAYS, HOURS |
**証明書のサブジェクトのアサーション**
| プロパティ | タイプ | 必須 | デフォルト | 説明 |
| --- | --- | --- | --- | --- |
| type | 文字列 | はい | - | "CERTIFICATE\_SUBJECT" を指定してください |
| field | string | はい | - | サブジェクトフィールド: CN、O、OU、C、ST、L |
| operator | string | はい | - | CONTAINS, EQUALS, REGEX\_MATCH |
| value | string | はい | - | 予想されるフィールド値 |
**証明書発行者のアサーション**
| プロパティ | タイプ | 必須 | デフォルト | 説明 |
| --- | --- | --- | --- | --- |
| type | 文字列 | はい | - | "CERTIFICATE\_ISSUER" を指定してください |
| field | string | はい | - | 発行者フィールド: CN、O |
| operator | string | はい | - | CONTAINS, EQUALS |
| value | string | はい | - | 予想されるフィールド値 |
### TCP アサーション
**接続成功アサーション**
| プロパティ | タイプ | 必須 | デフォルト | 説明 |
| --- | --- | --- | --- | --- |
| type | 文字列 | はい | - | "CONNECTION\_SUCCESSFUL" を指定してください |
| value | boolean | はい | - | 予想される接続ステータス |
**レスポンスデータのアサーション**
| プロパティ | タイプ | 必須 | デフォルト | 説明 |
| --- | --- | --- | --- | --- |
| type | 文字列 | はい | - | "RESPONSE\_DATA" を指定してください |
| operator | string | はい | - | CONTAINS, EQUALS, NOT\_CONTAINS, REGEX\_MATCH, STARTS\_WITH, ENDS\_WITH |
| 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}"
}
]
}
```