# @cdklabs/cdk-appflow 中文文档

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

版本：0\.2\.5
npm 元数据更新时间：2025-10-11T19:16:57.386Z
中文译文更新时间：2026-11-09T08:52:23.103Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：2.3 MB，299 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>= 18\.12\.0
- 运行依赖：0 个
- peer 依赖：@aws-cdk/aws-glue-alpha ^2\.211\.0-alpha\.0，@aws-cdk/aws-redshift-alpha ^2\.211\.0-alpha\.0，aws-cdk-lib ^2\.211\.0，constructs ^10\.0\.5
- 首次发布：2023-06-20T10:52:11.290Z
- 最新版本发布：2025-10-11T19:16:56.935Z
- 近 30 天下载量：3281（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：56（近 12 个月 0 个）

## 中文简介

暂无中文简介

## 安装

```sh
npm install @cdklabs/cdk-appflow
```

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

## README

# 亚马逊 AppFlow 构造库

* * *

![Experimental](https://img.shields.io/badge/experimental-important.svg?style=for-the-badge)

> **实验:** 这个建筑库是实验性的,正在积极发展之中. 它在将来的任何版本中都会受到非后向相容性的修改或去除. 这些限制不受《公约》的约束 [语义版本](https://semver.org/) 模型和 断开更改将在发布注释中宣布。 这意味着当你可以使用它们, 您可能需要在升级到此软件包的更新版本时更新源代码.

* * *

## 导言

Amazon AppFlow是一种服务,它能够创建各种SaaS应用程序和AWS服务之间的有管理的双向数据传输集成.

更多信息,请参见 [亚马逊 AppFlow 用户指南](https://docs.aws.amazon.com/appflow/latest/userguide/what-is-appflow.html)。 。 。 .

## 支持的应用程序

该库为以下应用程序和服务提供L2构件:

-   Amazon RDS 用于 PostgreSQL (目的地)
-   阿萨纳(来源)
-   事件桥(目的地)
-   GitHub (来源)
-   谷歌广告( 来源)
-   谷歌分析4(来源)
-   谷歌大查询(出自)
-   枢纽点(来源、目的地)
-   Mailchimp (来源)
-   市场(来源)
-   微软动态 365 (来源)
-   微软SharePoint在线(来源)
-   红移( 目的地)
-   S3(来源、目的地)
-   销售力(来源、目的地)
-   销售力量营销云(来源)
-   SAP OData(来源、目的地)
-   现在服务(来源)
-   黑 (来源)
-   雪花 (目的地)
-   Zendesk (来源)

## 示例

```ts
import { SecretValue } from 'aws-cdk-lib';
import { Bucket } from 'aws-cdk-lib/aws-s3';
import { ISecret } from 'aws-cdk-lib/aws-secretsmanager';
import {
  ISource,
  IDestination,
  Filter,
  FilterCondition,
  Mapping,
  OnDemandFlow,
  S3Destination,
  SalesforceConnectorProfile,
  SalesforceSource,
  Transform,
  Validation,
  ValidationAction,
  ValidationCondition,
} from '@cdklabs/cdk-appflow';

declare const clientSecret: ISecret;
declare const accessToken: SecretValue;
declare const refreshToken: SecretValue;
declare const instanceUrl: string;

const profile = new SalesforceConnectorProfile(this, 'MyConnectorProfile', {
  oAuth: {
    accessToken: accessToken,
    flow: {
      refreshTokenGrant: {
        refreshToken: refreshToken,
        client: clientSecret,
      },
    },
  },
  instanceUrl: instanceUrl,
  isSandbox: false,
});

const source = new SalesforceSource({
  profile: profile,
  object: 'Account',
});

const bucket = new Bucket(this, 'DestinationBucket');

const destination = new S3Destination({
  location: { bucket },
});

new OnDemandFlow(this, 'SfAccountToS3', {
  source: source,
  destination: destination,
  mappings: [Mapping.mapAll()],
  transforms: [
    Transform.mask({ name: 'Name' }, '*'),
  ],
  validations: [
    Validation.when(ValidationCondition.isNull('Name'), ValidationAction.ignoreRecord()),
  ],
  filters: [
    Filter.when(FilterCondition.timestampLessThanEquals({ name: 'LastModifiedDate', dataType: 'datetime' }, new Date(Date.parse('2022-02-02')))),
  ],
});

```

# 概念

亚马逊AppFlow引入了几个概念,这些概念将建立和管理数据集成的技术原理抽象出.

一个 `Application` saaS 数据集成组件可以是 _来源_ 或一个 _目标_ 为亚马逊AppFlow。 一个源是一个应用程序,Amazon AppFlow将从中检索数据,而一个目的地是一个应用程序,Amazon AppFlow将发送数据.

A 类 `Flow` 是Amazon AppFlow在源和去向之间的整合.

A 类 `ConnectorProfile` 是Amazon AppFlow在认证/授权上的抽象化,有特定的SaaS应用程序. 每个 SaaS 申请权限 `ConnectorProfile` 将确定连接器配置文件是作为源还是作为目的支持应用程序(请查看某一特定应用程序是否作为源或目的支持在 [文件](https://docs.aws.amazon.com/appflow/latest/userguide/app-specific.html)) (中文(简体) ).

## 流动类型

图书馆引入了三种不同的流量类型:

-   `OnDemandFlow` - 代表一种流动的构筑物,这种流动在方案上可以通过使用一种流动来触发 [启动 Flow API 呼叫](https://docs.aws.amazon.com/appflow/1.0/APIReference/API_StartFlow.html)。 。 。 .
    
-   `OnEventFlow` - 代表由向AppFlow发布的SaaS应用程序事件所触发的流的构造。 在写作时,只有"销售力量"来源能够发布AppFlow流量能消耗的事件.
    
-   `OnScheduleFlow` - 代表流出于 [`Schedule`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_events.Schedule.html)
    

## 任务

任务是可以在实地采取的步骤。 任务构成此库中命名的更高级别对象 `Operations`确定了四项行动:

-   变形 - 1-1 在源字段上变形, 如切换或遮掩
    
-   绘图 -- -- 1-1或从源地到目的地地的多对一操作
    
-   过滤器 - 在特定条件下限制源数据的操作
    
-   验证 - 以每笔记录级别工作且可能具有记录级别后果(即降下记录)或全局性后果(结束流量)的操作.
    

每道流会像下面的例子一样,将专用属性暴露于每个操作类型:

```ts
import {
  Filter,
  FilterCondition,
  IDestination,
  ISource,
  Mapping,
  OnDemandFlow,
  S3Destination,
  SalesforceConnectorProfile,
  SalesforceSource,
  Transform,
  Validation,
  ValidationAction,
  ValidationCondition,
} from '@cdklabs/cdk-appflow';

declare const stack: Stack;
declare const source: ISource;
declare const destination: IDestination;

const flow = new OnDemandFlow(stack, 'OnDemandFlow', {
  source: source,
  destination: destination,
  transforms: [
    Transform.mask({ name: 'Name' }, '*'),
  ],
  mappings: [
    Mapping.map({ name: 'Name', dataType: 'String' }, { name: 'Name', dataType: 'string' }),
  ],
  filters: [
    Filter.when(FilterCondition.timestampLessThanEquals({ name: 'LastModifiedDate', dataType: 'datetime' }, new Date(Date.parse('2022-02-02')))),
  ],
  validations: [
    Validation.when(ValidationCondition.isNull('Name'), ValidationAction.ignoreRecord()),
  ]  
});
```

## 监测

### 计量

每一流量都允许通过这些方法获取衡量标准:

-   `metricFlowExecutionsStarted`
-   `metricFlowExecutionsFailed`
-   `metricFlowExecutionsSucceeded`
-   `metricFlowExecutionTime`
-   `metricFlowExecutionRecordsProcessed`

关于AppFlow 度量衡的详细信息参见: [文件](https://docs.aws.amazon.com/appflow/latest/userguide/monitoring-cloudwatch.html)。 。 。 .

如以下例子所示,云表警报可以使用:

```ts
import { IFlow } from '@cdklabs/cdk-appflow';

declare const flow: IFlow;
declare const stack: Stack;

const metric = flow.metricFlowExecutionsStarted();

metric.createAlarm(stack, "FlowExecutionsStartedAlarm", {
  threshold: 1000,
  evaluationPeriods: 2
});
```

### 事件包通知

每个流会发布事件到默认的事件Bridge总线:

-   `onRunStarted`
-   `onRunCompleted`
-   `onDeactivated` (仅限 `OnEventFlow` 编辑 `OnScheduleFlow`(中文(简体) )
-   `onStatus` (仅限 `OnEventFlow` (中文(简体) )

这样,人们就可以使用以下例子中的通知:

```ts
import { ITopic } from 'aws-cdk-lib/aws-sns';
import { SnsTopic } from 'aws-cdk-lib/aws-events-targets';
import { IFlow } from '@cdklabs/cdk-appflow';

declare const flow: IFlow;
declare const myTopic: ITopic;

flow.onRunCompleted('OnRunCompleted', {
    target: new SnsTopic(myTopic),
});
```

# 与 CloudFormation 规格的显著区别

## `OnScheduleFlow` 财务报告和审定财务报表 `incrementalPullConfig`

在云中定义 `incrementalPullConfig` (有效给出用于跟踪最后一次拖出的时间戳的字段名称) [`SourceFlowConfig`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-appflow-flow-sourceflowconfig.html#cfn-appflow-flow-sourceflowconfig-incrementalpullconfig) 属性。 在图书馆里,这个被移到 `OnScheduleFlow` 构造者属性.

## `S3Destination` 粘贴目录

虽然在CloudFormation中,Glue Catalog的配置在流量级别上是固定的-它只有在目的地是S3时才有效. 这就是为什么库将 Glue Catalog 属性定义转换为 `S3Destination`,这反过来又需要使用懒惰来充气 `metadataCatalogConfig` 在流动中.

# 安全考虑

没错 _建议_ 接下来 [amazon AppFlow的数据保护机制](https://docs.aws.amazon.com/appflow/latest/userguide/data-protection.html)。 。 。 .

## 机密资料

Amazon AppFlow 应用程序集成使用 `ConnectionProfiles`A级 `ConnectionProfile` 要求以访问和刷新信号等形式提供敏感信息。 没错 _建议_ 此类信息被安全地存储并安全地传递给AWS CDK。 所有敏感领域都是有效的 `IResolvable` 这意味着他们可以在部署时得到解决。 那人应该跟着 [具有 " 云阵 " 证书的最佳做法](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/security-best-practices.html#creds)中,敏感字段键入为 `SecretValue` 以强调这些不应是简单的弦.

使用预定义的 AWS 保密管理器秘密存储敏感信息的例子如下:

```ts
import { Secret } from 'aws-cdk-lib/aws-secretsmanager';
import { GoogleAnalytics4ConnectorProfile } from '@cdklabs/cdk-appflow';

declare const stack: Stack;

const secret = Secret.fromSecretNameV2(stack, 'GA4Secret', 'appflow/ga4');

const profile = new GoogleAnalytics4ConnectorProfile(stack, 'GA4Connector', {
  oAuth: {
    flow: {
      refreshTokenGrant: {
        refreshToken: secret.secretValueFromJson('refreshToken'),
        clientId: secret.secretValueFromJson('clientId'),
        clientSecret: secret.secretValueFromJson('clientSecret'),
      },
    },
  },
});

```

## 管理权限的方法

这个图书馆依赖于内部 `AppFlowPermissionsManager` class 可自动推断并应用 S3 Bucket, KMS Key, 和Secrets Manager Secret 资源的适当资源政策声明. `AppFlowPermissionsManager` 将语句准确放一次给 `appflow.amazonaws.com` 无论一个资源在代码中被重复使用多少次,都为主.

### 疑惑的副问题

Amazon AppFlow是一个有账户的和区域服务。 因此,它对于混淆的副问题是不可磨灭的(例如,见A. [这里](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html)) (中文(简体) ). 不过, `AppFlowPermissionsManager` 仍在介绍 `aws:SourceAccount` 资源政策的条件 _最佳做法_。 。 。 .

## 升级和打破变化

请咨询 [更新文件](https://npmcn.com/UPGRADING.md) 供参考.

## 常见问题

### 如何安装 @cdklabs/cdk-appflow？

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

### @cdklabs/cdk-appflow 支持 TypeScript 吗？

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

### @cdklabs/cdk-appflow 支持 ESM 还是 CommonJS？

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

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

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

### @cdklabs/cdk-appflow 可以商用吗？

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

### @cdklabs/cdk-appflow 的下载量有多少？

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

### @cdklabs/cdk-appflow 还在维护吗？

最新版本 0\.2\.5 发布于 2025/10/12（1\.1 年前）；至今共发布 56 个版本，其中过去 12 个月发布了 0 个；首次发布于 2023/06/20。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。