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

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

版本：2\.59\.0-alpha\.0
npm 元数据更新时间：2023-11-21T10:13:57.529Z
中文译文更新时间：2026-11-07T13:46:24.314Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：688 kB，35 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>= 14\.15\.0
- 运行依赖：0 个
- peer 依赖：aws-cdk-lib ^2\.59\.0，constructs ^10\.0\.0
- 首次发布：2021-10-13T18:38:10.951Z
- 最新版本发布：2023-01-03T17:00:59.709Z
- 近 30 天下载量：56628（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：92（近 12 个月 0 个）

## 中文简介

AWS: AppSync 的 CDK 构造库

## 安装

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

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

## README

# AWS AppSync 构造库

* * *

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

> 本单元中更高层次的构件的API是实验性的并正在积极开发中. 在今后任何版本中,它们都须作非背向相容的修改或去除。 这些是 不适用 [语义版本](https://semver.org/) 模型和断开的更改 在发行笔记中宣布. 这意味着虽然你可能使用它们,但可能需要更新 当更新到此软件包的更新版本时,您的源代码.

* * *

这个 `@aws-cdk/aws-appsync` 软件包中包含用于灵活建筑的构造 使用 GraphQL 的 API .

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

## 示例

### 迪纳摩DB

图QL API 示例 `AWS_IAM` [授权](https://npmcn.com/package/%40aws-cdk/aws-appsync-alpha/#readme-authorization) 进入迪纳摩Db 后端数据源.

GraphQL 计划文件 `schema.graphql`数字 :

```gql
type demo {
  id: String!
  version: String!
}
type Query {
  getDemos: [ demo! ]
}
input DemoInput {
  version: String!
}
type Mutation {
  addDemo(input: DemoInput!): demo
}
```

CDK 堆栈文件 `app-stack.ts`数字 :

```ts
const api = new appsync.GraphqlApi(this, 'Api', {
  name: 'demo',
  schema: appsync.SchemaFile.fromAsset(path.join(__dirname, 'schema.graphql')),
  authorizationConfig: {
    defaultAuthorization: {
      authorizationType: appsync.AuthorizationType.IAM,
    },
  },
  xrayEnabled: true,
});

const demoTable = new dynamodb.Table(this, 'DemoTable', {
  partitionKey: {
    name: 'id',
    type: dynamodb.AttributeType.STRING,
  },
});

const demoDS = api.addDynamoDbDataSource('demoDataSource', demoTable);

// Resolver for the Query "getDemos" that scans the DynamoDb table and returns the entire list.
// Resolver Mapping Template Reference:
// https://docs.aws.amazon.com/appsync/latest/devguide/resolver-mapping-template-reference-dynamodb.html
demoDS.createResolver('QueryGetDemosResolver', {
  typeName: 'Query',
  fieldName: 'getDemos',
  requestMappingTemplate: appsync.MappingTemplate.dynamoDbScanTable(),
  responseMappingTemplate: appsync.MappingTemplate.dynamoDbResultList(),
});

// Resolver for the Mutation "addDemo" that puts the item into the DynamoDb table.
demoDS.createResolver('MutationAddDemoResolver', {
  typeName: 'Mutation',
  fieldName: 'addDemo',
  requestMappingTemplate: appsync.MappingTemplate.dynamoDbPutItem(
    appsync.PrimaryKey.partition('id').auto(),
    appsync.Values.projecting('input'),
  ),
  responseMappingTemplate: appsync.MappingTemplate.dynamoDbResultItem(),
});

//To enable DynamoDB read consistency with the `MappingTemplate`:
demoDS.createResolver('QueryGetDemosConsistentResolver', {
  typeName: 'Query',
  fieldName: 'getDemosConsistent',
  requestMappingTemplate: appsync.MappingTemplate.dynamoDbScanTable(true),
  responseMappingTemplate: appsync.MappingTemplate.dynamoDbResultList(),
});
```

### 无服务器的Aurora

AppSync 为针对Amazon Aurora执行SQL命令提供数据源 无服务器集群. 您可以使用 AppSync 解析器执行 SQL 语句 与 GraphQL 查询、 突变和订阅的 Data API 对齐.

```ts
// Create username and password secret for DB Cluster
const secret = new rds.DatabaseSecret(this, 'AuroraSecret', {
  username: 'clusteradmin',
});

// The VPC to place the cluster in
const vpc = new ec2.Vpc(this, 'AuroraVpc');

// Create the serverless cluster, provide all values needed to customise the database.
const cluster = new rds.ServerlessCluster(this, 'AuroraCluster', {
  engine: rds.DatabaseClusterEngine.AURORA_MYSQL,
  vpc,
  credentials: { username: 'clusteradmin' },
  clusterIdentifier: 'db-endpoint-test',
  defaultDatabaseName: 'demos',
});

// Build a data source for AppSync to access the database.
declare const api: appsync.GraphqlApi;
const rdsDS = api.addRdsDataSource('rds', cluster, secret, 'demos');

// Set up a resolver for an RDS query.
rdsDS.createResolver('QueryGetDemosRdsResolver', {
  typeName: 'Query',
  fieldName: 'getDemosRds',
  requestMappingTemplate: appsync.MappingTemplate.fromString(`
  {
    "version": "2018-05-29",
    "statements": [
      "SELECT * FROM demos"
    ]
  }
  `),
  responseMappingTemplate: appsync.MappingTemplate.fromString(`
    $utils.toJson($utils.rds.toJsonObject($ctx.result)[0])
  `),
});

// Set up a resolver for an RDS mutation.
rdsDS.createResolver('MutationAddDemoRdsResolver', {
  typeName: 'Mutation',
  fieldName: 'addDemoRds',
  requestMappingTemplate: appsync.MappingTemplate.fromString(`
  {
    "version": "2018-05-29",
    "statements": [
      "INSERT INTO demos VALUES (:id, :version)",
      "SELECT * WHERE id = :id"
    ],
    "variableMap": {
      ":id": $util.toJson($util.autoId()),
      ":version": $util.toJson($ctx.args.version)
    }
  }
  `),
  responseMappingTemplate: appsync.MappingTemplate.fromString(`
    $utils.toJson($utils.rds.toJsonObject($ctx.result)[1][0])
  `),
});
```

### HTTP 终点

GraphQL 计划文件 `schema.graphql`数字 :

```gql
type job {
  id: String!
  version: String!
}

input DemoInput {
  version: String!
}

type Mutation {
  callStepFunction(input: DemoInput!): job
}
```

GraphQL 请求绘图模板 `request.vtl`数字 :

```json
{
  "version": "2018-05-29",
  "method": "POST",
  "resourcePath": "/",
  "params": {
    "headers": {
      "content-type": "application/x-amz-json-1.0",
      "x-amz-target":"AWSStepFunctions.StartExecution"
    },
    "body": {
      "stateMachineArn": "<your step functions arn>",
      "input": "{ \"id\": \"$context.arguments.id\" }"
    }
  }
}
```

图QL 响应映射模板 `response.vtl`数字 :

```json
{
  "id": "${context.result.id}"
}
```

CDK 堆栈文件 `app-stack.ts`数字 :

```ts
const api = new appsync.GraphqlApi(this, 'api', {
  name: 'api',
  schema: appsync.SchemaFile.fromAsset(path.join(__dirname, 'schema.graphql')),
});

const httpDs = api.addHttpDataSource(
  'ds',
  'https://states.amazonaws.com',
  {
    name: 'httpDsWithStepF',
    description: 'from appsync to StepFunctions Workflow',
    authorizationConfig: {
      signingRegion: 'us-east-1',
      signingServiceName: 'states',
    }
  }
);

httpDs.createResolver('MutationCallStepFunctionResolver', {
  typeName: 'Mutation',
  fieldName: 'callStepFunction',
  requestMappingTemplate: appsync.MappingTemplate.fromFile('request.vtl'),
  responseMappingTemplate: appsync.MappingTemplate.fromFile('response.vtl'),
});
```

### 亚马逊 OpenSearch 服务

AppSync 已建立支持 Amazon OpenSearch Service( 继承到 Amazon) Elasticsearch Service),来自通过您的 AWS 账户提供的域. 你们可以 使用 AppSync 解析器执行 GraphQL 操作,例如查询、突变和 订阅.

```ts
import * as opensearch from 'aws-cdk-lib/aws-opensearchservice';

const user = new iam.User(this, 'User');
const domain = new opensearch.Domain(this, 'Domain', {
  version: opensearch.EngineVersion.OPENSEARCH_1_3,
  removalPolicy: RemovalPolicy.DESTROY,
  fineGrainedAccessControl: { masterUserArn: user.userArn },
  encryptionAtRest: { enabled: true },
  nodeToNodeEncryption: true,
  enforceHttps: true,
});

declare const api: appsync.GraphqlApi;
const ds = api.addOpenSearchDataSource('ds', domain);

ds.createResolver('QueryGetTestsResolver', {
  typeName: 'Query',
  fieldName: 'getTests',
  requestMappingTemplate: appsync.MappingTemplate.fromString(JSON.stringify({
    version: '2017-02-28',
    operation: 'GET',
    path: '/id/post/_search',
    params: {
      headers: {},
      queryString: {},
      body: { from: 0, size: 50 },
    },
  })),
  responseMappingTemplate: appsync.MappingTemplate.fromString(`[
    #foreach($entry in $context.result.hits.hits)
    #if( $velocityCount > 1 ) , #end
    $utils.toJson($entry.get("_source"))
    #end
  ]`),
});
```

## 自定义域名

对于很多用途,您可能想要将自定义域名与您的域名关联 图QL API. 这可以在API创建期间完成.

```ts
import * as acm from 'aws-cdk-lib/aws-certificatemanager';
import * as route53 from 'aws-cdk-lib/aws-route53';

const myDomainName = 'api.example.com';
const certificate = new acm.Certificate(this, 'cert', { domainName: myDomainName });
const schema = new appsync.SchemaFile({ filePath: 'mySchemaFile' })
const api = new appsync.GraphqlApi(this, 'api', {
  name: 'myApi',
  schema,
  domainName: {
    certificate,
    domainName: myDomainName,
  },
});

// hosted zone and route53 features
declare const hostedZoneId: string;
declare const zoneName = 'example.com';

// hosted zone for adding appsync domain
const zone = route53.HostedZone.fromHostedZoneAttributes(this, `HostedZone`, {
  hostedZoneId,
  zoneName,
});

// create a cname to the appsync domain. will map to something like xxxx.cloudfront.net
new route53.CnameRecord(this, `CnameApiRecord`, {
  recordName: 'api',
  zone,
  domainName: api.appSyncDomainName,
});
```

## 日志组

AppSync 自动创建带有名称的日志组 `/aws/appsync/apis/<graphql_api_id>` 与 日志数据集永不过期 。 如果您想要设定不同的过期期, 请使用 `logConfig.retention` 属性.

要获取 GraphQL API 的日志组 `logs.ILogGroup` 使用该 `logGroup` 财产的财产 `GraphqlApi` 构造.

```ts
import * as logs from 'aws-cdk-lib/aws-logs';

const logConfig: appsync.LogConfig = {
  retention: logs.RetentionDays.ONE_WEEK,
};

new appsync.GraphqlApi(this, 'api', {
  authorizationConfig: {},
  name: 'myApi',
  schema: appsync.SchemaFile.fromAsset(path.join(__dirname, 'myApi.graphql')),
  logConfig,
});
```

## 司马

您可以使用本地文件使用 `SchemaFile.fromAsset`

```ts
const api = new appsync.GraphqlApi(this, 'api', {
  name: 'myApi',
  schema: appsync.SchemaFile.fromAsset(path.join(__dirname, 'schema.graphl')),
});
```

### ISchema 计划

可通过实施 `ISchema` 接口。 一个例子是 `CodeFirstSchema` 提供的类别 [awscdk-appsync-utils (英语)](https://github.com/cdklabs/awscdk-appsync-utils)

## 进口

任意图形QL 堆栈外已创建的 Api 可以导入自 另一个堆入您的 CDK 应用程序。 利用 `fromXxx` 函数,您有 通过数据源和解析器 `IGraphqlApi` 接口.

```ts
declare const api: appsync.GraphqlApi;
declare const table: dynamodb.Table;
const importedApi = appsync.GraphqlApi.fromGraphqlApiAttributes(this, 'IApi', {
  graphqlApiId: api.apiId,
  graphqlApiArn: api.arn,
});
importedApi.addDynamoDbDataSource('TableDataSource', table);
```

如果你不说明 `graphqlArn` 内 `fromXxxAttributes`,CDK 将自动生成 预想数 `arn` 用于导入的 api,考虑到 `apiId`。用于创建数据 来源和解决者,a `apiId` 足够了.

## 授权

GraphQL API有多种授权类型,以适应不同的 访问使用案例。 它们是:

-   API 密钥( R)`AuthorizationType.API_KEY`(中文(简体) )
-   亚马逊·科尼托用户池(英语:Amazon Cognto Users pools (`AuthorizationType.USER_POOL`(中文(简体) )
-   打开ID 连接( O)`AuthorizationType.OPENID_CONNECT`(中文(简体) )
-   AWS 身份和访问管理`AuthorizationType.AWS_IAM`(中文(简体) )
-   AWS 兰布达( Lambda)`AuthorizationType.AWS_LAMBDA`(中文(简体) )

这些类型可以在单个API中同时使用,允许不同类型的客户端使用 访问数据。 当指定授权类型时,也可以指定相应的类型 授权模式以完成定义您的授权 。 例如, 这是一个 GraphQL API aWS蓝巴达授权.

```ts
import * as lambda from 'aws-cdk-lib/aws-lambda';
declare const authFunction: lambda.Function;

new appsync.GraphqlApi(this, 'api', {
  name: 'api',
  schema: appsync.SchemaFile.fromAsset(path.join(__dirname, 'appsync.test.graphql')),
  authorizationConfig: {
    defaultAuthorization: {
      authorizationType: appsync.AuthorizationType.LAMBDA,
      lambdaAuthorizerConfig: {
        handler: authFunction,
        // can also specify `resultsCacheTtl` and `validationRegex`.
      },
    },
  },
});
```

## 权限

使用时 `AWS_IAM` 作为IAM角色GraphQL API的授权类型 访问 API 必须使用正确的权限.

配置权限时,您可以指定特定资源仅为 无障碍 `IAM` 授权。 例如,如果只允许可变性 页:1 `IAM` 您将配置以下授权访问 .

单位 `schema.graphql`数字 :

```gql
type Mutation {
  updateExample(...): ...
    @aws_iam
}
```

单位 `IAM`数字 :

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "appsync:GraphQL"
      ],
      "Resource": [
        "arn:aws:appsync:REGION:ACCOUNT_ID:apis/GRAPHQL_ID/types/Mutation/fields/updateExample"
      ]
    }
  ]
}
```

见 [文档](https://docs.aws.amazon.com/appsync/latest/devguide/security.html#aws-iam-authorization) 更多细节.

为方便起见,CDK提供 `grant` API (英语).

使用 `grant` 函数用于更多的颗粒式授权.

```ts
const role = new iam.Role(this, 'Role', {
  assumedBy: new iam.ServicePrincipal('lambda.amazonaws.com'),
});
declare const api: appsync.GraphqlApi;

