将 Amazon AppSync API a 与 Amazon CDK - Amazon AppSync
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

将 Amazon AppSync API a 与 Amazon CDK

提示

在使用之前CDK,我们建议您查看CDK的官方文档以及 Amazon AppSyncCDK参考文献。

我们还建议确保您的Amazon CLINPM安装在您的系统上正常运行。

在本节中,我们将创建一个可以在 DynamoDB 表中添加和提取项目的简单CDK应用程序。这是一个快速入门示例,使用了 “设计架构”、“附加数据源” 和 “配置解析器” () JavaScript 部分中的一些代码。

设置CDK项目

警告

根据您的环境,这些步骤可能不完全准确。我们假设您的系统已安装必要的实用程序、与 Amazon 服务接口的方法以及适当的配置。

第一步是安装 Amazon CDK. 在你的CLI,你可以输入以下命令:

npm install -g aws-cdk

接下来,您需要创建一个项目目录,然后导航到该目录。用于创建和导航到目录的一组示例命令是:

mkdir example-cdk-app cd example-cdk-app

接下来,您需要创建一个应用程序。我们的服务主要使用 TypeScript. 在您的项目目录中,输入以下命令:

cdk init app --language typescript

执行此操作时,将安装一个CDK应用程序及其初始化文件:

Terminal output showing Git repository initialization and npm install completion.

您的项目结构可能如下所示:

Project directory structure showing folders and files for an example CDK app.

您会注意到我们具有几个重要目录:

  • bin:初始 bin 文件将创建应用程序。我们在本指南中不会对其进行修改。

  • lib:lib 目录包含您的堆栈文件。您可以将堆栈文件视为单独的执行单元。构造将位于我们的堆栈文件中。基本上,这些是部署应用程序 Amazon CloudFormation 时将启动的服务的资源。这是我们完成大部分编码的位置。

  • node_modules:此目录由您使用该npm命令创建NPM并包含您安装的所有软件包依赖项。

我们的初始堆栈文件可能包含如下内容:

import * as cdk from 'aws-cdk-lib'; import { Construct } from 'constructs'; // import * as sqs from 'aws-cdk-lib/aws-sqs'; export class ExampleCdkAppStack extends cdk.Stack { constructor(scope: Construct, id: string, props?: cdk.StackProps) { super(scope, id, props); // The code that defines your stack goes here // example resource // const queue = new sqs.Queue(this, 'ExampleCdkAppQueue', { // visibilityTimeout: cdk.Duration.seconds(300) // }); } }

这是在我们的应用程序中创建堆栈的样板代码。该示例中的大部分代码都位于该类的范围内。

要验证您的堆栈文件是否位于应用程序的目录中,请在终端中运行以下命令:

cdk ls

应该会显示您的堆栈列表。如果没有显示,您可能需要再次执行这些步骤,或者查看官方文档以获得帮助。

如果要在部署之前构建代码更改,您始终可以在终端中运行以下命令:

npm run build

要在部署之前查看更改,请运行以下命令:

cdk diff

在将代码添加到堆栈文件之前,我们将执行引导。Bootstrapp使我们能够在应用程序部署CDK之前为预置资源。可以在此处找到有关该过程的更多信息。要创建引导,请运行以下命令:

cdk bootstrap aws://ACCOUNT-NUMBER/REGION
提示

此步骤需要您的账户IAM拥有多项权限。如果您没有这些权限,将拒绝您的引导。如果发生这种情况,您可能必须删除引导导致的不完整资源,例如,引导生成的 S3 存储桶。

引导将启动多个资源。最终消息将如下所示:

Terminal output showing successful bootstrapping of an Amazon environment.

该操作对每个账户的每个区域执行一次,因此,您无需经常这样做。引导程序的主要资源是 Amazon CloudFormation 堆栈和 Amazon S3 存储桶。

