增强的订阅筛选

在中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查询变量负载的格式）的更多信息，请参阅解析器映射模板实用程序参考。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

创建由无服务器提供支持的通用 pub/sub API WebSockets

取消订阅连接