api.grant(role, appsync.IamResource.custom('types/Mutation/fields/updateExample'), 'appsync:GraphQL');
```

### 资源

为了使用 `grant` 函数,需要使用类 `IamResource`。 。 。 .

-   `IamResource.custom(...arns)` 允许自定义 ARN 并需要一个参数.
    
-   `IamResouce.ofType(type, ...fields)` 允许ARN用于类型及其字段.
    
-   `IamResource.all()` 允许所有资源.
    

### 通用权限

或者,您可以使用更通用的 `grant` 用于实现相同用途的函数.

其中包括:

-   混合(用于允许进入突变场)
-   授权查询( 用于授权访问查询字段)
-   赠款订阅(用于授权访问订阅栏)

```ts
declare const api: appsync.GraphqlApi;
declare const role: iam.Role;

// For generic types
api.grantMutation(role, 'updateExample');

// For custom types and granular design
api.grant(role, appsync.IamResource.ofType('Mutation', 'updateExample'), 'appsync:GraphQL');
```

## 管道解析器和 AppSync 函数

AppSync 函数是本地函数,可以执行某些操作到 a 后端数据源. 开发者可以组成操作(功能)并执行 以管道解析器排列.

```ts
declare const api: appsync.GraphqlApi;

const appsyncFunction = new appsync.AppsyncFunction(this, 'function', {
  name: 'appsync_function',
  api,
  dataSource: api.addNoneDataSource('none'),
  requestMappingTemplate: appsync.MappingTemplate.fromFile('request.vtl'),
  responseMappingTemplate: appsync.MappingTemplate.fromFile('response.vtl'),
});
```

AppSync 函数与管道解析器同步使用,以组成多个函数 操作.

```ts
declare const api: appsync.GraphqlApi;
declare const appsyncFunction: appsync.AppsyncFunction;

const pipelineResolver = new appsync.Resolver(this, 'pipeline', {
  api,
  dataSource: api.addNoneDataSource('none'),
  typeName: 'typeName',
  fieldName: 'fieldName',
  requestMappingTemplate: appsync.MappingTemplate.fromFile('beforeRequest.vtl'),
  pipelineConfig: [appsyncFunction],
  responseMappingTemplate: appsync.MappingTemplate.fromFile('afterResponse.vtl'),
});
```

更多了解管道解析器和 AppSync 函数 [这里](https://docs.aws.amazon.com/appsync/latest/devguide/pipeline-resolvers.html)。 。 。 .

## 常见问题

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

AWS: AppSync 的 CDK 构造库

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

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

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

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

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

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

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

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

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

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

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

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

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

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