本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 撰寫 Node.js 多重檢查藍圖的 JSON 組態
Node.js 多重檢查藍圖可讓您建立 Canary，在單一 Canary 執行中執行多個驗證檢查。當您想要測試多個端點、驗證應用程式的不同層面，或依序執行一系列相關檢查時，此藍圖非常有用。
**Topics**
+ [根組態結構](#root-configuration-structure)
+ [全域設定](#global-settings)
+ [變數和資料管理](#variables-data-management)
+ [步驟定義](#step-definitions)
+ [檢查類型](#check-types)
+ [身分驗證方法](#authentication-methods)
+ [聲明和驗證](#assertions-validation)
+ [資料擷取](#data-extraction)
## 根組態結構
根組態會定義進階 API 藍圖 Canary 的整體結構。
**結構描述屬性**
| 屬性 | Type | 必要 | Description |
| --- | --- | --- | --- |
| 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"
}
}
}
```
**驗證規則**
+ 必須至少包含一個步驟
+ 允許最多 10 個步驟
+ 不允許超過 `globalSettings`、 ` variables`和 的其他屬性 `steps`
## 全域設定
除非在步驟層級覆寫，否則全域設定會提供適用於所有步驟的預設組態。
**屬性**
**全域設定屬性**
| 屬性 | Type | 預設 | 範圍 | Description |
| --- | --- | --- | --- | --- |
| stepTimeout | integer | 30000 | 5000-300000 | 所有步驟的預設逾時 （毫秒） |
**範例**
```
{
"globalSettings": {
"stepTimeout": 60000,
}
}
```
## 變數和資料管理
變數可讓您定義可重複使用的值，這些值可以使用`${variableName}`語法在整個組態中參考。
**變數屬性**
| 屬性 | Type | 說明 |
| --- | --- | --- |
| 變數名稱 | 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，並包含特定類型的檢查。
*常見步驟屬性*
| 屬性 | Type | 必要 | 描述 |
| --- | --- | --- | --- |
| stepName | string | 是 | 步驟的唯一識別符 |
| checkerType | string | 是 | 檢查類型：HTTP、DNS、SSL、 TCP |
| extractors | 陣列 | 否 | 資料擷取組態 |
*步驟名稱驗證*
+ 模式 - ^【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 檢查
透過全面的請求和回應驗證來監控 Web 端點和 APIs。
**必要屬性**
| 屬性 | Type | Description |
| --- | --- | --- |
| url | string | 目標 URL （必須是有效的 URI 格式） |
| httpMethod | string | HTTP 方法：GET、POST、PUT、 PATCH、DELETE、HEAD、 OPTIONS |
**選用屬性**
| 屬性 | Type | 預設 | 範圍 | Description |
| --- | --- | --- | --- | --- |
| timeout | integer | 30000 | 5000-300000 | 請求逾時 （毫秒） |
| waitTime | integer | 0 | 0-60 | 請求之前的延遲 （秒） |
| headers | object | - | - | 自訂 HTTP 標頭 |
| body | string | - | - | POST/PUT 操作的請求內文 |
| authentication | object | - | - | 身分驗證組態 |
| assertions | 陣列 | - | - | 回應驗證規則 |
**範例**
```
{
"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 解析並記錄資訊。
**必要屬性**
| 屬性 | Type | Description |
| --- | --- | --- |
| domain | string | 要查詢的網域名稱 （主機名稱格式） |
**選用屬性**
| 屬性 | Type | 預設 | Description |
| --- | --- | --- | --- |
| recordType | string | 「A」 | DNS 記錄類型：A、CNAME、MX、 TXT、 NS |
| nameserver | string | - | 要查詢的特定 DNS 伺服器 |
| timeout | integer | 30000 | 查詢逾時 (5000-300000ms) |
| port | integer | 53 | DNS 伺服器連接埠 (1-65535) |
| protocol | string | 「UDP」 | 通訊協定： UDP 或 TCP |
| assertions | 陣列 | - | 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 憑證運作狀態和組態。
**必要屬性**
| 屬性 | Type | Description |
| --- | --- | --- |
| hostname | string | 目標主機名稱 （主機名稱格式） |
**選用屬性**
| 屬性 | Type | 預設 | 描述 |
| --- | --- | --- | --- |
| port | integer | 443 | SSL 連接埠 (1-65535) |
| timeout | integer | 30000 | 連線逾時 (5000-300000ms) |
| sni | boolean | TRUE | 伺服器名稱指示 |
| verifyHostname | boolean | TRUE | 主機名稱驗證 |
| allowSelfSigned | boolean | FALSE | 接受自我簽署憑證 |
| assertions | 陣列 | - | 憑證驗證規則 |
**範例**
```
{
"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 連接埠連線和回應驗證。
**必要屬性**
| 屬性 | Type | Description |
| --- | --- | --- |
| hostname | string | 目標主機名稱 （主機名稱格式） |
| port | integer | 目標連接埠 (1-65535) |
**選用屬性**
| 屬性 | Type | 預設 | 描述 |
| --- | --- | --- | --- |
| timeout | integer | 30000 | 整體逾時 (5000-300000ms) |
| connectionTimeout | integer | 3000 | 連線逾時 (5000-300000ms) |
| readTimeout | integer | 2000 | 資料讀取逾時 (5000-300000ms) |
| sendData | string | - | 連線後要傳送的資料 |
| expectedResponse | string | - | 預期的回應資料 |
| encoding | string | 「UTF-8」 | 資料編碼：UTF-8、ASCII、 HEX |
| assertions | 陣列 | - | 連線和回應驗證 |
**範例**
```
{
"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 | 必要 | 描述 |
| --- | --- | --- | --- |
| type | string | 是 | 必須為 "BASIC" |
| username | string | 是 | 身分驗證的使用者名稱 |
| password | string | 是 | 用於身分驗證的密碼 |
**範例**
```
{
"type": "BASIC",
"username": "admin",
"password": "${AWS_SECRET:basic-auth:password}"
}
```
**API 金鑰身分驗證**
| 屬性 | Type | 必要 | 預設 | Description |
| --- | --- | --- | --- | --- |
| type | string | 是 | - | 必須為 "API\$1KEY" |
| apiKey | string | 是 | - | API 金鑰值 |
| headerName | string | 否 | "X-API-Key" | API 金鑰的標頭名稱 |
**範例**
```
{
"type": "API_KEY",
"apiKey": "${AWS_SECRET:api-credentials}",
"headerName": "Authorization"
}
```
**OAuth 用戶端登入資料**
| 屬性 | Type | 必要 | 預設 | Description |
| --- | --- | --- | --- | --- |
| type | string | 是 | - | 必須為 "OAUTH\$1CLIENT\$1CREDENTIALS" |
| tokenUrl | string | 是 | - | OAuth 權杖端點 URL |
| clientId | string | 是 | - | OAuth 用戶端 ID |
| clientSecret | string | 是 | - | OAuth 用戶端秘密 |
| scope | string | 否 | - | OAuth 範圍 |
| audience | string | 否 | - | OAuth 對象 |
| resource | string | 否 | - | OAuth 資源 |
| tokenApiAuth | 陣列 | 否 | - | Token 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 | 必要 | 描述 |
| --- | --- | --- | --- |
| type | string | 是 | 必須為 "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 | 必要 | 描述 |
| --- | --- | --- | --- |
| type | string | 是 | 必須為 "STATUS\$1CODE" |
| operator | string | 是 | EQUALS, NOT\$1EQUALS, GREATER\$1THAN, LESS\$1THAN, IN\$1RANGE |
| value | integer | 有條件 | HTTP 狀態碼 (100-599) |
| rangeMin | integer | 有條件 | 最小範圍值 （適用於 IN\$1RANGE) |
| rangeMax | integer | 有條件 | 最大範圍值 （適用於 IN\$1RANGE) |
```
{
"type": "STATUS_CODE",
"operator": "EQUALS",
"value": 200
}
```
**回應時間聲明**
| 屬性 | Type | 必要 | 預設 | Description |
| --- | --- | --- | --- | --- |
| type | string | 是 | - | 必須為 "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 | 必要 | 描述 |
| --- | --- | --- | --- |
| type | string | 是 | 必須為 "HEADER" |
| headerName | string | 是 | 要驗證的標頭名稱 |
| operator | string | 是 | EQUALS, NOT\$1EQUALS, CONTAINS, NOT\$1CONTAINS, REGEX\$1MATCH, EXIST |
| value | string/boolean | 有條件 | 預期值 (EXIST運算子的布林值） |
```
{
"type": "HEADER",
"headerName": "Content-Type",
"operator": "CONTAINS",
"value": "application/json"
}
```
**內文聲明**
| 屬性 | Type | 必要 | 預設 | Description |
| --- | --- | --- | --- | --- |
| type | string | 是 | - | 必須為 "BODY" |
| target | string | 否 | 「JSON」 | JSON 或 TEXT |
| path | string | 有條件 | - | JSONPath (JSON 目標需要） |
| operator | string | 是 | - | CONTAINS, NOT\$1CONTAINS, EQUALS, NOT\$1EQUALS, EXISTS |
| value | string/boolean | 是 | - | 預期值 (EXISTS運算子的布林值） |
```
{
"type": "BODY",
"target": "JSON",
"path": "$.users[0].name",
"operator": "EQUALS",
"value": "John Doe"
}
```
### DNS 聲明
**記錄值聲明**
| 屬性 | Type | 必要 | 範圍 | Description |
| --- | --- | --- | --- | --- |
| type | string | 是 | - | 必須為 "RECORD\$1VALUE" |
| operator | string | 是 | - | EQUALS, NOT\$1EQUALS, CONTAINS, NOT\$1CONTAINS, REGEX\$1MATCH |
| value | string | 是 | - | 預期的記錄值 |
**記錄計數宣告**
| 屬性 | Type | 必要 | 範圍 | Description |
| --- | --- | --- | --- | --- |
| type | string | 是 | - | 必須為 "RECORD\$1COUNT" |
| operator | string | 是 | - | EQUALS, GREATER\$1THAN, LESS\$1THAN |
| value | integer | 是 | ≥ 0 | 預期計數 （最低 0) |
**授權聲明**
| 屬性 | Type | 必要 | 範圍 | Description |
| --- | --- | --- | --- | --- |
| type | string | 是 | - | 必須為 "AUTHORITATIVE" |
| value | boolean | 是 | - | 預期的授權狀態 |
**TTL 聲明**
| 屬性 | Type | 必要 | 範圍 | Description |
| --- | --- | --- | --- | --- |
| type | string | 是 | - | 必須為 "TTL" |
| operator | string | 是 | - | EQUALS, GREATER\$1THAN, LESS\$1THAN |
| value | integer | 是 | ≥ 0 | 預期的 TTL （最低 0) |
### SSL 聲明
**憑證過期聲明**
| 屬性 | Type | 必要 | 預設 | Description |
| --- | --- | --- | --- | --- |
| type | string | 是 | - | 必須為 "CERTIFICATE\$1EXPIRY" |
| operator | string | 是 | - | GREATER\$1THAN, LESS\$1THAN |
| value | integer | 是 | - | 時間值 （最小值為 0) |
| unit | string | 否 | 「天」 | DAYS, HOURS |
**憑證主體聲明**
| 屬性 | Type | 必要 | 預設 | Description |
| --- | --- | --- | --- | --- |
| type | string | 是 | - | 必須為 "CERTIFICATE\$1SUBJECT" |
| field | string | 是 | - | 主旨欄位：CN、O、OU、C、ST、 L |
| operator | string | 是 | - | CONTAINS, EQUALS, REGEX\$1MATCH |
| value | string | 是 | - | 預期的欄位值 |
**憑證發行者聲明**
| 屬性 | Type | 必要 | 預設 | Description |
| --- | --- | --- | --- | --- |
| type | string | 是 | - | 必須為 "CERTIFICATE\$1ISSUER" |
| field | string | 是 | - | 發行者欄位：CN、 O |
| operator | string | 是 | - | CONTAINS, EQUALS |
| value | string | 是 | - | 預期的欄位值 |
### TCP 聲明
**連線成功聲明**
| 屬性 | Type | 必要 | 預設 | Description |
| --- | --- | --- | --- | --- |
| type | string | 是 | - | 必須為 "CONNECTION\$1SUCCESSFUL" |
| value | boolean | 是 | - | 預期的連線狀態 |
**回應資料聲明**
| 屬性 | Type | 必要 | 預設 | Description |
| --- | --- | --- | --- | --- |
| type | string | 是 | - | 必須為 "RESPONSE\$1DATA" |
| operator | string | 是 | - | CONTAINS, EQUALS, NOT\$1CONTAINS, REGEX\$1MATCH, STARTS\$1WITH, ENDS\$1WITH |
| value | string | 是 | - | 預期的回應資料 |
| encoding | string | 否 | 「UTF-8」 | UTF-8, ASCII, HEX |
## 資料擷取
擷取器可讓您從回應擷取資料，以用於後續步驟或報告目的。
**擷取屬性**
| 屬性 | Type | 必要 | 預設 | Description |
| --- | --- | --- | --- | --- |
| name | string | 是 | - | 擷取資料的變數名稱 |
| type | string | 是 | - | 擷取類型： BODY |
| path | string | 否 | - | 用於內文擷取的 JSONPath |
| regex | string | 否 | - | 規則表達式模式 |
| regexGroup | integer | 否 | 0 | Regex 擷取群組 （最低 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}"
}
]
}
```