实时数据 - Amazon AppSync
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 Amazon Web Services 服务入门

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

实时数据

GraphQL 模式订阅指令

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

这些区域有:Amazon Amplify客户端库自动处理订阅连接管理。图书馆使用 pure WebSockets 作为客户端和服务之间的网络协议。

注意:要控制订阅连接时的授权,可以使用Amazon Identity and Access Management(我是),Amazon Lambda、Amazon Cognito 身份池或用于字段级授权的 Amazon Cognito 用户池。如需针对订阅进行精细化的访问控制,您可以将解析程序附加到订阅字段,并使用调用者和 Amazon AppSync 数据源的身份执行逻辑。有关更多信息,请参阅 授权和身份验证

订阅由更改触发,并将更改选择集发送给订阅者。

以下示例展示了如何使用 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 字段的返回类型必须与相应的更改字段的返回类型匹配。在上一示例中,addPostaddedPost 返回的类型都是 Post

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

使用订阅参数

使用 GraphQL 订阅时,理解何时及如何使用参数很重要。您可以进行细微的更改,以修改向客户通知已发生的突变的方式和时间。为此,请查看来自的示例架构启动示例架构,了解相关信息。在示例架构中,将出现以下更改:

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 参数值将以不同于完全省略参数的方式筛选结果。

让我们回到事件应用程序示例,我们可以在其中创建事件并发布有关事件的评论。参见来自的示例架构启动示例架构.

让我们修改我们的架构以添加一个新的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 }

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

注意

截至 2022 年 1 月 1 日,MQTT 已结束 WebSockets 不再作为 GraphQL 订阅的协议可用Amazon AppSyncAPI。纯净 WebSockets 是中唯一支持的协议Amazon AppSync.

客户基于Amazon AppSync2019 年 11 月之后发布的 SDK 或 Amplify 库会自动使用 pure WebSockets 默认情况下。将客户端升级到最新版本允许他们使用Amazon AppSync是纯粹的 WebSockets 引擎。

纯净 WebSockets 具有更大的有效负载大小 (240 KB)、更多种类的客户端选项,并进行了改进 CloudWatch 指标。有关使用 pure 的更多信息 WebSocket 客户,请参阅构建实时终端节点 WebSocket 客户.