# 为 Node.js 多重检查蓝图编写 JSON 配置
<a name="CloudWatch_Synthetics_WritingCanary_Multichecks"></a>

借助 Node.js 多重检查蓝图，您可以创建可在单次金丝雀运行中执行多项验证检查的金丝雀。当您想要测试多个端点、验证应用程序的不同方面，或按顺序执行一系列相关检查时，此蓝图非常有用。

**Topics**
+ [根配置结构](#root-configuration-structure)
+ [全局设置](#global-settings)
+ [变量和数据管理](#variables-data-management)
+ [步骤定义](#step-definitions)
+ [检查类型](#check-types)
+ [身份验证方法](#authentication-methods)
+ [断言与验证](#assertions-validation)
+ [数据提取](#data-extraction)

## 根配置结构
<a name="root-configuration-structure"></a>

根配置定义了高级 API 蓝图金丝雀的整体结构。


**架构属性**  

| 属性 | Type | 必需 | 说明 | 
| --- | --- | --- | --- | 
|  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` 外，不允许使用其他属性

## 全局设置
<a name="global-settings"></a>

全局设置提供了应用于所有步骤的默认配置，除非在步骤级别被覆盖。

 **属性** 


**全局设置属性**  

| 属性 | Type | 默认 | Range | 说明 | 
| --- | --- | --- | --- | --- | 
|  stepTimeout  | 整数 | 30000 | 5000-300000 | 所有步骤的默认超时（毫秒） | 

 **示例** 

```
{
  "globalSettings": {
    "stepTimeout": 60000,
            
  }
}
```

## 变量和数据管理
<a name="variables-data-management"></a>

通过变量，您可以定义可重复使用的值，并在整个配置中使用 `${variableName}` 语法来引用它们。

 **变量属性** 


| 属性 | Type | 说明 | 
| --- | --- | --- | 
| 变量名称 | 字符串 | 必须匹配模式 ^[a-zA-Z][a-zA-Z0-9\$1]\$1\$1 | 
| 变量值 | 字符串 | 任意字符串值 | 

 **限制** 
+ 每个配置最多 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}"
      }
    }
  }
}
```

## 步骤定义
<a name="step-definitions"></a>

步骤定义了单独的监控操作。每个步骤从 1 到 10 编号，包含特定类型的检查。

 *常用步骤属性* 


| 属性 | Type | 必需 | 描述 | 
| --- | --- | --- | --- | 
|  stepName  | 字符串 |  是  | 步骤的唯一标识符 | 
|  checkerType  | 字符串 |  是  | 检查类型：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"
    }
  }
}
```

## 检查类型
<a name="check-types"></a>

### HTTP 检查
<a name="http-types"></a>

通过全面的请求和响应验证来监控 Web 端点和 API。

 **必需属性** 


| 属性 | Type | 说明 | 
| --- | --- | --- | 
|  url  | 字符串 | 目标 URL（必须是有效的 URI 格式） | 
|  httpMethod  | 字符串 | HTTP 方法：GET、POST、PUT、 PATCH、DELETE、HEAD、OPTIONS | 

 **可选属性** 


| 属性 | Type | 默认 | Range | 说明 | 
| --- | --- | --- | --- | --- | 
|  timeout  | 整数 | 30000 | 5000-300000 | 请求超时（毫秒） | 
|  waitTime  | 整数 | 0 | 0-60 | 请求前的延迟（秒） | 
|  headers  | object | - | - | 自定义 HTTP 标头 | 
|  body  | 字符串 | - | - | 用于 POST/PUT 操作的请求正文 | 
|  authentication  | object | - | - | 身份验证配置 | 
|  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 检查
<a name="dns-types"></a>

验证 DNS 解析并记录信息。

 **必需属性** 


| 属性 | Type | 说明 | 
| --- | --- | --- | 
|  domain  | 字符串 | 要查询的域名（主机名格式） | 

 **可选属性** 


| 属性 | Type | 默认值 | 说明 | 
| --- | --- | --- | --- | 
|  recordType  | 字符串 | “A” | DNS 记录类型：A、CNAME、MX、 TXT、NS | 
|  nameserver  | 字符串 | - | 要查询的特定 DNS 服务器 | 
|  timeout  | 整数 | 30000 | 查询超时（5000-300000 毫秒） | 
|  port  | 整数 | 53 | DNS 服务器端口（1-65535） | 
|  protocol  | 字符串 | “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 检查
<a name="ssl-types"></a>

监控 SSL 证书的运行状况和配置。

 **必需属性** 


| 属性 | Type | 说明 | 
| --- | --- | --- | 
|  hostname  | 字符串 | 目标主机名（主机名格式） | 

 **可选属性** 


| 属性 | Type | 默认值 | 描述 | 
| --- | --- | --- | --- | 
|  port  | 整数 | 443 | SSL 端口（1-65535） | 
|  timeout  | 整数 | 30000 | 连接超时（5000-300000 毫秒） | 
|  sni  | 布尔值 | TRUE | 服务器名称指示 | 
|  verifyHostname  | 布尔值 | 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 检查
<a name="tcp-types"></a>

测试 TCP 端口连接性和响应验证。

 **必需属性** 


| 属性 | Type | 说明 | 
| --- | --- | --- | 
|  hostname  | 字符串 | 目标主机名（主机名格式） | 
|  port  | 整数 | 目标端口（1-65535） | 

 **可选属性** 


| 属性 | Type | 默认值 | 描述 | 
| --- | --- | --- | --- | 
|  timeout  | 整数 | 30000 | 总超时（5000-300000 毫秒） | 
|  connectionTimeout  | 整数 | 3000 | 连接超时（5000-300000 毫秒） | 
|  readTimeout  | 整数 | 2000 | 数据读取超时（5000-300000 毫秒） | 
|  sendData  | 字符串 | - | 连接后要发送的数据 | 
|  expectedResponse  | 字符串 | - | 预期响应数据 | 
|  encoding  | 字符串 | “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
    }
  ]
}
```

## 身份验证方法
<a name="authentication-methods"></a>

 **不使用身份验证** 

```
{
  "type": "NONE"
}
```

 **基本身份验证** 


| 属性 | Type | 必需 | 描述 | 
| --- | --- | --- | --- | 
|  type  | 字符串 |  是  | 必须是 "BASIC" | 
|  username  | 字符串 |  是  | 用于身份验证的用户名 | 
|  password  | 字符串 |  是  | 用于身份验证的密码 | 

 **示例** 

```
{
  "type": "BASIC",
  "username": "admin",
  "password": "${AWS_SECRET:basic-auth:password}"
}
```

 **API 密钥身份验证** 


| 属性 | Type | 必需 | 默认值 | 说明 | 
| --- | --- | --- | --- | --- | 
|  type  | 字符串 |  是  | - | 必须是 "API\$1KEY" | 
|  apiKey  | 字符串 |  是  | - | API 密钥值 | 
|  headerName  | 字符串 | 否 | “X-API-Key” | API 密钥的标头名称 | 

 **示例** 

```
{
  "type": "API_KEY",
  "apiKey": "${AWS_SECRET:api-credentials}",
  "headerName": "Authorization"
}
```

 **OAuth 客户端凭证** 


| 属性 | Type | 必需 | 默认值 | 说明 | 
| --- | --- | --- | --- | --- | 
|  type  | 字符串 |  是  | - | 必须是 "OAUTH\$1CLIENT\$1CREDENTIALS" | 
|  tokenUrl  | 字符串 |  是  | - | OAuth 令牌端点 URL | 
|  clientId  | 字符串 |  是  | - | OAuth 客户端 ID | 
|  clientSecret  | 字符串 |  是  | - | OAuth 客户端密钥 | 
|  scope  | 字符串 | 否 | - | OAuth 范围 | 
|  audience  | 字符串 | 否 | - | OAuth 受众 | 
|  resource  | 字符串 | 否 | - | OAuth 资源 | 
|  tokenApiAuth  | array | 否 | - | 令牌 API 身份验证方法：BASIC\$1AUTH\$1HEADER、REQUEST\$1BODY | 
|  tokenCacheTtl  | 整数 | 否 | 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 签名（版本 4）** 


| 属性 | Type | 必需 | 描述 | 
| --- | --- | --- | --- | 
|  type  | 字符串 |  是  | 必须是 "SIGV4" | 
|  service  | 字符串 |  是  | AWS 服务的名称（例如“execute-api”） | 
|  region  | 字符串 |  是  | AWS 区域 | 
|  roleArn  | 字符串 |  是  | 用于签名的 IAM 角色 ARN | 

 **示例** 

```
{
  "type": "SIGV4",
  "service": "execute-api",
  "region": "us-east-1",
  "roleArn": "arn:aws:iam::123456789012:role/SyntheticsRole"
}
```

## 断言与验证
<a name="assertions-validation"></a>

### HTTP 断言
<a name="http-assertions"></a>

 **状态代码断言** 


| 属性 | Type | 必需 | 描述 | 
| --- | --- | --- | --- | 
|  type  | 字符串 |  是  | 必须是 "STATUS\$1CODE" | 
|  operator  | 字符串 |  是  | 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 | 必需 | 默认值 | 说明 | 
| --- | --- | --- | --- | --- | 
|  type  | 字符串 |  是  | - | 必须是 "RESPONSE\$1TIME" | 
|  operator  | 字符串 |  是  | - | LESS\$1THAN, GREATER\$1THAN, EQUALS | 
|  value  | 数字 |  是  | - | 时间值（最小 0） | 
|  unit  | 字符串 | 否 | “MILLISECONDS” | 必须是 "MILLISECONDS" | 

```
{
  "type": "RESPONSE_TIME",
  "operator": "LESS_THAN",
  "value": 500,
  "unit": "MILLISECONDS"
}
```

 **标头断言** 


| 属性 | Type | 必需 | 描述 | 
| --- | --- | --- | --- | 
|  type  | 字符串 |  是  | 必须是 "HEADER" | 
|  headerName  | 字符串 |  是  | 要验证的标头名称 | 
|  operator  | 字符串 |  是  | EQUALS, NOT\$1EQUALS, CONTAINS,  NOT\$1CONTAINS, REGEX\$1MATCH, EXIST | 
|  value  | 字符串/布尔值 | 有条件 | 预期值（EXIST 运算符为布尔值） | 

```
{
  "type": "HEADER",
  "headerName": "Content-Type",
  "operator": "CONTAINS",
  "value": "application/json"
}
```

 **正文断言** 


| 属性 | Type | 必需 | 默认值 | 说明 | 
| --- | --- | --- | --- | --- | 
|  type  | 字符串 |  是  | - | 必须是 "BODY" | 
|  target  | 字符串 | 否 | “JSON” | JSON 或 TEXT | 
|  path  | 字符串 | 有条件 | - | JSONPath（对于 JSON 目标是必需的） | 
|  operator  | 字符串 |  是  | - | CONTAINS, NOT\$1CONTAINS, EQUALS,  NOT\$1EQUALS, EXISTS | 
|  value  | 字符串/布尔值 |  是  | - | 预期值（EXISTS 运算符为布尔值） | 

```
{
  "type": "BODY",
  "target": "JSON",
  "path": "$.users[0].name",
  "operator": "EQUALS",
  "value": "John Doe"
}
```

### DNS 断言
<a name="dns-assertions"></a>

 **记录价值断言** 


| 属性 | Type | 必需 | Range | 说明 | 
| --- | --- | --- | --- | --- | 
|  type  | 字符串 |  是  | - | 必须是 "RECORD\$1VALUE" | 
|  operator  | 字符串 |  是  | - | EQUALS, NOT\$1EQUALS, CONTAINS,  NOT\$1CONTAINS, REGEX\$1MATCH | 
|  value  | 字符串 |  是  | - | 预期记录值 | 

 **记录计数断言** 


| 属性 | Type | 必需 | Range | 说明 | 
| --- | --- | --- | --- | --- | 
|  type  | 字符串 |  是  | - | 必须是 "RECORD\$1COUNT" | 
|  operator  | 字符串 |  是  | - | EQUALS, GREATER\$1THAN, LESS\$1THAN | 
|  value  | 整数 |  是  | ≥ 0 | 预期计数（最小 0） | 

 **授权断言** 


| 属性 | Type | 必需 | Range | 说明 | 
| --- | --- | --- | --- | --- | 
|  type  | 字符串 |  是  | - | 必须是 "AUTHORITATIVE" | 
|  value  | 布尔值 |  是  | - | 预期授权状态 | 

 **TTL 断言** 


| 属性 | Type | 必需 | Range | 说明 | 
| --- | --- | --- | --- | --- | 
|  type  | 字符串 |  是  | - | 必须是 "TTL" | 
|  operator  | 字符串 |  是  | - | EQUALS, GREATER\$1THAN, LESS\$1THAN | 
|  value  | 整数 |  是  | ≥ 0 | 预期 TTL（最小 0） | 

### SSL 断言
<a name="ssl-assertions"></a>

 **证书到期断言** 


| 属性 | Type | 必需 | 默认值 | 说明 | 
| --- | --- | --- | --- | --- | 
|  type  | 字符串 |  是  | - | 必须是 "CERTIFICATE\$1EXPIRY" | 
|  operator  | 字符串 |  是  | - | GREATER\$1THAN, LESS\$1THAN | 
|  value  | 整数 |  是  | - | 时间值（最小 0） | 
|  unit  | 字符串 | 否 | “DAYS” | DAYS, HOURS | 

 **证书主题断言** 


| 属性 | Type | 必需 | 默认值 | 说明 | 
| --- | --- | --- | --- | --- | 
|  type  | 字符串 |  是  | - | 必须是 "CERTIFICATE\$1SUBJECT" | 
|  field  | 字符串 |  是  | - | 主题字段：CN、O、OU、C、ST、L | 
|  operator  | 字符串 |  是  | - | CONTAINS, EQUALS, REGEX\$1MATCH | 
|  value  | 字符串 |  是  | - | 预期字段值 | 

 **证书颁发者断言** 


| 属性 | Type | 必需 | 默认值 | 说明 | 
| --- | --- | --- | --- | --- | 
|  type  | 字符串 |  是  | - | 必须是 "CERTIFICATE\$1ISSUER" | 
|  field  | 字符串 |  是  | - | 颁发者字段：CN、O | 
|  operator  | 字符串 |  是  | - | CONTAINS, EQUALS | 
|  value  | 字符串 |  是  | - | 预期字段值 | 

### TCP 断言
<a name="tcp-assertions"></a>

 **连接成功断言** 


| 属性 | Type | 必需 | 默认值 | 说明 | 
| --- | --- | --- | --- | --- | 
|  type  | 字符串 |  是  | - | 必须是 "CONNECTION\$1SUCCESSFUL" | 
|  value  | 布尔值 |  是  | - | 预期连接状态 | 

 **响应数据断言** 


| 属性 | Type | 必需 | 默认值 | 说明 | 
| --- | --- | --- | --- | --- | 
|  type  | 字符串 |  是  | - | 必须是 "RESPONSE\$1DATA" | 
|  operator  | 字符串 |  是  | - | CONTAINS, EQUALS, NOT\$1CONTAINS,  REGEX\$1MATCH, STARTS\$1WITH, ENDS\$1WITH | 
|  value  | 字符串 |  是  | - | 预期响应数据 | 
|  encoding  | 字符串 | 否 | “UTF-8” | UTF-8, ASCII, HEX | 

## 数据提取
<a name="data-extraction"></a>

借助提取器，您可以从响应中捕获数据，用于后续步骤或报告目的。

 **提取属性** 


| 属性 | Type | 必需 | 默认值 | 说明 | 
| --- | --- | --- | --- | --- | 
|  name  | 字符串 |  是  | - | 提取数据的变量名称 | 
|  type  | 字符串 |  是  | - | 提取类型：BODY | 
|  path  | 字符串 | 否 | - | 用于正文提取的 JSONPath | 
|  regex  | 字符串 | 否 | - | 正则表达式模式 | 
|  regexGroup  | 整数 | 否 | 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}"
    }
  ]
}
```