Amazon S3 存储桶用于存储文件和IAM角色,这些文件和角色授予执行部署所需的权限。所需的资源是在一个名为引导 Amazon CloudFormation 堆栈的堆栈中定义的,该堆栈通常被命名为CDKToolkit。与任何 Amazon CloudFormation 堆栈一样,它在部署后会显示在 Amazon CloudFormation 控制台中:

CDKToolkit stack with CREATE_COMPLETE status in Amazon CloudFormation console.

存储桶也是如此:

S3 bucket details showing name, region, access settings, and creation date.

要在堆栈文件中导入所需的服务,我们可以使用以下命令:

npm install aws-cdk-lib # V2 command
提示

如果您在使用 V2 时遇到问题,您可以使用 V1 命令安装各个库:

npm install @aws-cdk/aws-appsync @aws-cdk/aws-dynamodb

我们不建议这样做,因为 V1 已被弃用。

实现CDK项目-架构

我们现在可以开始实施代码了。首先,我们必须创建架构。您只需在应用程序中创建一个 .graphql 文件即可:

mkdir schema touch schema.graphql

在我们的示例中,我们包含一个名为 schema 的顶级目录,其中包含 schema.graphql

File structure showing a schema folder containing schema.graphql file.

在我们的架构中,让我们包含一个简单的示例:

input CreatePostInput { title: String content: String } type Post { id: ID! title: String content: String } type Mutation { createPost(input: CreatePostInput!): Post } type Query { getPost: [Post] }

回到我们的堆栈文件,我们需要确保定义了以下 import 指令:

import * as cdk from 'aws-cdk-lib'; import * as appsync from 'aws-cdk-lib/aws-appsync'; import * as dynamodb from 'aws-cdk-lib/aws-dynamodb'; import { Construct } from 'constructs';

在类中,我们将添加代码来制作我们的 GraphQL API 并将其连接到我们的schema.graphql文件:

export class ExampleCdkAppStack extends cdk.Stack { constructor(scope: Construct, id: string, props?: cdk.StackProps) { super(scope, id, props); // makes a GraphQL API const api = new appsync.GraphqlApi(this, 'post-apis', { name: 'api-to-process-posts', schema: appsync.SchemaFile.fromAsset('schema/schema.graphql'), }); } }

我们还将添加一些代码来打印出 GraphQL URL、API密钥和区域:

export class ExampleCdkAppStack extends cdk.Stack { constructor(scope: Construct, id: string, props?: cdk.StackProps) { super(scope, id, props); // Makes a GraphQL API construct const api = new appsync.GraphqlApi(this, 'post-apis', { name: 'api-to-process-posts', schema: appsync.SchemaFile.fromAsset('schema/schema.graphql'), }); // Prints out URL new cdk.CfnOutput(this, "GraphQLAPIURL", { value: api.graphqlUrl }); // Prints out the AppSync GraphQL API key to the terminal new cdk.CfnOutput(this, "GraphQLAPIKey", { value: api.apiKey || '' }); // Prints out the stack region to the terminal new cdk.CfnOutput(this, "Stack Region", { value: this.region }); } }

此时,再次部署我们的应用程序:

cdk deploy

结果如下所示:

Deployment output showing ExampleCdkAppStack details, including GraphQL API URL and stack region.

看来我们的示例成功了,但让我们检查一下 Amazon AppSync 控制台以确认:

GraphQL interface showing successful API request with response data displayed.

看来我们的API已经创建了。现在,我们将检查附加到以下内容的架构API:

GraphQL schema defining CreatePostInput, Post type, Mutation, and Query operations.

这似乎与我们的架构代码匹配,因此,它是成功的。从元数据角度确认这一点的另一种方法是查看 Amazon CloudFormation 堆栈:

Amazon CloudFormation stack showing ExampleCdkAppStack update complete and CDKToolkit creation complete.

当我们部署CDK应用程序时,它会启动诸如引导程序之类的资源。 Amazon CloudFormation 我们的应用程序中的每个堆栈都与一个堆 Amazon CloudFormation 栈以 1:1 的比分映射。如果您回到堆栈代码,就会发现堆栈名称是从类名称 ExampleCdkAppStack 中获取的。你可以看到它创建的资源,这些资源也符合我们的 GraphQL API 结构中的命名约定:

Expanded view of post-apis resource showing Schema, DefaultApiKey, and CDKMetadata.

实施CDK项目-数据源

接下来,我们需要添加数据来源。我们的示例使用 DynamoDB 表。在堆栈类中,我们添加一些代码以创建新的表:

export class ExampleCdkAppStack extends cdk.Stack { constructor(scope: Construct, id: string, props?: cdk.StackProps) { super(scope, id, props); // Makes a GraphQL API construct const api = new appsync.GraphqlApi(this, 'post-apis', { name: 'api-to-process-posts', schema: appsync.SchemaFile.fromAsset('schema/schema.graphql'), }); //creates a DDB table const add_ddb_table = new dynamodb.Table(this, 'posts-table', { partitionKey: { name: 'id', type: dynamodb.AttributeType.STRING, }, }); // Prints out URL new cdk.CfnOutput(this, "GraphQLAPIURL", { value: api.graphqlUrl }); // Prints out the AppSync GraphQL API key to the terminal new cdk.CfnOutput(this, "GraphQLAPIKey", { value: api.apiKey || '' }); // Prints out the stack region to the terminal new cdk.CfnOutput(this, "Stack Region", { value: this.region }); } }

此时,让我们再次部署:

cdk deploy

我们应该检查 DynamoDB 控制台是否有新的表:

DynamoDB console showing ExampleCdkAppStack-poststable as Active with Provisioned capacity.

我们的堆栈名称是正确的,并且表名称与代码匹配。如果我们再次检查 Amazon CloudFormation 堆栈,我们现在将看到新表:

Expanded view of a logical ID in Amazon CloudFormation showing post-apis, posts-table, and CDKMetadata.

实施CDK项目-Resolver

该示例将使用两个解析器:一个用于查询表,另一个用于在表中添加数据。由于我们使用管道解析器,因此,我们需要声明两个管道解析器,在每个解析器中具有一个函数。在查询中,我们添加以下代码:

export class ExampleCdkAppStack extends cdk.Stack { constructor(scope: Construct, id: string, props?: cdk.StackProps) { super(scope, id, props); // Makes a GraphQL API construct const api = new appsync.GraphqlApi(this, 'post-apis', { name: 'api-to-process-posts', schema: appsync.SchemaFile.fromAsset('schema/schema.graphql'), }); //creates a DDB table const add_ddb_table = new dynamodb.Table(this, 'posts-table', { partitionKey: { name: 'id', type: dynamodb.AttributeType.STRING, }, }); // Creates a function for query const add_func = new appsync.AppsyncFunction(this, 'func-get-post', { name: 'get_posts_func_1', api, dataSource: api.addDynamoDbDataSource('table-for-posts', add_ddb_table), code: appsync.Code.fromInline(` export function request(ctx) { return { operation: 'Scan' }; } export function response(ctx) { return ctx.result.items; } `), runtime: appsync.FunctionRuntime.JS_1_0_0, }); // Creates a function for mutation const add_func_2 = new appsync.AppsyncFunction(this, 'func-add-post', { name: 'add_posts_func_1', api, dataSource: api.addDynamoDbDataSource('table-for-posts-2', add_ddb_table), code: appsync.Code.fromInline(` export function request(ctx) { return { operation: 'PutItem', key: util.dynamodb.toMapValues({id: util.autoId()}), attributeValues: util.dynamodb.toMapValues(ctx.args.input), }; } export function response(ctx) { return ctx.result; } `), runtime: appsync.FunctionRuntime.JS_1_0_0, }); // Adds a pipeline resolver with the get function new appsync.Resolver(this, 'pipeline-resolver-get-posts', { api, typeName: 'Query', fieldName: 'getPost', code: appsync.Code.fromInline(` export function request(ctx) { return {}; } export function response(ctx) { return ctx.prev.result; } `), runtime: appsync.FunctionRuntime.JS_1_0_0, pipelineConfig: [add_func], }); // Adds a pipeline resolver with the create function new appsync.Resolver(this, 'pipeline-resolver-create-posts', { api, typeName: 'Mutation', fieldName: 'createPost', code: appsync.Code.fromInline(` export function request(ctx) { return {}; } export function response(ctx) { return ctx.prev.result; } `), runtime: appsync.FunctionRuntime.JS_1_0_0, pipelineConfig: [add_func_2], }); // Prints out URL new cdk.CfnOutput(this, "GraphQLAPIURL", { value: api.graphqlUrl }); // Prints out the AppSync GraphQL API key to the terminal new cdk.CfnOutput(this, "GraphQLAPIKey", { value: api.apiKey || '' }); // Prints out the stack region to the terminal new cdk.CfnOutput(this, "Stack Region", { value: this.region }); } }

在该代码片段中,我们添加一个名为 pipeline-resolver-create-posts 的管道解析器,并将一个名为 func-add-post 的函数附加到该解析器。这是将 Posts 添加到表中的代码。另一个管道解析器命名为 pipeline-resolver-get-posts,并具有一个名为 func-get-post 的函数,该函数检索添加到表中的 Posts

我们将部署它以将其添加到 Amazon AppSync 服务中:

cdk deploy

让我们检查一下 Amazon AppSync 控制台,看看它们是否连接到我们的 GraphQLAPI:

GraphQL API schema showing mutation and query fields with Pipeline resolvers.

看来是正确的。在代码中,这两个解析器都连接到我们制作的 G API raphQL(由api解析器和函数中都存在的 props 值表示)。在 GraphQL 中API,我们附加解析器的字段也在 props 中指定(由每个解析器中的typenamefieldname道具定义)。

让我们看看解析器内容是否正确,从 pipeline-resolver-get-posts 开始:

Code snippet showing request and response functions in a resolver, with an arrow pointing to them.

之前和之后处理程序与 code 属性值匹配。我们还可以看到一个名为 add_posts_func_1 的函数,它与我们在解析器中附加的函数的名称匹配。

我们看一下该函数的代码内容:

Function code showing request and response methods for a PutItem operation.

这与 add_posts_func_1 函数的 code 属性匹配。已成功上传我们的查询,因此,让我们检查一下该查询:

Resolver code with request and response functions, and a get_posts_func_1 function listed below.

这些也与代码匹配。如果我们看一下 get_posts_func_1

Code snippet showing two exported functions: request returning 'Scan' operation and response returning items.

一切似乎准备就绪。要从元数据角度确认这一点,我们可以再次在 Amazon CloudFormation 中检查堆栈:

List of logical IDs for Amazon resources including API, table, functions, and pipelines.

现在,我们需要执行一些请求以测试该代码。

实施CDK项目-请求

为了在 Amazon AppSync 控制台中测试我们的应用程序,我们做了一个查询和一个变更:

GraphQL code snippet showing a query to get post details and a mutation to create a post.

MyMutation 包含具有 createPost1970-01-01T12:30:00.000Z 参数的 first post 操作。它返回我们传入的 datetitle 以及自动生成的 id 值。运行该变更将产生以下结果:

{ "data": { "createPost": { "date": "1970-01-01T12:30:00.000Z", "id": "4dc1c2dd-0aa3-4055-9eca-7c140062ada2", "title": "first post" } } }

如果快速检查 DynamoDB 表,我们可以在扫描时在该表中看到我们的条目:

DynamoDB table entry showing id, date, and title fields for a single item.

回到 Amazon AppSync 控制台,如果我们运行查询来检索这个Post,我们会得到以下结果:

{ "data": { "getPost": [ { "id": "9f62c4dd-49d5-48d5-b835-143284c72fe0", "date": "1970-01-01T12:30:00.000Z", "title": "first post" } ] } }