订阅筛选增强型 - Amazon AppSync
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 Amazon Web Services 服务入门

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

订阅筛选增强型

InAmazon 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,你定义了onSpecialTicketCreatedonGroupTicketCreated订阅。假设您正在为第一个订阅实现增强过滤器,onSpecialTicketCreated. 它的主要要求是筛选订阅的客户端onSpecialTicketCreated与之关联的订阅createTicket更改。

要实现增强型过滤器的行为,必须使用$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筛选新创建的票证,但它们不会实时发送到 connected WebSocket订阅的客户onSpecialTicketCreated.


                    显示票证筛选查询的示例

在订阅解析器(增强筛选)中定义的过滤器优先于仅基于订阅参数的筛选(基本筛选)。有关使用订阅参数的更多信息,请参阅。使用订阅参数)。

如果在订阅的 GraphQL 架构中定义了一个参数并且是必需的,则只有在解析器中将该参数定义为规则时,才会基于给定参数进行筛选$extensions.setSubscriptionFilter()方法。但是,如果没有$extensions筛选方法在订阅解析器中,客户端中定义的参数仅用于基本筛选。您不能同时使用基本筛选和增强筛选。

您可以使用$context变量在订阅的筛选扩展逻辑中访问某些信息。例如,由检索的属性GetItem来自 Amazon DynamoDB 的操作,在同一个订阅请求映射模板中定义 ($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 } }

订阅的客户端会监听要通过以下方式自动推送的数据 WebSockets使用创建票证后createTicket更改:

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()resolver 实用程序可以在订阅响应映射模板中实现,以便为每个客户端应用订阅参数中定义的过滤器:

## Response Mapping Template - onSpecialTicketCreated subscription $extensions.setSubscriptionFilter($util.transform.toSubscriptionFilter($util.parseJson($ctx.args.filter))) $util.toJson($context.result)

通过这种策略,客户可以定义自己的过滤器,这些过滤器使用增强的过滤逻辑和其他运算符。过滤器是在给定客户端在安全环境中调用订阅查询时分配的 WebSocket 连接. 有关用于增强筛选的转换实用程序的更多信息,包括filter查询变量负载,参见解析器映射模板实用程序参考.