设计您的架构
创建空架构
架构文件是文本文件,通常名为 schema.graphql
。您可以创建此文件,并使用 CLI 提交到 AWS AppSync 或导航到控制台并在 Schema (架构) 页面之下添加以下内容:
schema { }
每个架构都使用此根进行处理。只有添加了根查询类型之后才能进行处理。
添加根查询类型
在此示例中,我们将创建 Todo
应用程序。GraphQL 架构必须有根查询类型,所以我们要添加名为 Query
的根类型,它只有一个 getTodos
字段,返回包含 Todo
对象的列表。在您的 schema.graphql
文件中添加以下内容:
schema { query:Query } type Query { getTodos: [Todo] }
请注意,我们还没有定义 Todo
对象类型。我们现在就来定义。
定义 Todo 类型
现在,创建一个类型,其中包含 Todo
对象的数据:
schema { query:Query } type Query { getTodos: [Todo] } type Todo { id: ID! name: String description: String priority: Int }
请注意,Todo
对象类型ID
标量类型是唯一标识符,可以是 String
或 Int
。您可以在解析程序映射模板中控制这些内容以便进行自动分配,下文中将进行阐述。
Query
和 Todo
类型有相似之处。在 GraphQL 中,根类型(即 Query
、Mutation
和 Subscription
)与您定义的类型相似,但它们的不同之处在于您在架构中公开它们,作为 API 的入口点。有关更多信息,请参阅查询和更改类型
添加更改类型
现在您已有了一个对象类型,可以查询数据。如果您希望通过 API 添加、更新或删除数据,则需要在您的架构中添加更改类型。在 Todo
的示例中,可添加名为 addTodo
的更改类型的字段:
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 }
请注意,更改也添加到此架构类型,因为它是根类型。
修改 Todo 示例的状态
现在,您的 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 }
选择 Save Schema (保存架构)。
ENUM
与字符串类似,但它可包含一组值中的一个值。在上一示例中,您添加了这种类型,修改了 Todo 类型,还添加了 Todo 字段以包含此功能。
注意:您可以直接跳到附加数据源并立即开始将您的架构连接到数据源,或者继续阅读以使用分页和关系结构修改您的架构。
订阅
在 AWS AppSync 中,订阅是作为更改的响应调用的。您可使用架构中的Subscription
类型和 @aws_subscribe()
指令进行配置,以指定哪些更改会调用一个或多个订阅。有关配置订阅的更多信息,请参阅实时数据。
延伸阅读
有关更多信息,请参阅 GraphQL 类型系统
高级 - 关系和分页
假设您有一百万项 todos
。您一定不希望每次都提取所有内容,而是希望进行分页。请对您的架构进行以下改动:
-
为
nextToken
字段添加两个输入参数:getTodos
和limit
。 -
添加新的
TodoConnection
类型,它包含todos
和nextToken
字段。 -
更改
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]
) 列表,它与分页令牌一起返回。在 AWS AppSync 中,它通过映射模板连接到 Amazon DynamoDB 并自动生成以作为加密令牌。它会将 limit
参数的值转换为 maxResults
参数;并将 nextToken
参数转换为 exclusiveStartKey
参数。有关 AWS AppSync 控制台中的示例和内置模板示例,请参阅解析程序映射模板参考。
接下来,假设您的 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 }
选择 Save Schema (保存架构)。
请注意,Comment
类型具有与其关联的 todoid
、commentid
和 content
。它与您之后创建的 Amazon DynamoDB 表中的主键 + 排序键的组合相对应。
在 AWS AppSync 中,依托于现有数据源的应用程序图表允许您在一个 GraphQL 查询中返回两个不同数据源的数据。在示例中,假设有一个 Todos 表和一个 Comments 表。我们将在附加数据源和配置解析程序中说明如何执行对应操作。