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
-
-
登录 Amazon Web Services Management Console并打开 AppSync 控制台。
-
在 API 控制面板中,选择你的 GraphQL API。
-
在边栏中,选择架构。
-
您可以通过在 “架构” 窗口中添加以下内容Amazon AppSync来配置schema.graphql
文件并将其提交给:
schema {
}
-
选择 Save schema。
每个架构都以用于处理的schema
根开头。只有添加了根查询类型之后才能进行处理。
- API
-
- CLI
-
-
如果您尚未执行此操作,请安装Amazon CLI,然后添加您的配置。
-
通过运行create-graphql-api
命令创建 GraphQL API 对象。
您需要为这个特定命令键入两个参数:
-
你name
的 API 的。
-
或用于访问 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"
}
}
-
运行 start-schema-creation
命令。
您需要为这个特定命令键入两个参数:
-
您执行api-id
上一步中的操作。
-
架构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
-
-
登录 Amazon Web Services Management Console并打开 AppSync 控制台。
-
在 API 控制面板中,选择你的 GraphQL API。
-
在边栏中,选择架构。
-
在您的 schema.graphql
文件中添加以下内容:
schema {
query:Query
}
type Query {
getTodos: [Todo]
}
- API
-
- CLI
-
-
通过运行update-type
命令更新您的根架构。
你需要为这个特定命令输入几个参数:
-
你api-id
的 API 的。
-
你type-name
那种人。在控制台示例中,这是Schema
。
-
或您的类型内容。definition
在控制台示例中,这是
schema {
query:Query
}
-
你输入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"
}
}
-
通过运行create-type
命令创建Query
类型。
你需要为这个特定命令输入几个参数:
-
你api-id
的 API 的。
-
或您的类型内容。definition
在控制台示例中,这是
type Query {
getTodos: [Todo]
}
-
你输入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
-
-
登录 Amazon Web Services Management Console并打开 AppSync 控制台。
-
在 API 控制面板中,选择你的 GraphQL API。
-
在边栏中,选择架构。
-
现在,创建一个类型,其中包含 Todo
对象的数据:
schema {
query:Query
}
type Query {
getTodos: [Todo]
}
type Todo {
id: ID!
name: String
description: String
priority: Int
}
- API
-
- CLI
-
-
通过运行create-type
命令创建Todo
类型。
你需要为这个特定命令输入几个参数:
-
你api-id
的 API 的。
-
或您的类型内容。definition
在控制台示例中,这是
type Todo {
id: ID!
name: String
description: String
priority: Int
}
-
你输入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
标量类型是唯一标识符,可以是 String
或 Int
。您可以在解析器代码中控制这些以实现自动分配,稍后将对此进行介绍。
Query
和 Todo
类型有相似之处。在 GraphQL 中,根类型(即 Query
、Mutation
和 Subscription
)与您定义的类型相似,但它们的不同之处在于您在架构中公开它们,作为 API 的入口点。有关更多信息,请参阅查询和突变类型。
添加突变类型
现在您已有了一个对象类型,可以查询数据。如果您希望通过 API 添加、更新或删除数据,则需要在您的架构中添加更改类型。在 Todo
的示例中,可添加名为 addTodo
的更改类型的字段:
- Console
-
-
登录 Amazon Web Services Management Console并打开 AppSync 控制台。
-
在 API 控制面板中,选择你的 GraphQL API。
-
在边栏中,选择架构。
-
将突变添加到您的架构中并定义其类型:
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
-
- CLI
-
-
通过运行update-type
命令更新您的根架构。
你需要为这个特定命令输入几个参数:
-
你api-id
的 API 的。
-
你type-name
那种人。在控制台示例中,这是Schema
。
-
或您的类型内容。definition
在控制台示例中,这是
schema {
query:Query
mutation: Mutation
}
-
你输入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"
}
}
-
通过运行create-type
命令创建Mutation
类型。
你需要为这个特定命令输入几个参数:
-
你api-id
的 API 的。
-
或您的类型内容。definition
在控制台示例中,这是
type Mutation {
addTodo(id: ID!, name: String, description: String, priority: Int): Todo
}
-
你输入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
字段添加两个输入参数:getTodos
和 limit
。
-
添加一个包含todos
和nextToken
字段的新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
、和content
。todoid
这相当于您稍后创建的 Amazon DynamoDB 表中的主键和排序键组合。
在 Amazon AppSync 中,依托于现有数据源的应用程序图表允许您在一个 GraphQL 查询中返回两个不同数据源的数据。在示例中,假设有一个 Todos 表和一个 Comments 表。我们将在 “附加数据源” 和 “配置解析器” 中介绍如何执行此操作。