本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
增强的订阅筛选
在中Amazon AppSync,您可以使用支持其他逻辑运算符的过滤器,直接在 GraphQL API 订阅解析器中定义和启用用于后端数据筛选的业务逻辑。您可以配置这些过滤器,这与在客户端的订阅查询中定义的订阅参数不同。有关使用订阅参数的更多信息,请参阅使用订阅参数。有关运算符的列表,请参阅解析器映射模板实用程序参考。
在本文档中,我们将实时数据过滤分为以下几类:
-
基本筛选-根据订阅查询中客户端定义的参数进行筛选。
-
增强过滤-基于Amazon AppSync服务后端集中定义的逻辑进行筛选。
下面几节介绍如何配置增强的订阅筛选条件并介绍其实际用途。
在 GraphQL 架构中定义订阅
要使用增强型订阅筛选器,必须在 GraphQL 架构中定义订阅,然后使用筛选扩展插件定义增强型筛选器。要说明增强订阅筛选的工作原理Amazon AppSync,请使用以下 GraphQL 架构作为示例,该架构定义了票证管理系统 API:
type Mutation { createTicket(input: TicketInput): Ticket } enum Priority { none lowest low medium high highest } type Query { getTicket(id: ID!): Ticket } type Subscription { onSpecialTicketCreated: Ticket @aws_subscribe(mutations: ["createTicket"]) onGroupTicketCreated(group: String!): Ticket @aws_subscribe(mutations: ["createTicket"]) } type Ticket { id: ID content: String severity: Int group: String createdAt: AWSDateTime priority: Priority status: String plusOnes: Int category: String type: String item: String } input TicketInput { content: String group: String severity: Int priority: Priority status: String category: String type: String item: String } schema { query: Query mutation: Mutation subscription: Subscription }
在给定订阅的 GraphQL 解析器的响应映射模板中启用了增强过滤器。有关更多信息,请参阅 解析器映射模板概述。
在前面的示例中,您使用Subscription
来定义订阅筛选器要求。在中Subscription
,您可以定义onSpecialTicketCreated
和onGroupTicketCreated
订阅。假设您正在为第一次订阅实现增强过滤器onSpecialTicketCreated
。它的主要要求是筛选订阅与createTicket
变异相关的onSpecialTicketCreated
订阅的客户。
要实现增强型过滤器的行为,必须使用该$extensions.setSubscriptionFilter()
方法定义一个过滤器表达式,该表达式是根据来自已订阅客户端可能感兴趣的 GraphQL 变异的已发布数据进行评估的。有关筛选扩展的更多信息,请参阅解析器映射模板实用程序参考。
下面几节介绍如何使用筛选扩展来实现增强的筛选条件。
使用过滤扩展程序创建增强型订阅过滤器
增强型过滤器以 JSON 编写在订阅解析器的响应映射模板中。过滤器可以组合到一个名为 a 的列表中filterGroup
。过滤器使用至少一条规则来定义,每个规则都有字段、运算符和值。在以下示例中,假设您要为定义过滤器onSpecialTicketCreated
。使用$extensions.setSubscriptionFilter()
,过滤器中的多个规则使用 AND 逻辑进行评估,而过滤器组中的多个过滤器使用 OR 逻辑进行评估:
## Response Mapping Template - onSpecialTicketCreated subscription $extensions.setSubscriptionFilter({ "filterGroup": [ { "filters" : [ { "fieldName" : "severity", "operator" : "ge", "value" : 7 }, { "fieldName" : "priority", "operator" : "in", "value" : ["high", "medium"] } ] }, { "filters" : [ { "fieldName" : "classification", "operator" : "eq", "value" : "Security" }, { "fieldName" : "group", "operator" : "in", "value" : ["admin", "operators"] } ] } ] }) $util.toJson($context.result)
根据前面示例中定义的过滤器,如果使用以下方式创建票证,则重要票证会自动推送到已订阅的 API 客户端:
-
priority
级别high
或medium
AND
-
severity
级别ge
(大于或等于)7
或
-
classification
票证设置为Security
AND
-
group
赋值设置为admin
或operators
您仍然可以手动查询优先级较低的票证。但是,会Amazon AppSync过滤新创建的票证,并且它们不会实时发送给订阅的连接 WebSocket 客户端onSpecialTicketCreated
。

