设计你的架构 - 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 标量类型是唯一标识符，可以是 String 或 Int。您可以在解析器代码中控制这些以实现自动分配，稍后将对此进行介绍。

Query 和 Todo 类型有相似之处。在 GraphQL 中，根类型（即 Query、Mutation 和 Subscription）与您定义的类型相似，但它们的不同之处在于您在架构中公开它们，作为 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 字段添加两个输入参数：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 表。我们将在 “附加数据源” 和 “配置解析器” 中介绍如何执行此操作。