# @aws-cdk/aws-synthetics 中文文档

规范地址：https://npmcn.com/package/%40aws-cdk/aws-synthetics/

版本：1\.204\.0
npm 元数据更新时间：2023-11-21T10:12:50.609Z
中文译文更新时间：2026-11-07T17:51:45.739Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40aws-cdk/aws-synthetics
原文对照：https://npmcn.com/package/%40aws-cdk/aws-synthetics/?lang=original
项目主页：https://github.com/aws/aws-cdk
源码仓库：https://github.com/aws/aws-cdk

弃用说明：AWS CDK v1 has reached End-of-Support on 2023-06-01\. This package is no longer being updated, and users should migrate to AWS CDK v2\. For more information on how to migrate, see https://docs\.aws\.amazon\.com/cdk/v2/guide/migrating-v2\.html

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：743 kB，25 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>= 14\.15\.0
- 运行依赖：7 个
- peer 依赖：@aws-cdk/aws-cloudwatch 1\.204\.0，@aws-cdk/aws-ec2 1\.204\.0，@aws-cdk/aws-iam 1\.204\.0，@aws-cdk/aws-s3 1\.204\.0，@aws-cdk/aws-s3-assets 1\.204\.0，@aws-cdk/core 1\.204\.0，constructs ^3\.3\.69
- 首次发布：2020-05-05T12:38:28.689Z
- 最新版本发布：2023-06-19T21:07:07.903Z
- 近 30 天下载量：3474（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：193（近 12 个月 0 个）

## 中文简介

AWS 的 CDK 构造库: 合成

## 安装

```sh
npm install @aws-cdk/aws-synthetics
```

也可以使用：`pnpm add @aws-cdk/aws-synthetics`、`yarn add @aws-cdk/aws-synthetics`、`bun add @aws-cdk/aws-synthetics`

## README

# 亚马逊云表合成库

* * *

![End-of-Support](https://img.shields.io/badge/End--of--Support-critical.svg?style=for-the-badge)

> AWS CDK v1在2023-06-01上达到了支持结束. 此软件包不再更新,用户应该迁移到 AWS CDK v2.
> 
> 关于如何移徙的更多信息,请参见: [_移动到 AWS CDK v2_ 指南](https://docs.aws.amazon.com/cdk/v2/guide/migrating-v2.html)。 。 。 .

* * *

Amazon Cloud Watch 合成器允许您通过生成来监视您的应用程序 **合成** 堵车 交通是由一个 **金丝雀**:一个按时间表运行的可配置的脚本. 您配置了金丝雀脚本以遵循相同的路径, 并进行与用户相同的动作, 这使得您可以不断验证您的用户体验, 即使您的应用程序没有任何流量 .

## 加那利语Name

为了说明如何使用金丝雀,假设您的应用定义了以下终点:

```console
% curl "https://api.example.com/user/books/topbook/"
The Hitchhikers Guide to the Galaxy

```

下面的代码定义了一只金丝雀,它会击中 `books/topbook` 每5分钟结束点 :

```ts
const canary = new synthetics.Canary(this, 'MyCanary', {
  schedule: synthetics.Schedule.rate(Duration.minutes(5)),
  test: synthetics.Test.custom({
    code: synthetics.Code.fromAsset(path.join(__dirname, 'canary')),
    handler: 'index.handler',
  }),
  runtime: synthetics.Runtime.SYNTHETICS_NODEJS_PUPPETEER_3_1,
  environmentVariables: {
    stage: 'prod',
  },
});
```

以下是一个实例: `index.js` 用于导出 `handler` 函数 :

```js
const synthetics = require('Synthetics');
const log = require('SyntheticsLogger');

const pageLoadBlueprint = async function () {
  // Configure the stage of the API using environment variables
  const url = `https://api.example.com/${process.env.stage}/user/books/topbook/`;

  const page = await synthetics.getPage();
  const response = await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 });
  // Wait for page to render. Increase or decrease wait time based on endpoint being monitored.
  await page.waitFor(15000);
  // This will take a screenshot that will be included in test output artifacts.
  await synthetics.takeScreenshot('loaded', 'loaded');
  const pageTitle = await page.title();
  log.info('Page title: ' + pageTitle);
  if (response.status() !== 200) {
    throw 'Failed to load page!';
  }
};

exports.handler = async () => {
  return await pageLoadBlueprint();
};
```

> **说明:** 职能 **必须** 调用 `handler`。 。 。 .

金丝雀会自动生产出"云表"Dashboard:

![UI Screenshot](https://npmcn.com/package/%40aws-cdk/aws-synthetics/images/ui-screenshot.png)

加那利代码将在合成人代表您创建的羊肉达函数中被执行. Lambda 函数包括一个自定义 [运行时间](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries_Library.html) 由合成人提供。 所提供的运行时间包括各种工具,例如: [傀儡](https://www.npmjs.com/package/puppeteer-core) (对于以节点为基础的一个)和铬.

为了更多地了解合成能力,请检查 [文档](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries.html)。 。 。 .

### 加那利计划

您可以指定一个金丝雀运行的时间表 提供一个 [`Schedule`](https://docs.aws.amazon.com/cdk/api/latest/docs/@aws-cdk_aws-synthetics.Schedule.html) 对象 `schedule` 属性.

配置最多60分钟的运行速度 `Schedule.rate`数字 :

```ts
const schedule = synthetics.Schedule.rate(Duration.minutes(5)); // Runs every 5 minutes.
```

您也可以指定 [cron 表达式](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries_cron.html) 与 `Schedule.cron`数字 :

```ts
const schedule = synthetics.Schedule.cron({
  hour: '0,8,16', // Run at 12am, 8am, 4pm UTC every day
});
```

如果你想让金丝雀在部署时运行一次 你可以使用 `Schedule.once()`。 。 。 .

### 配置 Canary 脚本

要配置金丝雀执行的脚本,请使用 `test` 属性。 这个 `test` 属性接受 a `Test` 可初始化的示例 `Test` 类静态方法. 目前,唯一采用的方法是 `Test.custom()`,它允许你带来自己的代码。 将来会增加其他方法. `Test.custom()` 接受 `code` 财务报告和审定财务报表 `handler` 属性 - 两者都被合成器要求为您创建羊肉达函数.

这个 `synthetics.Code` 班级会暴露静态方法 来捆绑您的密码文物:

-   `code.fromInline(code)` - 指定内在脚本.
-   `code.fromAsset(path)` - 指定 .zip 文件或本地文件系统中的目录,在部署时将其拉链并上传到 S3 。 关于目录结构,见上文注释.
-   `code.fromBucket(bucket, key[, objectVersion])` - 指定包含您运行时代码的.zip文件的 S3 对象 。 关于目录结构,见上文注释.

使用 `Code` 类静态初始器 :

```ts
// To supply the code inline:
new synthetics.Canary(this, 'Inline Canary', {
  test: synthetics.Test.custom({
    code: synthetics.Code.fromInline('/* Synthetics handler code */'),
    handler: 'index.handler', // must be 'index.handler'
  }),
  runtime: synthetics.Runtime.SYNTHETICS_NODEJS_PUPPETEER_3_4,
});

// To supply the code from your local filesystem:
new synthetics.Canary(this, 'Asset Canary', {
  test: synthetics.Test.custom({
    code: synthetics.Code.fromAsset(path.join(__dirname, 'canary')),
    handler: 'index.handler', // must end with '.handler'
  }),
  runtime: synthetics.Runtime.SYNTHETICS_NODEJS_PUPPETEER_3_4,
});

// To supply the code from a S3 bucket:
import * as s3 from '@aws-cdk/aws-s3';
const bucket = new s3.Bucket(this, 'Code Bucket');
new synthetics.Canary(this, 'Bucket Canary', {
  test: synthetics.Test.custom({
    code: synthetics.Code.fromBucket(bucket, 'canary.zip'),
    handler: 'index.handler', // must end with '.handler'
  }),
  runtime: synthetics.Runtime.SYNTHETICS_NODEJS_PUPPETEER_3_4,
});
```

> **说明:** 合成器有指定用于金丝雀的文件夹结构. 对于通过下列方式提供的节点脚本: `code.fromAsset()` 或者说 `code.fromBucket()`,金丝雀资源需要以下文件夹结构:
> 
> ```plaintext
> canary/
> ├── nodejs/
>    ├── node_modules/
>         ├── <filename>.js
> ```
> 
> 对于通过 Python 脚本提供 `code.fromAsset()` 或者说 `code.fromBucket()`,金丝雀资源需要以下文件夹结构:
> 
> ```plaintext
> canary/
> ├── python/
>     ├── <filename>.py
> ```
> 
> 见合成 [文档](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries_WritingCanary.html)。 。 。 .

### 在VPC上开金丝雀

您可以指定什么 [VPC 一个金丝雀在](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries_VPC.html)。 。 。 . 这可以使监测服务成为具体的《维也纳公约》的一部分。 要在VPC内放置金丝雀,您可以指定 `vpc` 有理想财产 `VPC` 把金丝雀放进去. 这将自动附加相应的IAM权限,附入VPC. 这将创建一个安全小组,并附加到VPC的默认子网上,除非通过 `vpcSubnets` 财务报告和审定财务报表 `securityGroups`。 。 。 .

```ts
import * as ec2 from '@aws-cdk/aws-ec2';