在订阅解析器(增强筛选)中定义的过滤器优先于仅基于订阅参数的筛选(基本筛选)。有关使用订阅参数的更多信息,请参阅使用订阅参数)。
如果在订阅的 GraphQL 架构中定义并需要参数,则只有在解析器的$extensions.setSubscriptionFilter()
方法中将参数定义为规则时,才会根据给定参数进行筛选。但是,如果订阅解析器中没有$extensions
筛选方法,则在客户端中定义的参数仅用于基本筛选。您不能同时使用基本筛选和增强筛选。
您可以使用订阅的过滤器扩展逻辑中的$context变量来访问某些信息。例如,由 Amazon DynamoDB 的GetItem
操作检索到的属性,该属性定义在相同的订阅请求映射模板 ($context.result.severity
)、用户身份 ($context.identity.sub
) 中,或在必要时在请求 ($context.args.userId
) 的特定参数中定义。
现在假设您要为onGroupTicketCreated
示例 GraphQL 架构中的另一个订阅实现增强的过滤器行为。订onGroupTicketCreated
阅需要使用强制性group
名称作为参数。创建后,系统会自动为票证分配pending
状态,还会配置第二个过滤器:status
## Response Mapping Template - onGroupTicketCreated subscription $extensions.setSubscriptionFilter({ "filterGroup": [ { "filters" : [ { "fieldName" : "group", "operator" : "eq", "value" : $ctx.args.group }, { "fieldName" : "status", "operator" : "eq", "value" : "pending" } ] } ] }) $util.toJson($context.result)
当使用突变发布数据时,如下例所示:
mutation TicketCreate{ createTicket(input: {description: "This is a ticket.", group: "admin", classification: "Security", priority: "high", severity: 10}) { id classification group description priority severity } }
订阅的客户端会在使用createTicket
变异创建票证后立即监听自动推送 WebSockets 数据:
subscription onSpecialTicketCreated{ onSpecialTicketCreated { id classification group description priority severity } }
无需参数即可订阅客户端,因为过滤逻辑是在Amazon AppSync服务中通过增强筛选实现的,这简化了客户端代码。只有在满足定义的筛选条件时,客户端才会收到数据。
定义来自客户端的增强过滤器
您可以在 GraphQL 中将基本筛选与订阅参数一起使用。在订阅查询中进行调用的客户端定义参数的值。在具有筛选功能的Amazon AppSync订阅解析器中启用增强$extensions
筛选器时,解析器中定义的后端过滤器具有优先级和优先级。
使用订阅中的filter
参数配置动态的、客户端定义的增强型过滤器。配置这些过滤器时,必须更新 GraphQL 架构以反映新参数:
... type Subscription { onSpecialTicketCreated(filter: String): Ticket @aws_subscribe(mutations: ["createTicket"]) } ...
然后,客户端可以发送订阅查询,如以下示例所示:
subscription onSpecialTicketCreated($filter: String) { onSpecialTicketCreated(filter: $filter) { id classification group description priority severity } }
您可以像以下示例一样配置查询变量:
{"filter" : "{\"severity\":{\"le\":2}}"}
可以在订阅响应映射模板中实现$util.transform.toSubscriptionFilter()
解析器实用程序,以便为每个客户端应用订阅参数中定义的过滤器:
## Response Mapping Template - onSpecialTicketCreated subscription $extensions.setSubscriptionFilter($util.transform.toSubscriptionFilter($util.parseJson($ctx.args.filter))) $util.toJson($context.result)
通过这种策略,客户可以定义自己的过滤器,这些过滤器使用增强的过滤逻辑和其他运算符。当给定客户端在安全 WebSocket 连接中调用订阅查询时,就会分配过滤器。有关用于增强筛选的转换实用程序(包括filter
查询变量负载的格式)的更多信息,请参阅解析器映射模板实用程序参考。