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
**importante**
A partir del 13 de marzo de 2025, podrás crear una PubSub API en tiempo real con la WebSockets tecnología de AWS AppSync Events. Para obtener más información, consulta [Publicar eventos WebSocket en](https://docs.aws.amazon.com/appsync/latest/eventapi/publish-websocket.html) la *Guía para desarrolladores de AWS AppSync eventos*.
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 la 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](aws-appsync-real-time-data.md#using-subscription-arguments). Para ver una lista de operadores, consulte [AWS AppSync referencia de la utilidad de plantilla de mapeo de resolución](resolver-util-reference.md).
Para los fines de este documento, dividimos el filtrado de datos en tiempo real en las siguientes categorías:
+ **Filtrado básico**: filtrado basado en los argumentos definidos por el cliente en la consulta de suscripción.
+ **Filtrado mejorado**: filtrado basado en la lógica definida de forma centralizada en el backend del AWS AppSync servicio.
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 la API de un sistema de gestión de tickets, 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 un origen de datos `NONE` para su API y, a continuación, adjunta un solucionador a la mutación `createTicket` utilizando este origen 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;
}
```
**nota**
Los filtros mejorados están habilitados en el controlador del solucionador de GraphQL en una suscripción determinada. Para obtener más información, consulte [Referencia al solucionador](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html).
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](https://docs.aws.amazon.com//appsync/latest/devguide/extensions-js.html).
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 en JSON en el controlador de respuestas de los solucionadores 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úan mediante la lógica AND. Por su parte, 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 distribuyen automáticamente a los clientes de la API suscritos si se crea un ticket con:
+ nivel de `priority` `high` o `medium`
AND
+ nivel de `severity` mayor o igual que `7` (`ge`)
OR
+ ticket de `classification` con la definición de `Security`
AND
+ asignación de `group` establecida en `admin` o `operators`
![\[Ejemplo que muestra una consulta de filtrado de tickets\]](http://docs.aws.amazon.com/es_es/appsync/latest/devguide/images/aws-priority-example.png)
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](https://docs.aws.amazon.com//appsync/latest/devguide/aws-appsync-real-time-data.html#using-subscription-arguments).
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`](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-context-reference-js.html) 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 autorizadores personalizados de grupos de usuarios de Amazon Cognito, OIDC o Lambda para la autorización, puede recuperar información sobre sus usuarios en `context.identity` cuando se establezca la suscripción. 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 `createTicket` mutación:
```
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](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-real-time-data.html#using-subscription-arguments). 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 [JavaScriptresolutores](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-overview-js.html).
## 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:
+ Los filtros mejorados no admiten el filtrado de las listas de objetos de nivel superior. En este caso de uso, los datos publicados de la mutación se ignoran en las suscripciones mejoradas.
+ AWS AppSync admite hasta cinco niveles de anidación. Los filtros más allá del nivel cinco de los campos de esquema de anidamiento se ignoran. Observe la respuesta de GraphQL que aparece a continuación. El campo `continent` en `venue.address.country.metadata.continent` está permitido porque es un nido de nivel cinco. Sin embargo, `financial` en `venue.address.country.metadata.capital.financial` es un nido de nivel seis, por lo que el filtro no funcionará:
```
{
"data": {
"onCreateFilterEvent": {
"venue": {
"address": {
"country": {
"metadata": {
"capital": {
"financial": "New York"
},
"continent" : "North America"
}
},
"state": "WA"
},
"builtYear": 2023
},
"private": false,
}
}
}
```