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

在中使用实时数据应用程序的订阅 AWS AppSync

AWS AppSync允许您利用订阅来实现实时应用程序更新、推送通知等。当客户端调用 GraphQL 订阅操作时，会由自动建立和维护安全 WebSocket 连接。 AWS AppSync然后，应用程序可以将数据源中的数据实时分发给订阅者，同时 AWS AppSync 持续管理应用程序的连接和扩展需求。以下各节将向您展示订阅 AWS AppSync的工作原理。

GraphQL 架构订阅指令

中的订阅 AWS AppSync 是作为对突变的响应而调用的。这意味着您可以通过在突变上指定 GraphQL 架构指令来 AWS AppSync 实时创建任何数据源。

AWS Amplify 客户端库会自动处理订阅连接管理。这些库使用 pure WebSockets 作为客户端和服务之间的网络协议。

订阅由变更触发，并将变更选择集发送给订阅者。

以下示例展示了如何使用 GraphQL 订阅。它没有指定数据源，因为数据源可能是 Lambda、Amazon DynamoDB 或亚马逊服务。 OpenSearch

要开始使用订阅，您必须将订阅入口点添加到您的架构中，如下所示：

schema {
    query: Query
    mutation: Mutation
    subscription: Subscription
}

假设有一个博客站点，您希望订阅新博文和现有博客的变更。为此，请在架构中添加以下 Subscription 定义：

type Subscription {
    addedPost: Post
    updatedPost: Post
    deletedPost: Post
}

进一步假设有以下变更：

type Mutation {
    addPost(id: ID! author: String! title: String content: String url: String): Post!
    updatePost(id: ID! author: String! title: String content: String url: String ups: Int! downs: Int! expectedVersion: Int!): Post!
    deletePost(id: ID!): Post!
}

对于希望收到通知的每个订阅，您可以添加 @aws_subscribe(mutations: ["mutation_field_1", "mutation_field_2"]) 指令，使这些字段成为实时字段，如下所示：

type Subscription {
    addedPost: Post
    @aws_subscribe(mutations: ["addPost"])
    updatedPost: Post
    @aws_subscribe(mutations: ["updatePost"])
    deletedPost: Post
    @aws_subscribe(mutations: ["deletePost"])
}

由于 @aws_subscribe(mutations: ["",..,""]) 使用变更输入数组，因此，您可以指定多个启动订阅的变更。如果您从客户端订阅，您的 GraphQL 查询可能是下面的样子：

subscription NewPostSub {
    addedPost {
        __typename
        version
        title
        content
        author
        url
    }
}

客户端连接和工具需要使用该订阅查询。

对于纯 WebSockets 客户端，选择集筛选是针对每个客户机进行的，因为每个客户机都可以定义自己的选择集。在这种情况下，订阅选择集必须是变更选择集的子集。例如，链接到变更 addPost(...){id author title url version} 的订阅 addedPost{author title} 仅接收文章的作者和标题。它不会接收其他字段。但是，如果变更在其选择集中缺少作者，则订阅者将获得作者字段的 null 值（或者，如果在架构中将作者字段定义为必填/非 Null 的情况下，将得到错误）。

使用 pure 时，订阅选择集是必不可少的 WebSockets。如果订阅中未明确定义字段，则 AWS AppSync 不会返回该字段。

在以上示例中，订阅没有参数。假设您的架构如下所示：

type Subscription {
    updatedPost(id:ID! author:String): Post
    @aws_subscribe(mutations: ["updatePost"])
}

在这种情况下，您的客户端定义了订阅，如下所示：

subscription UpdatedPostSub {
    updatedPost(id:"XYZ", author:"ABC") {
        title
        content
    }
}

您的架构中 subscription 字段的返回类型必须与相应的变更字段的返回类型匹配。在上一示例中，addPost 和 addedPost 返回的类型都是 Post。

要在客户端上设置订阅，请参阅使用 Amplify 客户端构建客户端应用程序。

使用订阅参数

使用 GraphQL 订阅的一个重要部分是，了解何时以及如何使用参数。您可以进行细微的更改，以修改何时以及如何向客户端通知发生的变更。为此，请参阅快速入门章节中创建“Todo”的示例架构。对于该示例架构，定义了以下变更：

type Mutation {
    createTodo(input: CreateTodoInput!): Todo
    updateTodo(input: UpdateTodoInput!): Todo
    deleteTodo(input: DeleteTodoInput!): Todo
}

在默认示例中，客户端可以使用不带参数的 onUpdateTodo subscription 订阅任何 Todo 的更新：

subscription OnUpdateTodo {
  onUpdateTodo {
    description
    id
    name
    when
  }
}

您可以使用 subscription 的参数对其进行筛选。例如，要仅在更新具有特定 ID 的 todo 时触发 subscription，请指定 ID 值：

subscription OnUpdateTodo {
  onUpdateTodo(id: "a-todo-id") {
    description
    id
    name
    when
  }
}

您也可以传递多个参数。例如，以下 subscription 说明了如何在特定地点和时间获取任何 Todo 更新的通知：

subscription todosAtHome {
  onUpdateTodo(when: "tomorrow", where: "at home") {
    description
    id
    name
    when
    where
  }
}

请注意，所有参数都是可选的。如果未在 subscription 中指定任何参数，您将订阅应用程序中发生的所有 Todo 更新。不过，您可以更新 subscription 的字段定义以要求使用 ID 参数。这会强制提供特定 todo 的响应，而不是提供所有 todo 的响应：

onUpdateTodo(
  id: ID!,
  name: String,
  when: String,
  where: String,
  description: String
): Todo

参数 null 值具有含义

在中进行订阅查询时 AWS AppSync，null参数值对结果的筛选方式与完全省略参数的方式不同。

让我们回到待办事项API示例，我们可以在其中创建待办事项。请参阅快速入门章节中的示例架构。

让我们修改架构以在 Todo 类型上包含新的 owner 字段，该字段描述所有者是谁。owner 字段不是必填字段，只能在 UpdateTodoInput 上设置该字段。请参阅以下简化架构版本：

type Todo {
  id: ID!
  name: String!
  when: String!
  where: String!
  description: String!
  owner: String
}

input CreateTodoInput {
  name: String!
  when: String!
  where: String!
  description: String!
}

input UpdateTodoInput {
  id: ID!
  name: String
  when: String
  where: String
  description: String
  owner: String
}

type Subscription {
    onUpdateTodo(
        id: ID,
        name: String,
        when: String,
        where: String,
        description: String
    ): Todo @aws_subscribe(mutations: ["updateTodo"])
}

以下订阅返回所有 Todo 更新：

subscription MySubscription {
  onUpdateTodo {
    description
    id
    name
    when
    where
  }
}

如果您修改前面的订阅以添加字段参数 owner: null，您现在会问一个不同的问题。该订阅现在注册客户端，以获得所有未提供所有者的 Todo 更新的通知。

subscription MySubscription {
  onUpdateTodo(owner: null) {
    description
    id
    name
    when
    where
  }
}