Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Definir filtros de suscripciones mejorados en AWS AppSync

En AWS AppSync, puedes definir y habilitar la lógica empresarial para el filtrado de datos en el backend directamente en los solucionadores de suscripciones de API GraphQL mediante filtros que admitan operadores lógicos adicionales. A diferencia de los argumentos de suscripción que se definen en la consulta de suscripción en el cliente, en este caso sí puede configurar estos filtros. Para obtener más información acerca de los argumentos de suscripción, consulte Uso de argumentos de suscripción. Para ver una lista de operadores, consulte AWS AppSync referencia de utilidad de plantilla de mapeo de resolución.

Para los fines de este documento, dividimos el filtrado de datos en tiempo real en las siguientes categorías:

En las siguientes secciones se explica cómo configurar los filtros de suscripción mejorados y se muestran sus aplicaciones prácticas.

Definición de suscripciones en su esquema de GraphQL

Para usar filtros de suscripción mejorados, defina la suscripción en el esquema de GraphQL y, a continuación, defina el filtro mejorado mediante una extensión de filtrado. Para ilustrar cómo funciona el filtrado de suscripciones mejorado AWS AppSync, utilice el siguiente esquema de GraphQL, que define un sistema de gestión de ticketsAPI, como ejemplo:

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
	

Supongamos que crea una fuente de NONE datos para usted yAPI, a continuación, adjunta un resolutor a la createTicket mutación utilizando esta fuente de datos. Los controladores pueden tener un aspecto similar al siguiente:

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 el comportamiento del filtro mejorado, debe usar la función extensions.setSubscriptionFilter() para definir una expresión de filtro evaluada en función de los datos publicados de una mutación de GraphQL que pueda interesar a los clientes suscritos. Para obtener más información acerca de las extensiones de filtrado, consulte Extensiones.

En la siguiente sección, se explica cómo utilizar extensiones de filtrado para implementar filtros mejorados.

Creación de filtros de suscripciones mejorados mediante extensiones de filtrado

Los filtros mejorados están escritos JSON en el controlador de respuestas de los resolutores de la suscripción. Los filtros se pueden agrupar en una lista llamada filterGroup. Los filtros se definen mediante al menos una regla, cada una con campos, operadores y valores. Definamos un nuevo solucionador para onSpecialTicketCreated que configure un filtro mejorado. Puede configurar varias reglas en un filtro que se evalúen mediante la AND lógica, mientras que varios filtros de un grupo de filtros se evalúan mediante la 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;
}

Según los filtros definidos en el ejemplo anterior, los tickets importantes se envían automáticamente a los API clientes suscritos si se crea un ticket con:

OR

Los filtros definidos en el solucionador de suscripciones (filtrado mejorado) tienen prioridad sobre el filtrado basado únicamente en los argumentos de suscripción (filtrado básico). Para obtener más información acerca de los argumentos de suscripción, consulte Uso de argumentos de suscripción.

Si un argumento está definido en el esquema de GraphQL de la suscripción y es obligatorio, el filtrado basado en el argumento en cuestión solo se lleva a cabo si el argumento está definido como una regla en el método extensions.setSubscriptionFilter() del solucionador. Sin embargo, si no hay métodos de filtrado de extensions en el solucionador de suscripciones, los argumentos definidos en el cliente se utilizan únicamente para el filtrado básico. No puede utilizar el filtrado básico y el filtrado mejorado a la vez.

Puede usar la variable context de la lógica de extensión del filtro de la suscripción para acceder a la información contextual sobre la solicitud. Por ejemplo, si utiliza grupos de usuarios de Amazon Cognito o autorizadores personalizados de Lambda para la autorización, puede recuperar información sobre sus usuarios context.identity cuando se establezca la suscripción. OIDC Puede usar esa información para establecer filtros basados en la identidad de sus usuarios.

Supongamos ahora que desea implementar el comportamiento de filtro mejorado para onGroupTicketCreated. La suscripción onGroupTicketCreated requiere un nombre group obligatorio como argumento. Cuando se crean, a los tickets se les asigna automáticamente un estado pending. Puedes configurar un filtro de suscripción para recibir solo los tickets recién creados que pertenezcan al grupo proporcionado:

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

Cuando los datos se publican mediante una mutación, como en el siguiente ejemplo:

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

Los clientes suscritos esperan que los datos se envíen automáticamente tan pronto WebSockets como se cree un ticket con la mutación: createTicket

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

Los clientes se pueden suscribir sin argumentos porque la lógica de filtrado está implementada en el AWS AppSync servicio con un filtrado mejorado, lo que simplifica el código del cliente. Los clientes reciben datos solo si se cumplen los criterios de filtro definidos.

Definición de filtros mejorados para campos de esquema anidados

Puede utilizar el filtrado de suscripciones mejorado para filtrar los campos de esquema anidados. Supongamos que modificamos el esquema de la sección anterior para incluir los tipos de ubicación y dirección:

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

Con este esquema, puede usar un separador . para representar el anidamiento. En el siguiente ejemplo, se agrega una regla de filtrado para un campo de esquema anidado en location.address.country. La suscripción se activará si la dirección del ticket se define 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;
}

En el ejemplo anterior, location representa el nivel de anidamiento uno, address representa el nivel de anidamiento dos y country representa el nivel de anidamiento tres, todos los cuales están separados por el separador ..

Puede probar esta suscripción mediante la mutación createTicket:

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

Definición de filtros mejorados desde el cliente

Puede usar el filtrado básico en GraphQL con argumentos de suscripciones. El cliente que realiza la llamada en la consulta de suscripción define los valores de los argumentos. Cuando los filtros mejorados están habilitados en una resolución de AWS AppSync suscripciones con el extensions filtrado, los filtros secundarios definidos en la resolución tienen prioridad y prioridad.

Configure filtros mejorados dinámicos definidos por el cliente en la suscripción usando un argumento filter. Al configurar estos filtros, debe actualizar el esquema de GraphQL para que refleje el nuevo argumento:

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

A continuación, el cliente puede enviar una consulta de suscripción como en el siguiente ejemplo:

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

Puede configurar la variable de consulta de la siguiente manera:

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

La utilidad de solucionador util.transform.toSubscriptionFilter() se puede implementar en la plantilla de mapeo de respuestas de suscripción para aplicar el filtro definido en el argumento de suscripción a 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;
}

Con esta estrategia, los clientes pueden definir sus propios filtros que utilizan una lógica de filtrado mejorada y operadores adicionales. Los filtros se asignan cuando un cliente determinado invoca la consulta de suscripción en una conexión segura. WebSocket Para obtener más información sobre la utilidad de transformación para mejorar el filtrado, incluido el formato de la carga útil de la variable de filter consulta, consulte la descripción general de los JavaScript resolutores.

Restricciones adicionales al filtrado mejorado

A continuación, se muestran varios casos de uso en los que se imponen restricciones adicionales a los filtros mejorados: