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

在中定义增强型订阅过滤器 AWS AppSync

在中 AWS AppSync，您可以使用支持其他逻辑运算符的筛选器，直接在 GraphQL API 订阅解析器中定义和启用业务逻辑，以便在后端进行数据筛选。您可以配置这些筛选条件，这与在客户端的订阅查询上定义的订阅参数不同。有关使用订阅参数的更多信息，请参阅使用订阅参数。有关运算符列表，请参阅AWS AppSync 解析器映射模板实用程序参考。

就本文而言，我们将实时数据筛选分为以下几个类别：

以下几节介绍了如何配置增强订阅筛选条件，并说明了它们的实际用途。

在 GraphQL 架构中定义订阅

要使用增强订阅筛选条件，您可以在 GraphQL 架构中定义订阅，然后使用筛选扩展定义增强筛选条件。要说明增强型订阅筛选的工作原理 AWS AppSync，请使用以下 GraphQL 架构（它定义了票证管理系统API）作为示例：

type Ticket {
	id: ID
	createdAt: AWSDateTime
	content: String
	severity: Int
	priority: Priority
	category: String
	group: String
	status: String
	
}

type Mutation {
	createTicket(input: TicketInput): Ticket
}

type Query {
	getTicket(id: ID!): Ticket
}

type Subscription {
	onSpecialTicketCreated: Ticket @aws_subscribe(mutations: ["createTicket"])
	onGroupTicketCreated(group: String!): Ticket @aws_subscribe(mutations: ["createTicket"])
}



enum Priority {
	none
	lowest
	low
	medium
	high
	highest
}

input TicketInput {
	content: String
	severity: Int
	priority: Priority
	category: String
	group: String
	

假设你为你的NONE数据源创建了一个数据源API，然后使用这个数据源将一个解析器附加到createTicket突变中。您的处理程序可能如下所示：

import { util } from '@aws-appsync/utils';

export function request(ctx) {
	return {
		payload: {
			id: util.autoId(),
			createdAt: util.time.nowISO8601(),
			status: 'pending',
			...ctx.args.input,
		},
	};
}

export function response(ctx) {
	return ctx.result;
}

要实施增强筛选条件的行为，您必须使用 extensions.setSubscriptionFilter() 函数定义一个筛选条件表达式，该表达式针对通过 GraphQL 变更发布并且订阅客户端可能感兴趣的数据进行评估。有关筛选扩展的更多信息，请参阅扩展。

以下几节介绍了如何使用筛选扩展实施增强筛选条件。

使用筛选扩展创建增强订阅筛选条件

增强型过滤器写JSON在订阅的解析器的响应处理程序中。可以将筛选条件组合到一个名为 filterGroup 的列表中。筛选条件是使用至少一个规则定义的，每个规则包含字段、运算符和值。让我们为 onSpecialTicketCreated 定义一个新的解析器以设置增强筛选条件。您可以在过滤器中配置多个使用AND逻辑进行评估的规则，而筛选器组中的多个筛选器则使用 OR 逻辑进行评估：

import { util, extensions } from '@aws-appsync/utils';

export function request(ctx) {
	// simplfy return null for the payload
	return { payload: null };
}

export function response(ctx) {
	const filter = {
		or: [
			{ severity: { ge: 7 }, priority: { in: ['high', 'medium'] } },
			{ category: { eq: 'security' }, group: { in: ['admin', 'operators'] } },
		],
	};
	extensions.setSubscriptionFilter(util.transform.toSubscriptionFilter(filter));

  // important: return null in the response
	return null;
}

根据前面示例中定义的过滤器，如果使用以下方法创建票证，则重要票证会自动推送到订阅的API客户端：

或

订阅解析器中定义的筛选条件（增强筛选）优先于仅基于订阅参数的筛选（基本筛选）。有关使用订阅参数的更多信息，请参阅使用订阅参数。

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

您可以在订阅的筛选条件扩展逻辑中使用 context 变量，以访问有关请求的上下文信息。例如，在使用 Amazon Cognito 用户池或 Lambda 自定义授权方进行授权时，您可以在订阅建立context.identity时检索有关您的用户的信息。OIDC您可以使用该信息根据用户身份设置筛选条件。

现在假设您希望实施 onGroupTicketCreated 的增强筛选条件行为。onGroupTicketCreated 订阅要求将必需的 group 名称作为参数。在创建后，将自动为票证分配 pending 状态。您可以设置订阅筛选条件，以仅接收属于提供的组的新创建的票证：

import { util, extensions } from '@aws-appsync/utils';

export function request(ctx) {
	// simplfy return null for the payload
	return { payload: null };
}

export function response(ctx) {
	const filter = { group: { eq: ctx.args.group }, status: { eq: 'pending' } };
	extensions.setSubscriptionFilter(util.transform.toSubscriptionFilter(filter));

	return null;
}

在使用变更发布数据时，如以下示例中所示：

mutation CreateTicket {
  createTicket(input: {priority: medium, severity: 2, group: "aws"}) {
    id
    priority
    severity
    status
    group
    createdAt
  }
}

订阅的客户端会在创建带有createTicket变异的票证后立即监听要自动推送 WebSockets的数据：

subscription OnGroup {
  onGroupTicketCreated(group: "aws") {
    category
    status
    severity
    priority
    id
    group
    createdAt
    content
  }
}

无需参数即可订阅客户端，因为筛选逻辑是在 AWS AppSync 服务中实现的，具有增强筛选功能，从而简化了客户端代码。只有在满足定义的筛选条件时，客户端才会收到数据。

为嵌套的架构字段定义增强筛选条件

您可以使用增强订阅筛选以筛选嵌套的架构字段。假设我们修改了上一节中的架构以包含位置和地址类型：

type Ticket {
	id: ID
	createdAt: AWSDateTime
	content: String
	severity: Int
	priority: Priority
	category: String
	group: String
	status: String
	location: ProblemLocation
}

type Mutation {
	createTicket(input: TicketInput): Ticket
}

type Query {
	getTicket(id: ID!): Ticket
}

type Subscription {
	onSpecialTicketCreated: Ticket @aws_subscribe(mutations: ["createTicket"])
	onGroupTicketCreated(group: String!): Ticket @aws_subscribe(mutations: ["createTicket"])
}

type ProblemLocation {
	address: Address
}

type Address {
	country: String
}

enum Priority {
	none
	lowest
	low
	medium
	high
	highest
}

input TicketInput {
	content: String
	severity: Int
	priority: Priority
	category: String
	group: String
	location: AWSJSON

对于该架构，您可以使用 . 分隔符表示嵌套。以下示例为 location.address.country 下面的嵌套架构字段添加筛选规则。如果票证的地址设置为 USA，则会触发订阅：

import { util, extensions } from '@aws-appsync/utils';

export const request = (ctx) => ({ payload: null });

export function response(ctx) {
	const filter = {
		or: [
			{ severity: { ge: 7 }, priority: { in: ['high', 'medium'] } },
			{ category: { eq: 'security' }, group: { in: ['admin', 'operators'] } },
			{ 'location.address.country': { eq: 'USA' } },
		],
	};
	extensions.setSubscriptionFilter(util.transform.toSubscriptionFilter(filter));
	return null;
}

在上面的示例中，location 表示嵌套级别 1，address 表示嵌套级别 2，country 表示嵌套级别 3，所有这些字段以 . 分隔符分隔。

您可以使用 createTicket 变更测试该订阅：

mutation CreateTicketInUSA {
  createTicket(input: {location: "{\"address\":{\"country\":\"USA\"}}"}) {
    category
    content
    createdAt
    group
    id
    location {
      address {
        country
      }
    }
    priority
    severity
    status
  }
}

从客户端中定义增强筛选条件

您可以在 GraphQL 中通过订阅参数使用基本筛选。在订阅查询中进行调用的客户端定义参数的值。当在带有筛选功能的 AWS AppSync 订阅解析器中启用增强型extensions过滤器时，解析器中定义的后端过滤器具有优先级和优先级。

使用 filter 参数在订阅中配置客户端定义的动态增强筛选条件。在配置这些筛选条件时，您必须更新 GraphQL 架构以反映新参数：

...
type Subscription {
    onSpecialTicketCreated(filter: String): Ticket
        @aws_subscribe(mutations: ["createTicket"])
}
...

然后，客户端可以发送订阅查询，如以下示例中所示：

subscription onSpecialTicketCreated($filter: String) {
     onSpecialTicketCreated(filter: $filter) {
        id
        group
        description
        priority
        severity
     }
 }

您可以像以下示例一样配置查询变量：

{"filter" : "{\"severity\":{\"le\":2}}"}

可以在订阅响应映射模板中实施 util.transform.toSubscriptionFilter() 解析器实用程序，以应用每个客户端的订阅参数中定义的筛选条件：

import { util, extensions } from '@aws-appsync/utils';

export function request(ctx) {
	// simplfy return null for the payload
	return { payload: null };
}

export function response(ctx) {
	const filter = ctx.args.filter;
	extensions.setSubscriptionFilter(util.transform.toSubscriptionFilter(filter));
	return null;
}

通过使用该策略，客户端可以定义自己的筛选条件，以使用增强筛选逻辑和额外的运算符。当给定客户端在安全 WebSocket 连接中调用订阅查询时，就会分配过滤器。有关用于增强筛选的转换实用程序的更多信息，包括filter查询变量负载的格式，请参阅JavaScript 解析器概述。

额外的增强筛选限制

以下是几个对增强筛选条件施加额外限制的使用案例：