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

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

版本：2\.101\.1-alpha\.0
npm 元数据更新时间：2023-11-21T10:12:51.631Z
中文译文更新时间：2026-11-07T14:19:36.616Z
软件包许可：Apache-2\.0

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

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

弃用说明：This package has been stabilized and moved to aws-cdk-lib

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

- 包体积（解压后）：454 kB，24 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>= 14\.15\.0
- 运行依赖：0 个
- peer 依赖：aws-cdk-lib ^2\.101\.1，constructs ^10\.0\.0
- 首次发布：2021-10-13T18:38:50.760Z
- 最新版本发布：2023-10-16T21:11:37.710Z
- 近 30 天下载量：21647（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：148（近 12 个月 0 个）

## 中文简介

此模块被贬值. 所有构造现在都可以在aws-cdk-lib/aws-synthetics下使用

## 安装

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

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

## README

# 亚马逊云表合成库

* * *

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

> 此API 可能会发出警告 。 后向兼容性没有保证 .

* * *

所有构造都被移动到aws-cdk-lib/aws-synthetics.

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_4_0,
  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-alpha/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()`。 。 。 .

### 删除金丝雀上的相关资源

当您删除一个 lambda 时, 您的 AWS 账户中将隔离以下基本资源 :

-   运行您金丝雀脚本的 Lambda 函数
-   用于保存文物的S3桶
-   IAM的作用和政策
-   云表日志中的日志组 .

要更多地了解这些基本资源,见: [合成动画](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/synthetics_canaries_deletion.html)。 。 。 .

在 CCDK 中,您可以配置您的金丝雀来删除金丝雀被删除时隐藏的羊肉达函数. 这可以通过设置来提供 `cleanup: Cleanup.LAMBDA`。注意这一点 将会在引擎盖下创建自定义资源, 为您处理 lambda 删除 .

```ts
const canary = new synthetics.Canary(this, 'Canary', {
  test: synthetics.Test.custom({
    handler: 'index.handler',
    code: synthetics.Code.fromInline('/* Synthetics handler code'),
  }),
  cleanup: synthetics.Cleanup.LAMBDA,
  runtime: synthetics.Runtime.SYNTHETICS_NODEJS_PUPPETEER_4_0,
});
```

> 注意: 要正确清理删除时的金丝雀, 您仍需要手动删除其他资源 像S3桶和云表记录.

### 配置 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_4_0,
});

// 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_4_0,
});

// To supply the code from a S3 bucket:
import * as s3 from 'aws-cdk-lib/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_4_0,
});
```

> **说明:** 合成器有指定用于金丝雀的文件夹结构. 对于通过下列方式提供的节点脚本: `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-lib/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_4_0,
  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-lib/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,
});
```

### 艺术品

你可以通过一个S3桶 从金丝雀跑道储存文物。 如果你没有, 当金丝雀创建时,它会自动生成。 您可以添加 [生命周期规则](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html) 到自动生成的桶.

```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_4_0,
  artifactsBucketLifecycleRules: [{
    expiration: Duration.days(30),
  }],
});
```

## 常见问题

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

此模块被贬值\. 所有构造现在都可以在aws-cdk-lib/aws-synthetics下使用注意：该包已被作者标记为弃用——This package has been stabilized and moved to aws-cdk-lib

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

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

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

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

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

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

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

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

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

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

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

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

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

最新版本 2\.101\.1-alpha\.0 发布于 2023/10/17（3 年前）；至今共发布 148 个版本，其中过去 12 个月发布了 0 个；首次发布于 2021/10/14。作者已将其标记为弃用，新项目建议寻找替代方案。