declare const vpc: ec2.IVpc;
new synthetics.Canary(this, 'Vpc Canary', {
  test: synthetics.Test.custom({
    code: synthetics.Code.fromAsset(path.join(__dirname, 'canary')),
    handler: 'index.handler',
  }),
  runtime: synthetics.Runtime.SYNTHETICS_NODEJS_PUPPETEER_3_4,
  vpc,
});
```

> **说明:** 默认情况下,Synthetics运行时间需要访问S3和Cloud Watch API,在没有启用互联网接入的私人子网(如被隔离的子网)中会失败.
> 
> 确保加那利号安装在具有互联网连接的VPC或与S3和Cloud Watch的VPC端点进行启用和配置.
> 
> 见 [合成 VPC 文件](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries_VPC.html)。 。 。 .

### 警报

您可以在金丝雀上配置 Cloud Watch 提醒 。 度量衡由Cloud Watch自动发布,以下API可以访问:

-   `canary.metricSuccessPercent()` - 成功金丝雀在一定时间内运行的百分比
-   `canary.metricDuration()` 每只金丝雀运行需要多少时间,几秒钟.
-   `canary.metricFailed()` - 失败的金丝雀数量在某一时间运行

创建一个跟踪金丝雀度量的提醒 :

```ts
import * as cloudwatch from '@aws-cdk/aws-cloudwatch';

declare const canary: synthetics.Canary;
new cloudwatch.Alarm(this, 'CanaryAlarm', {
  metric: canary.metricSuccessPercent(),
  evaluationPeriods: 2,
  threshold: 90,
  comparisonOperator: cloudwatch.ComparisonOperator.LESS_THAN_THRESHOLD,
});
```

## 常见问题

### @aws-cdk/aws-synthetics 是什么？

AWS 的 CDK 构造库: 合成注意：该包已被作者标记为弃用——AWS CDK v1 has reached End-of-Support on 2023-06-01\. This package is no longer being updated, and users should migrate to AWS CDK v2\. For more information on how to migrate, see https://docs\.aws\.amazon\.com/cdk/v2/guide/migrating-v2\.html

### 如何安装 @aws-cdk/aws-synthetics？

在项目目录运行 npm install @aws-cdk/aws-synthetics，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@aws-cdk/aws-cloudwatch（1\.204\.0）、@aws-cdk/aws-ec2（1\.204\.0）、@aws-cdk/aws-iam（1\.204\.0）、@aws-cdk/aws-s3（1\.204\.0）、@aws-cdk/aws-s3-assets（1\.204\.0）、@aws-cdk/core（1\.204\.0）、constructs（^3\.3\.69）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @aws-cdk/aws-synthetics 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @aws-cdk/aws-synthetics 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @aws-cdk/aws-synthetics 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>= 14\.15\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @aws-cdk/aws-synthetics 可以商用吗？

@aws-cdk/aws-synthetics 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @aws-cdk/aws-synthetics 的下载量有多少？

根据 npm 官方下载统计，@aws-cdk/aws-synthetics 在 2026/10/08 – 2026/11/06 这 30 天内被下载 3,474 次，日均约 116 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @aws-cdk/aws-synthetics 还在维护吗？

最新版本 1\.204\.0 发布于 2023/06/20（3 年前）；至今共发布 193 个版本，其中过去 12 个月发布了 0 个；首次发布于 2020/05/05。作者已将其标记为弃用，新项目建议寻找替代方案。