Definindo filtros de assinaturas aprimorados em AWS AppSync

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Em AWS AppSync, você pode definir e habilitar a lógica de negócios para filtragem de dados no back-end diretamente nos resolvedores de assinatura da API GraphQL usando filtros que suportam operadores lógicos adicionais. Você pode configurar esses filtros, diferentemente dos argumentos de assinatura definidos na consulta de assinatura no cliente. Para obter mais informações sobre como usar argumentos de assinatura, consulte Usar argumentos de assinatura. Para obter uma lista de operadores, consulte AWS AppSync referência do utilitário do modelo de mapeamento do resolvedor.

Para os fins deste documento, dividimos a filtragem de dados em tempo real nas seguintes categorias:

As seções a seguir explicam como configurar filtros de assinatura avançados e mostrar seu uso prático.

Definir assinaturas no esquema do GraphQL

Para usar filtros de assinatura avançados, defina a assinatura no esquema do GraphQL e, em seguida, defina o filtro avançado usando uma extensão de filtragem. Para ilustrar como a filtragem aprimorada de assinaturas funciona AWS AppSync, use o seguinte esquema do GraphQL, que define uma API do sistema de gerenciamento de tickets, como exemplo:

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
	

Suponha que você crie uma fonte de dados do NONE para a API e, em seguida, anexe um resolvedor à mutação do createTicket usando essa fonte de dados. Os manipuladores podem ser semelhantes a estes:

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;
}

Para implementar o comportamento do filtro aprimorado, você deve usar a função extensions.setSubscriptionFilter() para definir uma expressão de filtro avaliada em relação aos dados publicados de uma mutação do GraphQL na qual os clientes inscritos possam estar interessados. Para ter mais informações sobre as extensões de filtragem, consulte Extensões.

A seção a seguir explica como usar extensões de filtragem para implementar filtros avançados.

Criar filtros avançados de assinatura usando extensões de filtragem

Os filtros avançados são escritos em JSON no manipulador de respostas dos resolvedores da assinatura. Os filtros podem ser agrupados em uma lista chamada filterGroup. Os filtros são definidos usando pelo menos uma regra, cada uma com campos, operadores e valores. Vamos definir um novo resolvedor para onSpecialTicketCreated que configura um filtro avançado. Você pode configurar várias regras em um filtro que são avaliadas usando a lógica AND, enquanto vários filtros em um grupo de filtros são avaliados usando a lógica 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;
}

Com base nos filtros definidos no exemplo anterior, tíquetes importantes serão automaticamente enviados para clientes da API inscritos se um tíquete for criado com:

OU

Os filtros definidos no resolvedor de assinaturas (filtragem avançada) têm precedência sobre a filtragem baseada somente nos argumentos da assinatura (filtragem básica). Para obter mais informações sobre como usar argumentos de assinatura, consulte Usar argumentos de assinatura).

Se um argumento for definido e exigido no esquema GraphQL da assinatura, a filtragem com base no argumento fornecido ocorrerá somente se o argumento for definido como uma regra no método extensions.setSubscriptionFilter() do resolvedor. No entanto, se não houver métodos de filtragem de extensions no resolvedor de assinaturas, os argumentos definidos no cliente serão usados somente para a filtragem básica. Não é possível usar a filtragem básica e a filtragem avançada ao mesmo tempo.

Você pode usar a variável de context na lógica de extensão de filtro da assinatura para acessar informações contextuais sobre a solicitação. Por exemplo, ao usar grupos de usuários do Amazon Cognito, OIDC ou autorizadores personalizados de Lambda para autorização, você pode recuperar informações sobre os usuários no context.identity quando a assinatura é estabelecida. Você pode usar essas informações para estabelecer filtros com base na identidade dos seus usuários.

Agora, suponha que você queira implementar o comportamento de filtro avançado para onGroupTicketCreated. A assinatura do onGroupTicketCreated exige um nome de group obrigatório como argumento. Quando criados, os tickets recebem automaticamente um status pending. Você pode configurar um filtro de assinatura para receber somente tickets recém-criados que pertencem ao grupo fornecido:

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;
}

Quando os dados são publicados usando uma mutação, como no exemplo a seguir:

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

Os clientes inscritos ouvem os dados a serem enviados automaticamente WebSockets assim que um ticket é criado com a createTicket mutação:

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

Os clientes podem ser inscritos sem argumentos porque a lógica de filtragem é implementada no AWS AppSync serviço com filtragem aprimorada, o que simplifica o código do cliente. Os clientes receberão dados somente se os critérios de filtro definidos forem atendidos.

Definição de filtros aprimorados para campos de esquema aninhados

Você pode usar a filtragem de assinatura avançada para filtrar campos de esquema aninhados. Suponha que tenhamos modificado o esquema da seção anterior para incluir tipos de localização e endereço:

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

Com esse esquema, você pode usar um separador . para representar o aninhamento. O exemplo a seguir adiciona uma regra de filtro para um campo de esquema aninhado em location.address.country. A assinatura será acionada se o endereço do tíquete estiver definido como 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;
}

No exemplo acima, location representa o nível de aninhamento um, address representa o nível de aninhamento dois e country representa o nível de aninhamento três, todos separados pelo separador ..

Você pode testar essa assinatura usando a mutação createTicket:

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

Definindo filtros avançados do cliente

Você pode usar a filtragem básica no GraphQL com argumentos de assinaturas. O cliente que faz a chamada na consulta de assinatura define os valores dos argumentos. Quando filtros aprimorados são habilitados em um resolvedor de AWS AppSync assinatura com a extensions filtragem, os filtros de back-end definidos no resolvedor têm precedência e prioridade.

Configure filtros aprimorados dinâmicos definidos pelo cliente usando um argumento filter na assinatura. Ao configurar esses filtros, você deve atualizar o esquema do GraphQL para refletir o novo argumento:

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

O cliente pode então enviar uma consulta de assinatura, como no exemplo a seguir:

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

Você pode configurar a variável de consulta como no exemplo a seguir:

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

O utilitário do resolvedor util.transform.toSubscriptionFilter() pode ser implementado no modelo de mapeamento de resposta da assinatura para aplicar o filtro definido no argumento da assinatura para cada cliente:

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;
}

Com essa estratégia, os clientes podem definir seus próprios filtros que usam lógica de filtragem avançada e operadores adicionais. Os filtros são atribuídos quando um determinado cliente invoca a consulta de assinatura em uma conexão segura WebSocket . Para obter mais informações sobre o utilitário de transformação para filtragem aprimorada, incluindo o formato da carga útil da variável de filter consulta, consulte a visão geral dos JavaScriptresolvedores.

Restrições adicionais de filtragem avançada

Veja abaixo vários casos de uso em que restrições adicionais são colocadas em filtros avançados: