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

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

设计你的架构

GraphQL 架构是任何 GraphQL 服务器实现的基础。每个 GraphQL API 都由单个 GraphQL 架构定义。GraphQL 类型系统描述了 GraphQL 服务器的功能,用于确定查询是否有效。服务器的类型系统称为该服务器的架构。它由一组对象类型、标量、输入类型、接口、枚举和联合组成。它定义流经 API 的数据的形状以及可以执行的操作。GraphQL 是强类型化协议,所有数据操作都将对照此架构进行验证。

Amazon AppSync允许您定义和配置 GraphQL 架构。以下部分介绍如何使用Amazon AppSync服务从头开始创建 GraphQL 架构。

创建空架构

架构文件是文本文件,通常名为 schema.graphql。Amazon AppSync 允许用户使用控制台、CLI 或 API 为其 GraphQL API 创建新的架构。

Console
  1. 登录 Amazon Web Services Management Console并打开 AppSync 控制台

    1. API 控制面板中,选择你的 GraphQL API。

    2. 在边中,选择架构

  2. 您可以通过在 “架构” 窗口中添加以下内容Amazon AppSync来配置schema.graphql文件并将其提交给:

    schema { }
  3. 选择 Save schema

    注意

    每个架构都以用于处理的schema根开头。只有添加了根查询类型之后才能进行处理。

API
  1. 通过调用 API 创建 GraphQL CreateGraphqlApiAPI 对象。

  2. 调用 StartSchemaCreation API。

CLI
  1. 如果您尚未执行此操作,请安装Amazon CLI,然后添加您的配置

  2. 通过运行create-graphql-api命令创建 GraphQL API 对象。

    您需要为这个特定命令键入两个参数:

    1. name的 API 的。

    2. 或用于访问 API 的证书类型(IAM、OIDC 等)。authentication-type

    注意

    还有其他诸如此类的参数必须配置Region,但通常会默认为您的 CLI 配置值。

    示例命令将如下所示:

    aws appsync create-graphql-api --name testAPI123 --authentication-type API_KEY

    输出将在 CLI 中返回。示例如下:

    { "graphqlApi": { "xrayEnabled": false, "name": "testAPI123", "authenticationType": "API_KEY", "tags": {}, "apiId": "abcdefghijklmnopqrstuvwxyz", "uris": { "GRAPHQL": "https://zyxwvutsrqponmlkjihgfedcba.appsync-api.us-west-2.amazonaws.com/graphql", "REALTIME": "wss://zyxwvutsrqponmlkjihgfedcba.appsync-realtime-api.us-west-2.amazonaws.com/graphql" }, "arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz" } }
  3. 运行 start-schema-creation 命令。

    您需要为这个特定命令键入两个参数:

    1. 您执行api-id上一步中的操作。

    2. 架构definition,它是一个以 64 为基数编码的二进制 blob。

    示例命令将如下所示:

    aws appsync start-schema-creation --api-id abcdefghijklmnopqrstuvwxyz --definition "aa1111aa-123b-2bb2-c321-12hgg76cc33v"

    将返回输出:

    { "status": "PROCESSING" }

    此命令在处理后不会返回最终输出。必须使用单独的命令才能查看结果。get-schema-creation-status请注意,这两个命令是异步的,因此即使架构仍在创建中,您也可以检查输出状态。

添加根查询类型

每个 GraphQL 架构都必须具有根查询类型。您可以将它们视为 GraphQL 服务器的入口点(或端点)。

在本指南中,我们将创建一个示例Todo应用程序。我们将添加一个以单个getTodos字段命名的Query根类型,该字段返回一个包含Todo对象的列表。

Console
  1. 登录 Amazon Web Services Management Console并打开 AppSync 控制台

    1. API 控制面板中,选择你的 GraphQL API。

    2. 在边中,选择架构

  2. 在您的 schema.graphql 文件中添加以下内容:

    schema { query:Query } type Query { getTodos: [Todo] }
API
  1. 通过调用 UpdateTypeAPI 更新根架构。

  2. 通过调用 CreateTypeAPI 创建您的Query类型。

CLI
  1. 通过运行update-type命令更新您的根架构。

    你需要为这个特定命令输入几个参数:

    1. api-id的 API 的。

    2. type-name那种人。在控制台示例中,这是Schema

    3. 或您的类型内容。definition在控制台示例中,这是

      schema { query:Query }
    4. 你输入format的。在此示例中,我们使用SDL

    示例命令将如下所示:

    aws appsync update-type --api-id abcdefghijklmnopqrstuvwxyz --type-name schema --definition "schema {query:Query}" --format SDL

    输出将在 CLI 中返回。示例如下:

    { "type": { "definition": "schema {query:Query}", "name": "schema", "arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/schema", "format": "SDL" } }
  2. 通过运行create-type命令创建Query类型。

    你需要为这个特定命令输入几个参数:

    1. api-id的 API 的。

    2. 或您的类型内容。definition在控制台示例中,这是

      type Query { getTodos: [Todo] }
    3. 你输入format的。在此示例中,我们使用SDL

    示例命令将如下所示:

    aws appsync create-type --api-id abcdefghijklmnopqrstuvwxyz --definition "type Query {getTodos: [Todos]}" --format SDL

    输出将在 CLI 中返回。示例如下:

    { "type": { "definition": "Query {getTodos: [Todos]}", "name": "Query", "arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/Query", "format": "SDL" } }

请注意,我们还没有定义 Todo 对象类型。我们现在就来定义。

定义待办事项类型

在上一节中,我们在未定义其行为的情况下声明了Todo对象类型。

Console
  1. 登录 Amazon Web Services Management Console并打开 AppSync 控制台

    1. API 控制面板中,选择你的 GraphQL API。

    2. 在边中,选择架构

  2. 现在,创建一个类型,其中包含 Todo 对象的数据:

    schema { query:Query } type Query { getTodos: [Todo] } type Todo { id: ID! name: String description: String priority: Int }
API
  • 通过调用 CreateTypeAPI 创建您的Todo类型。

CLI
  • 通过运行create-type命令创建Todo类型。

    你需要为这个特定命令输入几个参数:

    1. api-id的 API 的。

    2. 或您的类型内容。definition在控制台示例中,这是

      type Todo { id: ID! name: String description: String priority: Int }
    3. 你输入format的。在此示例中,我们使用SDL

    示例命令将如下所示:

    aws appsync create-type --api-id abcdefghijklmnopqrstuvwxyz --definition "type Todo{id:ID! name:String description:String priority:Int}" --format SDL

    输出将在 CLI 中返回。示例如下:

    { "type": { "definition": "type Todo{id:ID! name:String description:String priority:Int}", "name": "Todo", "arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/Todo", "format": "SDL" } }

请注意,Todo对象类型具有标量类型的字段,例如字符串和整数。Amazon AppSync 除了可以在架构Amazon AppSync中使用的基本 GraphQL 标量外,还具有增强的标量类型。以感叹号结尾的字段都是必填字段。ID 标量类型是唯一标识符,可以是 StringInt。您可以在解析器代码中控制这些以实现自动分配,稍后将对此进行介绍。

QueryTodo 类型有相似之处。在 GraphQL 中,根类型(即 QueryMutationSubscription)与您定义的类型相似,但它们的不同之处在于您在架构中公开它们,作为 API 的入口点。有关更多信息,请参阅查询和突变类型

添加突变类型

现在您已有了一个对象类型,可以查询数据。如果您希望通过 API 添加、更新或删除数据,则需要在您的架构中添加更改类型。在 Todo 的示例中,可添加名为 addTodo 的更改类型的字段:

Console
  1. 登录 Amazon Web Services Management Console并打开 AppSync 控制台

    1. API 控制面板中,选择你的 GraphQL API。

    2. 在边中,选择架构

  2. 将突变添加到您的架构中并定义其类型:

    schema { query:Query mutation: Mutation } type Query { getTodos: [Todo] } type Mutation { addTodo(id: ID!, name: String, description: String, priority: Int): Todo } type Todo { id: ID! name: String description: String priority: Int }
API
  • 通过调用 CreateTypeAPI 创建您的Todo类型。

CLI
  1. 通过运行update-type命令更新您的根架构。

    你需要为这个特定命令输入几个参数:

    1. api-id的 API 的。

    2. type-name那种人。在控制台示例中,这是Schema

    3. 或您的类型内容。definition在控制台示例中,这是

      schema { query:Query mutation: Mutation }
    4. 你输入format的。在此示例中,我们使用SDL

    示例命令将如下所示:

    aws appsync update-type --api-id abcdefghijklmnopqrstuvwxyz --type-name schema --definition "schema {query:Query mutation: Mutation}" --format SDL

    输出将在 CLI 中返回。示例如下:

    { "type": { "definition": "schema {query:Query mutation: Mutation}", "name": "schema", "arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/schema", "format": "SDL" } }
  2. 通过运行create-type命令创建Mutation类型。

    你需要为这个特定命令输入几个参数:

    1. api-id的 API 的。

    2. 或您的类型内容。definition在控制台示例中,这是

      type Mutation { addTodo(id: ID!, name: String, description: String, priority: Int): Todo }
    3. 你输入format的。在此示例中,我们使用SDL

    示例命令将如下所示:

    aws appsync create-type --api-id abcdefghijklmnopqrstuvwxyz --definition "type Mutation {addTodo(id: ID! name: String description: String priority: Int): Todo}" --format SDL

    输出将在 CLI 中返回。示例如下:

    { "type": { "definition": "type Mutation {addTodo(id: ID! name: String description: String priority: Int): Todo}", "name": "Mutation", "arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/Mutation", "format": "SDL" } }

