# 使用金丝雀蓝图
<a name="CloudWatch_Synthetics_Canaries_Blueprints"></a>

本节提供有关每种金丝雀蓝图的详细信息以及每种蓝图最适合的任务。为以下金丝雀类型提供了蓝图：

**Topics**
+ [检测信号监控](#CloudWatch_Synthetics_Canaries_Blueprints_Heartbeat)
+ [API 金丝雀](#CloudWatch_Synthetics_Canaries_Blueprints_API)
+ [失效链接检查器](#CloudWatch_Synthetics_Canaries_Blueprints_Broken_Links)
+ [可视监控蓝图](#CloudWatch_Synthetics_Canaries_Blueprints_VisualTesting)
+ [金丝雀记录器](#CloudWatch_Synthetics_Canaries_Blueprints_Recorder)
+ [GUI 工作流生成器](#CloudWatch_Synthetics_Canaries_Blueprints_GUI_Workflow)
+ [多重检查蓝图](#CloudWatch_Synthetics_Canaries_Blueprints_Multichecks_Blueprint)
+ [创建多重检查蓝图金丝雀](CloudWatch_Synthetics_Canaries_MultiCheck_Blueprint.md)

当您使用蓝图创建金丝雀时，在填写 CloudWatch 控制台中的字段时，页面的 **Script editor（脚本编辑器）**区域会将您正在创建的金丝雀显示为 Node.js 脚本。您还可以在此区域编辑金丝雀以进一步定制。

## 检测信号监控
<a name="CloudWatch_Synthetics_Canaries_Blueprints_Heartbeat"></a>

检测信号脚本加载指定的 URL，并存储页面的屏幕截图和 HTTP 归档文件（HAR 文件）。它们还存储已访问 URL 的日志。

您可以使用 HAR 文件查看有关网页性能的详细数据。您可以分析 Web 请求列表并捕获性能问题，例如某个项的加载时间。

如果您的金丝雀使用 `syn-nodejs-puppeteer-3.1` 或更高版本的运行时，您可以使用检测信号监控蓝图，以监控多个 URL 并查看状态、持续时间、关联的屏幕截图和金丝雀运行报告的步骤摘要中各个 URL 的故障原因。

## API 金丝雀
<a name="CloudWatch_Synthetics_Canaries_Blueprints_API"></a>

API 金丝雀可以测试 REST API 的基本读写函数。REST 指*表述性状态转移*，是开发人员在创建 API 时需要遵循的一组规则。其中一条规则规定，指向特定 URL 的链接应返回一段数据。

金丝雀可与任何 API 结合使用并测试所有类型的功能。每个金丝雀都可以做出多个 API 调用。

在使用 `syn-nodejs-2.2` 或更高版本运行时的金丝雀中，API 金丝雀蓝图支持将 API 作为 HTTP 步骤进行监控的多步骤金丝雀。您可以在单个金丝雀中测试多个 API。每个步骤都是一个单独的请求，可以访问不同的 URL、使用不同的标头以及对是否捕获标题和响应正文使用不同的规则。通过不捕获标头和响应正文，可以防止敏感数据被记录下来。

API 金丝雀中的每个请求均包含以下信息：
+ *终端节点*，即您请求的 URL。
+ *方法*，它是发送到服务器的请求类型。REST API 支持 GET（读取）、POST（写入）、PUT（更新）、PATCH（更新）和 DELETE（删除）操作。
+ *标头*，用于向客户端和服务器提供信息。它们用于身份验证和提供有关正文内容的信息。有关有效标头的列表，请参阅 [HTTP 标头](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers)。
+ *数据*（或*正文*），其中包含要发送到服务器的信息。这仅用于 POST、PUT、PATCH 或 DELETE 请求。

**注意**  
Playwright 运行时不支持 API Canary 蓝图。

API 金丝雀蓝图支持 GET 和 POST 方法。使用此蓝图时，您必须指定标头。例如，您可以指定 **Authorization** 作为**键**，并指定必要的授权数据作为该键的**值**。

如果您在测试 POST 请求，还可以在**数据**字段中指定要发布的内容。

 **与 API Gateway 的集成** 

API 蓝图与 Amazon API Gateway 集成。因此，您能够从与该金丝雀所在的同一个 Amazon 账户和区域选择一个 API Gateway API 和阶段，或上载 API Gateway 中的 Swagger 模板以进行跨账户和跨区域 API 监控。然后，您可以在控制台中选择其余详细信息来创建金丝雀，而不是从 Scratch 输入这些详细信息。有关 API Gateway 的更多信息，请参阅[什么是 Amazon API Gateway？](https://docs.amazonaws.cn/apigateway/latest/developerguide/welcome.html)。

 **使用私有 API** 

您可以在 Amazon API Gateway 中创建使用私有 API 的金丝雀。有关更多信息，请参阅 [在 Amazon API Gateway 中创建私有 API?](https://docs.amazonaws.cn/apigateway/latest/developerguide/apigateway-private-apis.html)

## 失效链接检查器
<a name="CloudWatch_Synthetics_Canaries_Blueprints_Broken_Links"></a>

无效链接检查器通过使用 `document.getElementsByTagName('a')` 收集您正在测试的 URL 内的所有链接。它仅测试您指定数量的链接，而且 URL 本身计为第一个链接。例如，如果要检查包含五个链接的页面上的所有链接，则必须指定金丝雀跟踪六个链接。

使用 `syn-nodejs-2.0-beta` 或更高版本运行时创建的无效链接检查器金丝雀支持以下额外功能：
+ 提供包含所检查链接、状态代码、故障原因（如有）以及源页面和目标页面屏幕截图的报告。
+ 查看金丝雀结果时，您可以筛选以仅查看无效链接，然后根据故障原因修复链接。
+ 此版本会捕获每个链接的带注释源页面屏幕截图，并突出显示链接所在的锚点。不会对隐藏组件添加注释。
+ 您可以将此版本配置为捕获源页面和目标页面的屏幕截图、仅捕获源页面或仅捕获目标页面的屏幕截图。
+ 此版本修复了早期版本中的一个问题，在早期版本中，即使从第一页抓取了更多链接，金丝雀脚本也会在第一个无效链接后停止。

**注意**  
Playwright 运行时不支持无效链接检查器蓝图。

要使用 `syn-1.0` 来更新现有 Canary 以使用新的运行时，则必须删除并重新创建 Canary。这些功能并不会随着将现有金丝雀更新到新运行时而变得可用。

无效链接检查器金丝雀可检测以下类型的链接错误：
+ 404 未找到页面
+ 主机名无效
+ 错误的 URL。例如，URL 缺少括号、包含多余的斜线，或者协议错误。
+ 无效的 HTTP 响应代码。
+ 主机服务器返回没有内容和没有响应代码的空响应。
+ HTTP 请求在金丝雀运行期间持续超时。
+ 主机持续丢弃连接，因为它配置错误或太忙。

## 可视监控蓝图
<a name="CloudWatch_Synthetics_Canaries_Blueprints_VisualTesting"></a>

可视化监控蓝图包含用以比较在金丝雀运行期间捕获的屏幕截图与在基准金丝雀运行期间捕获的屏幕截图的代码。如果两个屏幕截图之间的差异超过阈值百分比，则金丝雀将失败。运行 **syn-puppeteer-node-3.2** 和更高版本的金丝雀支持可视化监控。运行 Python 和 Selenium 或使用 Playwright 运行时的 Canary 中目前不支持可视化监控。

可视化监控蓝图在默认蓝图金丝雀脚本中包含以下代码行，这些代码可实现可视化监控。

```
syntheticsConfiguration.withVisualCompareWithBaseRun(true);
```

将此行添加到脚本后，金丝雀首次成功运行时，它会使用在该运行期间捕获的屏幕截图作为比较基准。在金丝雀的该首次运行之后，您可以使用 CloudWatch 控制台编辑金丝雀以执行以下任一操作：
+ 将金丝雀的下一次运行设置为新基准。
+ 在当前基准屏幕截图上绘制边界，以指定在可视化比较过程中要忽略的屏幕截图区域。
+ 删除屏幕截图，使其不用于可视化监控。

有关使用 CloudWatch 控制台编辑金丝雀的更多信息，请参阅 [编辑或删除金丝雀脚本](synthetics_canaries_deletion.md)。

您还可以通过使用 ` nextrun` 或 `lastrun` 参数或在 [UpdateCanary](https://docs.amazonaws.cn/AmazonSynthetics/latest/APIReference/API_UpdateCanary.html) API 中指定金丝雀运行 ID 来更改用作基准的金丝雀运行。

使用可视化监控蓝图时，您可以输入要在其中捕获屏幕截图的 URL，并将差值阈值指定为百分比。在基准运行之后，只要在金丝雀的未来运行中检测到大于该阈值的可视化差异，便会触发金丝雀故障。在基准运行之后，您还可以编辑金丝雀，以在可视化监控过程中要忽略的基准屏幕截图上“绘制”边界。

可视化监控功能由 ImageMagick 开源软件工具包提供支持。有关更多信息，请参阅 [ImageMagick](https://imagemagick.org/index.php)。

## 金丝雀记录器
<a name="CloudWatch_Synthetics_Canaries_Blueprints_Recorder"></a>

使用金丝雀记录器蓝图，您可以使用 CloudWatch Synthetics Recorder 记录您的点击并在网站上键入操作，并自动生成可用于创建按相同步骤操作的金丝雀的 Node.js 脚本。CloudWatch Synthetics Recorder 是 Amazon 推出的 Google Chrome 扩展程序。使用 Playwright 运行时的 Canary 不支持 Canary 记录器。

**开发团队**：CloudWatch Synthetics Recorder 基于[无头记录器](https://github.com/checkly/headless-recorder)。

有关更多信息，请参阅 [使用面向 Google Chrome 的 CloudWatch Synthetics Recorder](CloudWatch_Synthetics_Canaries_Recorder.md)。

## GUI 工作流生成器
<a name="CloudWatch_Synthetics_Canaries_Blueprints_GUI_Workflow"></a>

GUI 工作流生成器蓝图验证是否可以在您的网页上执行操作。例如，如果您有一个带有登录表单的网页，则金丝雀可以填充用户和密码字段并提交表单，以验证网页是否正常工作。

当您使用蓝图创建此类型的金丝雀时，可以指定希望金丝雀在网页上执行的操作。您可以使用的操作如下：
+ **单击** – 选择您要指定的元素，然后模拟用户单击或选择该元素的行为。

  若要在 Node.js 脚本中指定该元素，请使用 `[id=]` 或 ` a[class=]`。

  若要在 Python 脚本中指定该元素，请使用 `xpath //*[@id=]` 或 ` //*[@class=]`。
+ **验证选择器** – 验证网页上存在指定的元素。此测试对于验证之前的操作是否导致使用正确的元素填充页面非常有用。

  若要在 Node.js 脚本中指定待验证的元素，请使用 `[id=]` 或 ` a[class=]`。

  若要在 Python 脚本中指定待验证的元素，请使用 `xpath //*[@id=]` 或 `//*[class=]`。
+ **验证文本** – 验证指定的字符串是否包含在目标元素中。此测试对于验证之前的操作是否导致显示正确的文本非常有用。

  若要在 Node.js 脚本中指定元素，请使用诸如 ` div[@id=]//h1` 之类的格式，因为此操作使用 Puppeteer 中的 `waitForXPath` 函数。

  若要在 Python 脚本中指定元素，请使用 xpath 格式（例如 ` //*[@id=] ` 或 //\$1[@class=]），因为此操作使用 Selenium 中的 `implicitly_wait` 函数。
+ **输入文本** – 在目标元素中写入指定的文本。

  若要在 Node.js 脚本中指定待验证的元素，请使用 `[id=]` 或 ` a[class=]`。

  若要在 Python 脚本中指定待验证的元素，请使用 `xpath //*[@id=]` 或 `//*[@class=]`。
+ **单击并导航** – 在选择指定的元素之后，等待整个页面加载。当您需要重新加载页面时，这非常有用。

  若要在 Node.js 脚本中指定该元素，请使用 `[id=]` 或 ` a[class=]`。

  若要在 Python 脚本中指定该元素，请使用 `xpath //*[@id=]` 或 ` //*[@class=]`。

例如，以下蓝图使用 Node.js。其会单击指定 URL 上的 **firstButton**，验证预期的选择器是否出现了预期文本，将名称 `Test_Customer` 输入到 **Name**（名称）字段中，单击 **Login**（登录）按钮，然后通过检查下一页上的 **Welcome**（欢迎）文本来验证登录是否成功。

![\[控制台中的创建金丝雀页面，其中填充了 GUI 工作流蓝图的字段。\]](http://docs.amazonaws.cn/AmazonCloudWatch/latest/monitoring/images/canary_create_gui_workflow.PNG)


使用以下运行时的 GUI 工作流金丝雀还提供每次金丝雀运行所执行的步骤的摘要。您可以使用与每个步骤关联的屏幕截图和错误消息来查找故障的根本原因。
+ `syn-nodejs-2.0` 或更高版本
+ `syn-python-selenium-1.0` 或更高版本

## 多重检查蓝图
<a name="CloudWatch_Synthetics_Canaries_Blueprints_Multichecks_Blueprint"></a>

多重检查蓝图简化了金丝雀的创建过程。它通过简单的 JSON 配置提供了开箱即用的功能，用于执行 HTTP、DNS、SSL 和 TCP 检查，从而降低了成本。最多可以配置 10 项检查。将每项检查配置为按顺序运行的数字步骤，以便清晰理解金丝雀执行流程。

多重检查蓝图支持：
+ 基本 HTTP 请求、TCP 请求；验证 DNS 记录、监控 SSL 证书
+ 与 Secrets Manager 集成的 HTTP 身份验证方法，例如 Basic、API Key、OAuth 和 Sigv4
+ 针对每项检查的断言

有关更多信息，请参阅 [创建金丝雀](CloudWatch_Synthetics_Canaries_Create.md)。