本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 入门：在中创建你的第一个 GraphQL API AWS AppSync 您可以使用 AWS AppSync 控制台来配置和启动 GraphQL API。GraphQL APIs 通常需要三个组件： 1. **GraphQL 架构** - 您的 GraphQL 架构是 API 的蓝图。它定义您可以在执行操作时请求的类型和字段。要使用数据填充架构，您必须将数据来源连接到 GraphQL API。在该快速入门指南中，我们使用预定义的模型创建一个架构。 1. **数据来源** - 这些资源包含用于填充 GraphQL API 的数据。这可以是 DynamoDB 表、Lambda 函数等 AWS AppSync 。支持多种数据源来构建强大且可扩展的 GraphQL。 APIs数据来源链接到架构中的字段。每次对字段执行请求时，来自源的数据将填充该字段。该机制是由解析器控制的。在该快速入门指南中，我们使用预定义的模型以及架构创建一个数据来源。 1. **解析器** - 解析器负责将架构字段链接到数据来源。他们从源中检索数据，然后根据字段定义的内容返回结果。 AWS AppSync 同时支持两者 JavaScript ，还支持 VTL，用于为 GraphQL 编写解析器。 APIs在该快速入门指南中，将根据架构和数据来源自动生成解析器。我们不会在本节中深入介绍该内容。 AWS AppSync 支持创建和配置所有 GraphQL 组件。在打开控制台时，您可以使用以下方法创建您的 API： 1. 设计自定义的 GraphQL API，即通过预定义的模型生成一个 GraphQL API，然后设置新的 DynamoDB 表（数据来源）以支持该 API。 1. 使用空白架构设计 GraphQL API，没有数据来源或解析器。 1. 使用 DynamoDB 表导入数据，并生成架构的类型和字段。 1. 使用 AWS AppSync的 WebSocket 功能和 Pub/Sub 架构进行实时开发 APIs。 1. 使用现有的 GraphQL APIs （源代码 APIs）链接到合并的 API。 **注意** 我们建议在使用更高级的工具之前查看[设计架构](designing-your-schema.md#aws-appsync-designing-your-schema)一节。这些指南将解释更简单的示例，您可以在概念上使用这些示例来构建更复杂的应用程序。 AWS AppSync AWS AppSync 还支持多个非控制台选项来创建 GraphQL APIs。这些方法包括： 1. AWS Amplify 1. AWS SAM 1. CloudFormation 1. CDK 以下示例将说明如何使用预定义的模型和 DynamoDB 创建 GraphQL API 基本组件。 **Topics** + [启动架构](schema-launch-start.md) + [ # 浏览 AWS AppSync 控制台 ](console-tour.md) + [使用 GraphQL 变更将数据添加到 DynamoDB 表](add-data-with-graphql-mutation.md) + [使用 GraphQL 查询从 DynamoDB 表中检索数据](retrieve-data-with-graphql-query.md) + [补充章节](next-steps.md) # 在 AWS AppSync 控制台中启动架构 在此示例中，您将创建一个 `Todo` API，允许用户为诸如*Finish task*或*Pick up groceries*之类的日常琐事提醒创建`Todo`项目。该 API 将说明如何使用 GraphQL 操作，其中状态持久保留在 DynamoDB 表中。 从概念上讲，需要三个主要步骤以创建第一个 GraphQL API。您必须定义架构（类型和字段），将数据来源附加到字段，然后编写处理业务逻辑的解析器。不过，控制台体验改变了该顺序。我们先定义希望数据来源如何与架构交互，然后定义架构和解析器。 **创建您的 GraphQL API** 1. 登录 AWS 管理控制台 并打开[AppSync 控制台](https://console.aws.amazon.com/appsync/)。 1. 在**控制面板**中，选择**创建 API**。 1. 选择 **GraphQL** 后 APIs，选择**从头开始设计**。然后选择**下一步**。 1. 对于 **API 名称**，将预填充的名称更改为 **Todo API**，然后选择**下一步**。 **注意** 此处还提供了其他选项，但我们不会在该示例中使用这些选项。 1. 在**指定 GraphQL 资源**部分中，执行以下操作： 1. 选择**立即创建由 DynamoDB 表支持的类型**。 **注意** 这意味着，我们将创建一个新的 DynamoDB 表以附加为数据来源。 1. 在**模型名称**字段中，输入 **Todo**。 **注意** 我们的第一个要求是，定义我们的架构。该**模型名称**是类型名称，因此，您真正要做的是创建一个名为 `Todo` 的 `type`，该类型将包含在架构中： ``` type Todo {} ``` 1. 在**字段**下面，执行以下操作： 1. 创建一个名为 **id** 的字段，“类型”为 `ID`，并且“必填”设置为 `Yes`。 **注意** 这些字段将位于您的 `Todo` 类型范围内。此处的字段名称指定为 `id`，类型为 `ID!`： ``` type Todo { id: ID! } ``` AWS AppSync 支持针对不同用例的多个标量值。 1. 通过使用**添加新字段**，创建 4 个额外的字段，并将`Name`值设置为 **name**、**when**、**where** 和 **description**。它们的`Type`值为 `String`，`Array`和`Required`值设置为 `No`。它将如下所示： ![\[Model information form showing fields for a Todo model with ID, name, when, where, and description.\]](http://docs.aws.amazon.com/zh_cn/appsync/latest/devguide/images/model-information-tutorial.png) **注意** 完整的类型及其字段如下所示： ``` type Todo { id: ID! name: String when: String where: String description: String } ``` 由于我们使用该预定义的模型创建架构，因此，将根据 `create`、`delete` 和 `update` 等类型使用多个样板变更填充该架构，以帮助您轻松填充数据来源。 1. 在**配置模型表**下面，输入表名称，例如 **TodoAPITable**。将**主键**设置为 `id`。 **注意** 我们实际上是在创建一个*TodoAPITable*名为的新 DynamoDB 表，该表将作为我们的主要数据源附加到 API。我们的主键设置为以前定义的必填 `id` 字段。请注意，该新表是空白的，除了分区键以外，该表不包含任何内容。 1. 选择**下一步**。 1. 检查您的更改，然后选择**创建 API**。请稍等片刻，让 AWS AppSync服务完成您的 API 创建。 您已成功创建一个 GraphQL API 及其架构和 DynamoDB 数据来源。简要说明一下上述步骤，我们选择创建一个全新的 GraphQL API。我们定义了 API 名称，然后添加第一个类型以添加架构定义。我们定义了类型及其字段，然后选择创建不包含数据的新 DynamoDB 表，以将该数据来源附加到其中的一个字段。 # 浏览 AWS AppSync 控制台 在向 DynamoDB 表中添加数据之前，我们应该先回顾一下控制台体验的基本功能。 AWS AppSync 页面左侧的 AWS AppSync 控制台选项卡允许用户轻松导航到 AWS AppSync 提供以下内容的任何主要组件或配置选项： ![\[AWS AppSync console navigation menu showing APIs, Todo API options, and Documentation link.\]](http://docs.aws.amazon.com/zh_cn/appsync/latest/devguide/images/explorer-example-5.jpg) ## 架构设计器 选择**架构**以查看您刚刚创建的架构。如果您查看架构的内容，您会发现它已加载一些帮助程序操作以简化开发过程。在**架构**编辑器中，如果滚动查看代码，您最终会看到上一节中定义的模型： ``` type Todo { id: ID! name: String when: String where: String description: String } ``` 您的模型已成为在整个架构中使用的基本类型。我们将开始使用从该类型自动生成的变更，以将数据添加到我们的数据来源中。 以下是有关**架构**编辑器的一些其他提示和信息： 1. 代码编辑器具有代码规范检查和错误检查功能，您可以在编写自己的应用程序时使用这些功能。 1. 在控制台的右侧显示已创建的 GraphQL 类型，以及不同顶级类型（例如查询）的解析器。 1. 向架构添加新类型时（例如`type User {...}`），您可以为您 AWS AppSync 预置 DynamoDB 资源。其中包括可与您的 GraphQL 数据访问模式进行最佳匹配的适当主键、排序键和索引。如果您选择顶部的 **Create Resources (创建资源)**，并从菜单中选择这些用户定义的类型之一，即可在架构设计中选择不同字段选项。我们将在[设计架构](designing-your-schema.md#aws-appsync-designing-your-schema)一节中介绍该内容。 ### 解析器配置 在架构设计器中，**解析器**部分包含架构中的所有类型和字段。如果滚动查看字段列表，您会发现可以选择**附加**以将解析器附加到某些字段。这将打开一个代码编辑器，你可以在其中编写解析器代码。 AWS AppSync 同时支持 VTL 和 JavaScript运行时，可以在页面顶部选择**操作**，然后选择**更新**运行时来更改运行时。您还可以在页面底部创建函数，它们将按顺序运行多个操作。不过，解析器是一个高级主题，我们不会在本节中介绍该内容。 ## 数据来源 选择**数据来源**以查看您的 DynamoDB 表。通过选择`Resource`选项（如果可用），您可以查看数据来源的配置。在我们的示例中，这会显示 DynamoDB 控制台。从该控制台中，可以编辑您的数据。您也可以选择数据来源，然后选择**编辑**以直接编辑某些数据。如果需要删除数据来源，您可以选择数据来源，然后选择**删除**。最后，您可以选择**创建数据来源**，然后配置名称和类型以创建新的数据来源。请注意，此选项用于将 AWS AppSync服务链接到现有资源。在 AWS AppSync 识别资源之前，您仍需要使用相关服务在账户中创建该资源。 ## 查询 选择**查询**以查看您的查询和变更。当我们使用模型创建 GraphQL API 时， AWS AppSync 会自动生成一些辅助变更和查询以供测试。在查询编辑器中，左侧包含**资源管理器**。这是一个显示您的所有变更和查询的列表。您可以在此处单击名称值，以轻松启用要使用的操作和字段。这会使代码自动出现在编辑器的中心部分。在此处，您可以修改值以编辑变更和查询。在编辑器底部具有**查询变量**编辑器，可用于为操作的输入变量输入字段值。在编辑器顶部选择 “**运行**” 将弹出一个下拉列表来选择 query/mutation 要运行的。该运行的输出显示在页面右侧。返回到顶部的**资源管理器**部分，您可以选择一个操作（查询、变更、订阅），然后选择 **\$1** 符号以添加该特定操作的新实例。在页面顶部还包含一个下拉列表，其中包含您的查询运行的授权模式。不过，我们不会在本节中介绍该功能（有关更多信息，请参阅[安全性](security-authz.md#aws-appsync-security)）。 ## 设置 可以选择**设置**以查看 GraphQL API 的一些配置选项。在此处，您可以启用一些选项，例如日志记录、跟踪和 Web 应用程序防火墙功能。您也可以添加新的授权模式以保护您的数据，以免意外对外泄露数据。不过，这些选项是更高级的选项，不会在本节中介绍该内容。 **注意** 默认授权模式 `API_KEY` 使用 API 密钥测试应用程序。这是授予所有新创建的 Graph APIs QL 的基本授权。我们建议您在生产环境中使用不同的方法。对于本节中的示例，我们仅使用 API 密钥。有关支持的授权方法的更多信息，请参阅[安全性](security-authz.md#aws-appsync-security)。 # 在控制台中使用 GraphQL 突变向 DynamoDB 表添加数据 AWS AppSync 下一步是使用 GraphQL 变更将数据添加到空白 DynamoDB 表中。变更是 GraphQL 中的基本操作类型之一。它们是在架构中定义的，可用于处理数据来源中的数据。就 REST 而言 APIs，这些操作与`PUT`或之类的操作非常相似`POST`。 **将数据添加到您的数据来源** 1. 如果您尚未执行此操作，请登录 AWS 管理控制台 并打开[AppSync 控制台](https://console.aws.amazon.com/appsync/)。 1. 从表中选择您的 API。 1. 在左侧的选项卡中，选择**查询**。 1. 在表左侧的**资源管理器**选项卡中，您可能会看到在查询编辑器中已定义的多个变更和查询： ![\[Explorer tab showing a dropdown menu with mutation and query options like createTodo and deleteTodo.\]](http://docs.aws.amazon.com/zh_cn/appsync/latest/devguide/images/explorer-example-1.png) **注意** 该变更实际作为 `Mutation` 类型包含在您的架构中。它具有以下代码： ``` type Mutation { createTodo(input: CreateTodoInput!): Todo updateTodo(input: UpdateTodoInput!): Todo deleteTodo(input: DeleteTodoInput!): Todo } ``` 正如您看到的一样，此处的操作与查询编辑器中的操作类似。 AWS AppSync 这些都是根据我们之前定义的模型自动生成的。这个例子将使用`createTodo`变异来向我们的*TodoAPITable*表中添加条目。 1. 在 `createTodo` 变更下面展开以选择 `createTodo` 操作： ![\[Expanded createTodo mutation showing input fields like description, id, name, when, and where.\]](http://docs.aws.amazon.com/zh_cn/appsync/latest/devguide/images/explorer-example-2.png) 启用所有字段的复选框，如上图所示。 **注意** 您在此处看到的属性是变更的各种可修改元素。您的 `input` 可以被视为 `createTodo` 的参数。具有复选框的各种选项是一些字段，它们是在执行操作后在响应中返回的。 1. 在屏幕中央的代码编辑器中，您会注意到该操作显示在 `createTodo` 变更下面： ``` mutation createTodo($createtodoinput: CreateTodoInput!) { createTodo(input: $createtodoinput) { where when name id description } } ``` **注意** 为了正确解释该代码片段，我们还必须查看架构代码。声明 `mutation createTodo($createtodoinput: CreateTodoInput!){}` 是具有操作之一 (`createTodo`) 的变更。完整的变更位于架构中： ``` type Mutation { createTodo(input: CreateTodoInput!): Todo updateTodo(input: UpdateTodoInput!): Todo deleteTodo(input: DeleteTodoInput!): Todo } ``` 返回到编辑器中的变更声明，参数是一个名为 `$createtodoinput` 的对象，所需的输入类型为 `CreateTodoInput`。请注意，`CreateTodoInput`（以及变更中的所有输入）也是在架构中定义的。例如，以下是 `CreateTodoInput` 的样板代码： ``` input CreateTodoInput { name: String when: String where: String description: String } ``` 它包含我们在模型中定义的字段，即 `name`、`when`、`where` 和 `description`。 返回到编辑器代码，在 `createTodo(input: $createtodoinput) {}` 中，我们将输入声明为 `$createtodoinput`，还会在变更声明中使用它。我们这样做是因为，这允许 GraphQL 根据提供的类型验证我们的输入，并确保它们与正确的输入一起使用。 编辑器代码的最后一部分显示执行操作后在响应中返回的字段： ``` { where when name id description } ``` 在该编辑器下面的**查询变量**选项卡中，具有一个通用 `createtodoinput` 对象，它可能包含以下数据： ``` { "createtodoinput": { "name": "Hello, world!", "when": "Hello, world!", "where": "Hello, world!", "description": "Hello, world!" } } ``` **注意** 这是我们为前面提到的输入分配值的位置： ``` input CreateTodoInput { name: String when: String where: String description: String } ``` 添加我们希望放入 DynamoDB 表中的信息以更改 `createtodoinput`。在该示例中，我们希望创建一些 `Todo` 项目以作为提醒： ``` { "createtodoinput": { "name": "Shopping List", "when": "Friday", "where": "Home", "description": "I need to buy eggs" } } ``` 1. 选择编辑器顶部的**运行**。在下拉列表中选择 **createTodo**。在编辑器右侧，您应该会看到响应。它可能如下所示： ``` { "data": { "createTodo": { "where": "Home", "when": "Friday", "name": "Shopping List", "id": "abcdefgh-1234-1234-1234-abcdefghijkl", "description": "I need to buy eggs" } } } ``` 如果您导航到 DynamoDB 服务，您现在会在数据来源中看到一个包含以下信息的条目： ![\[TodoAPITable interface showing a completed scan with 1 item returned in a table format.\]](http://docs.aws.amazon.com/zh_cn/appsync/latest/devguide/images/explorer-example-3.png) 简要说明一下该操作，GraphQL 引擎解析记录，然后解析器将其插入到您的 Amazon DynamoDB 表中。同样，您可以在 DynamoDB 控制台中验证这一点。请注意，您不需要传入 `id` 值。将生成一个 `id` 并在结果中返回。这是因为，对于 DynamoDB 资源上设置的分区键，该示例在 GraphQL 解析器中使用 `autoId()` 函数。我们将在另一节中介绍如何构建解析器。记下返回的 `id` 值；您在下一节中使用该值通过 GraphQL 查询检索数据。 # 在控制台中使用 GraphQL 查询从 DynamoDB 表中检索数据 AWS AppSync 您的数据库现已包含一条记录，您将在运行查询时获得结果。查询是 GraphQL 的其他基本操作之一。它用于从数据来源中解析和检索信息。就 REST 而言 APIs，这与`GET`操作类似。GraphQL 查询的主要优点是，能够指定应用程序的确切数据要求，以使您在正确的时间获取相关的数据。 **查询您的数据来源** 1. 如果您尚未执行此操作，请登录 AWS 管理控制台 并打开[AppSync 控制台](https://console.aws.amazon.com/appsync/)。 1. 从表中选择您的 API。 1. 在左侧的选项卡中，选择**查询**。 1. 在表左侧的**资源管理器**选项卡中，在 `query` `listTodos` 下面展开 `getTodo` 操作： ![\[Expanded getTodo operation showing fields id, description, name, when, and where.\]](http://docs.aws.amazon.com/zh_cn/appsync/latest/devguide/images/explorer-example-4.png) 1. 在代码编辑器中，您应该会看到操作代码： ``` query listTodos { getTodo(id: "") { description id name when where } ``` 在 `(id:"")` 中，填写您在变更操作结果中保存的值。在我们的示例中，这是： ``` query listTodos { getTodo(id: "abcdefgh-1234-1234-1234-abcdefghijkl") { description id name when where } ``` 1. 选择**运行**，然后选择 **listTodos**。结果将显示在编辑器右侧。我们的示例如下所示： ``` { "data": { "getTodo": { "description": "I need to buy eggs", "id": "abcdefgh-1234-1234-1234-abcdefghijkl", "name": "Shopping List", "when": "Friday", "where": "Home" } } } ``` **注意** 查询仅返回您指定的字段。您可以从返回字段中删除不需要的字段，以取消选择这些字段： ``` { description id name when where } ``` 在**资源管理器**选项卡中，您也可以取消选中要删除的字段旁边的框。 1. 您还可以尝试 `listTodos` 操作，方法是重复在数据来源中创建条目的步骤，然后使用 `listTodos` 操作重复查询步骤。以下是我们添加第二个任务的示例： ``` { "createtodoinput": { "name": "Second Task", "when": "Monday", "where": "Home", "description": "I need to mow the lawn" } } ``` 在调用 `listTodos` 操作时，它返回旧条目和新条目： ``` { "data": { "listTodos": { "items": [ { "id": "abcdefgh-1234-1234-1234-abcdefghijkl", "name": "Shopping List", "when": "Friday", "where": "Home", "description": "I need to buy eggs" }, { "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "name": "Second Task", "when": "Monday", "where": "Home", "description": "I need to mow the lawn" } ] } } } ``` # 控制台的补充部分 AWS AppSync 这些部分是更多高级 AWS AppSync 主题的参考。我们建议您在执行任何其他操作之前查看*补充内容*一节。 ## 集成 在控制台选项卡中，如果您选择 API 的名称，则会显示**集成**页面： ![\[AWS AppSync sidebar menu with APIs, Todo API highlighted, and other options listed.\]](http://docs.aws.amazon.com/zh_cn/appsync/latest/devguide/images/explorer-example-6.png) 它简要说明了设置 API 的步骤，以及构建客户端应用程序的后续步骤。“**与您的应用集成**” 部分详细介绍了如何使用 Amp [AWS lify 工具链](https://aws-amplify.github.io/)，通过配置和代码生成自动将 API 与 iOS、Android 和 JavaScript 应用连接起来。Amplify 工具链为从本地工作站中构建项目提供全面支持，包括 GraphQL 预置和 CI/CD 工作流。 **客户示例**部分还列出了用于测试 end-to-end体验的示例客户端应用程序（例如 iOS JavaScript、Android）。您可以克隆并下载这些示例，配置文件包含您开始使用这些示例所需的信息（例如您的终端节点 URL）。按照 [AWS Amplify 工具链](https://aws-amplify.github.io/)页面上的说明运行您的应用程序。 ## 补充内容 + [使用以下方法设计 GraphQL APIs AWS AppSync](designing-a-graphql-api.md) - 这是使用没有数据来源或解析器的空白架构创建 GraphQL 的综合指南。