请注意,更改也添加到此架构类型,因为它是根类型。

使用状态修改待办事项示例

此时,您的 GraphQL API 在结构上可以读取和写入Todo对象,只是没有数据源,下一节将对此进行介绍。您可以使用更高级的功能修改此 API,例如为您的添加状态Todo,该状态来自一组定义为ENUM. 例如,请参阅下面的片段:

schema { query:Query mutation: Mutation } type Query { getTodos: [Todo] } type Mutation { addTodo(id: ID!, name: String, description: String, priority: Int, status: TodoStatus): Todo } type Todo { id: ID! name: String description: String priority: Int status: TodoStatus } enum TodoStatus { done pending }

ENUM 与字符串类似,但它可包含一组值中的一个值。在上一示例中,您添加了这种类型,修改了 Todo 类型,还添加了 Todo 字段以包含此功能。

注意

您可以直接跳到附加数据源,立即开始将架构连接到数据源,也可以继续阅读以使用分页和关系结构修改架构。

订阅

在 Amazon AppSync 中,订阅是作为更改的响应调用的。您可使用架构中的Subscription 类型和 @aws_subscribe() 指令进行配置,以指定哪些更改会调用一个或多个订阅。有关配置订阅的更多信息,请参阅实时数据

关系和分页(高级)

假设您有一百万项 todos。您一定不希望每次都提取所有内容,而是希望进行分页。请对您的架构进行以下改动:

  • nextToken 字段添加两个输入参数:getTodoslimit

  • 添加一个包含todosnextToken字段的新TodoConnection类型。

  • 更改 getTodos,使其返回 TodoConnection(而不是 Todos 列表)。

schema { query:Query mutation: Mutation } type Query { getTodos(limit: Int, nextToken: String): TodoConnection } type Mutation { addTodo(id: ID!, name: String, description: String, priority: Int, status: TodoStatus): Todo } type Todo { id: ID! name: String description: String priority: Int status: TodoStatus } type TodoConnection { todos: [Todo] nextToken: String } enum TodoStatus { done pending }

TodoConnection 类型允许您返回一组 todos 以及一个 nextToken,用于获得下一批 todos。请注意,它是单个 TodoConnection 而不是一个连接列表。连接内是一个 todo 项目 ([Todo]) 列表,它与分页令牌一起返回。在中Amazon AppSync,它通过解析器连接到 Amazon DynamoDB,并自动生成为加密令牌。它会将 limit 参数的值转换为 maxResults 参数;并将 nextToken 参数转换为 exclusiveStartKey 参数。有关示例和Amazon AppSync 控制台中的内置模板示例,请参阅 Resolver reference (JavaScript) JavaScript 或 VTL 的 R esolver 映射模板参考 (VTL)

接下来,假设您的 Todo 有评论,您希望运行查询,返回某一 todo 的所有评论。这是通过处理的GraphQL connections。修改您的架构,添加 Comment 类型,并为 comments 类型添加 Todo 字段、为 addComment 类型添加 Mutation 字段,如下所示:

schema { query: Query mutation: Mutation } type Query { getTodos(limit: Int, nextToken: String): TodoConnection } type Mutation { addTodo(id: ID!, name: String, description: String, priority: Int, status: TodoStatus): Todo addComment(todoid: ID!, content: String): Comment } type Comment { todoid: ID! commentid: String! content: String } type Todo { id: ID! name: String description: String priority: Int status: TodoStatus comments: [Comment] } type TodoConnection { todos: [Todo] nextToken: String } enum TodoStatus { done pending }

请注意,该Comment类型具有与之关联的commentid、和contenttodoid这相当于您稍后创建的 Amazon DynamoDB 表中的主键和排序键组合。

在 Amazon AppSync 中,依托于现有数据源的应用程序图表允许您在一个 GraphQL 查询中返回两个不同数据源的数据。在示例中,假设有一个 Todos 表和一个 Comments 表。我们将在 “附加数据源” 和 “配置解析器” 中介绍如何执行此操作。