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

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

实时数据

Amazon AppSync 允许您使用订阅实施实时应用程序更新、推送通知等。在客户端调用 GraphQL 订阅操作时，Amazon AppSync 自动建立并维护安全的 WebSocket 连接。然后，应用程序可以将数据从数据源实时分配给订阅者，同时 Amazon AppSync 持续管理应用程序的连接和扩展要求。以下几节说明了订阅在 Amazon AppSync 中的工作方式。

GraphQL 架构订阅指令

Amazon AppSync 中的订阅是作为变更响应调用的。这意味着，您可以在变更上指定 GraphQL 架构指令，以在 Amazon AppSync 中实时生成任何数据源。

Amazon Amplify 客户端库自动处理订阅连接管理。这些库将纯 WebSockets 作为客户端和服务之间的网络协议。

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

以下示例展示了如何使用 GraphQL 订阅。该示例未指定数据源，因为数据源可以是 Lambda、Amazon DynamoDB 或 Amazon OpenSearch Service。

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

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 的情况下，将得到错误）。

在使用纯 WebSockets 时，订阅选择集是至关重要的。如果在订阅中未明确定义某个字段，则 Amazon 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。

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

使用订阅参数

使用 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 值具有含义

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

让我们回到创建 Todo 的 Todo 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
  }
}