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

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

实时数据

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

GraphQL 模式订阅指令

在 Amazon AppSync 中，订阅是作为更改的响应调用的。这就意味着，您可以在 Amazon AppSync 中针对更改指定 GraphQL 架构指令，从而实时更新任何数据源。

Amazon 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 客户端，选择集筛选是针对每个客户机完成的，因为每个客户机都可以定义自己的选择集。在这种情况下，订阅选择集必须是更改选择集的子集。例如，addedPost{author title}链接到变异的订阅只addPost(...){id author title url version}会收到帖子的作者和标题。它不会接收其他字段。但是，如果更改在其选择集中缺少作者，则订阅者将获得作者字段的 null 值（或者，如果在架构中将作者字段定义为必填/非 Null 的情况下，将得到错误）。

使用 pure 时，订阅选择集至关重要 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 订阅的一个重要部分是了解何时以及如何使用参数。您可以进行细微的更改，修改通知客户有关已发生突变的方式和时间。要执行此操作，请参阅中的示例架构启动你的第一个 GraphQL API，该架构创建 “事件” 和 “注释”。在示例架构中，将出现以下更改：

type Mutation {
    createEvent(
        name: String!,
        when: String!,
        where: String!,
        description: String!
    ): Event
    deleteEvent(id: ID!): Event
    commentOnEvent(eventId: ID!, content: String!, createdAt: String!): Comment
}

在默认示例中，客户端可以订阅传递特定 eventId 参数时的评论：

type Subscription {
    subscribeToEventComments(eventId: String!): Comment
        @aws_subscribe(mutations: ["commentOnEvent"])
}

但如果您希望允许客户端订阅单次事件或所有事件，可以从订阅原型中移除感叹号 (!)，使这一参数成为可选参数：

subscribeToEventComments(eventId: String): Comment

这样更改之后，省略此参数的客户端将收到所有事件的评论。此外，如果您希望客户端显式订阅所有事件的所有评论，应删除参数，如下所示：

subscribeToEventComments: Comment

这些内容可用于一个或多个事件的评论。如果您想要了解创建的所有事件，可以执行以下操作：

type Subscription {
    subscribeToNewEvents: Event
        @aws_subscribe(mutations: ["createEvent"])
}

也可传递多个参数。例如，如果您希望获得特定时间和地点发生的新事件的通知，可以执行以下操作：

type Subscription {
    subscribePlaceDate(where: String! when: String!): Event
            @aws_subscribe(mutations: ["createEvent"])
}

因此，客户端应用程序现在可以执行以下操作：

subscription myplaces {
    subscribePlaceDate(where: "Seattle" when: "Saturday"){
        id
        name
        description
    }
}

参数 null 值具有含义

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

让我们回到事件应用程序示例，我们可以在其中创建事件并发布有关事件的评论。参见中的示例架构启动你的第一个 GraphQL API。

让我们修改架构，在location字段上添加一个新Comment字段，描述评论的发送地点。该值可以是一组坐标或一个位置。请参阅以下架构，为简洁起见，该架构已精简：

type Comment {
    # The id of the comment's parent event.
    eventId: ID!
    # A unique identifier for the comment.
    commentId: String!
    # The comment's content.
    content: String
    # Location where the comment was made
    location: String
}

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

type Mutation {
    commentOnEvent(eventId: ID!, location: String, content: String): Comment
}

type Subscription {
    subscribeToEventComments(eventId: String!, location: String, content: String): Comment
        @aws_subscribe(mutations: ["commentOnEvent"])
}

请注意新的可选字段 Comment.location。

现在，假设我们希望收到针对特定事件发布的所有评论的通知。在这种情况下，我们将编写以下订阅：

subscribeToEventComments(eventId: "1") {
    eventId
    commentId
    location
    content
}

如果我们改为将字段参数location: null添加到前面的订阅中：

subscribeToEventComments(eventId: "1" location: null) {
    eventId
    commentId
    location
    content
}

我们现在要问一个不同的问题。此订阅现在注册客户端以获得未提供特定事件位置的所有评论的通知。