Extensiones

nota

Ahora admitimos de forma básica el tiempo de ejecución APPSYNC_JS y su documentación. Considere la opción de utilizar el tiempo de ejecución APPSYNC_JS y sus guías aquí.

$extensions contiene un conjunto de métodos para realizar acciones adicionales en sus solucionadores.

Almacenamiento en caché de extensiones

$extensions.evictFromApiCache(String, String, Object) : Object

Expulsa un elemento de la memoria caché del AWS AppSync servidor. El primer argumento es el nombre de tipo. El segundo argumento es el nombre de campo. El tercer argumento es un objeto que contiene elementos de pares clave-valor que especifican el valor clave de almacenamiento en caché. Debe colocar los elementos del objeto en el mismo orden que las claves de almacenamiento en caché del elemento cachingKey del solucionador almacenado en caché.

nota

Esta utilidad solo funciona para mutaciones, no para consultas.

Almacenamiento en caché de extensiones

$extensions.evictFromApiCache(String, String, Object) : Object

Expulsa un elemento de la memoria caché del AWS AppSync servidor. El primer argumento es el nombre de tipo. El segundo argumento es el nombre de campo. El tercer argumento es un objeto que contiene elementos de pares clave-valor que especifican el valor clave de almacenamiento en caché. Debe colocar los elementos del objeto en el mismo orden que las claves de almacenamiento en caché del elemento cachingKey del solucionador almacenado en caché.

nota

Esta utilidad solo funciona para mutaciones, no para consultas.

Extensiones de suscripción

$extensions.setSubscriptionFilter(filterJsonObject)

Define filtros de suscripción mejorados. Cada evento de notificación de suscripción se evalúa con respecto a los filtros de suscripción proporcionados y envía notificaciones a los clientes si todos los filtros se evalúan como true. El argumento es filterJsonObject, tal y como se describe a la siguiente sección.

nota

Puede utilizar este método de extensión solo en las plantillas de mapeo de respuestas de un solucionador de suscripción.

$extensions.setSubscriptionInvalidationFilter(filterJsonObject)

Define los filtros de invalidación de suscripciones. Los filtros de suscripción se evalúan con respecto a la carga de invalidación y, a continuación, invalidan una suscripción determinada si los filtros se evalúan como true. El argumento es filterJsonObject, tal y como se describe a la siguiente sección.

nota

Puede utilizar este método de extensión solo en las plantillas de mapeo de respuestas de un solucionador de suscripción.

$extensions.invalidateSubscriptions(invalidationJsonObject)

Se utiliza para iniciar la invalidación de una suscripción a partir de una mutación. El argumento es invalidationJsonObject, tal y como se describe a la siguiente sección.

nota

Esta extensión solo se puede usar en las plantillas de mapeo de respuestas de los solucionadores de mutaciones.

Solo puede usar como máximo cinco llamadas al método $extensions.invalidateSubscriptions() únicas en una sola solicitud. Si supera este límite, recibirá un error de GraphQL.

Extensiones de suscripción

$extensions.setSubscriptionFilter(filterJsonObject)

Define filtros de suscripción mejorados. Cada evento de notificación de suscripción se evalúa con respecto a los filtros de suscripción proporcionados y envía notificaciones a los clientes si todos los filtros se evalúan como true. El argumento es filterJsonObject, tal y como se describe a la siguiente sección.

nota

Puede utilizar este método de extensión solo en las plantillas de mapeo de respuestas de un solucionador de suscripción.

$extensions.setSubscriptionInvalidationFilter(filterJsonObject)

Define los filtros de invalidación de suscripciones. Los filtros de suscripción se evalúan con respecto a la carga de invalidación y, a continuación, invalidan una suscripción determinada si los filtros se evalúan como true. El argumento es filterJsonObject, tal y como se describe a la siguiente sección.

nota

Puede utilizar este método de extensión solo en las plantillas de mapeo de respuestas de un solucionador de suscripción.

$extensions.invalidateSubscriptions(invalidationJsonObject)

Se utiliza para iniciar la invalidación de una suscripción a partir de una mutación. El argumento es invalidationJsonObject, tal y como se describe a la siguiente sección.

nota

Esta extensión solo se puede usar en las plantillas de mapeo de respuestas de los solucionadores de mutaciones.

Solo puede usar como máximo cinco llamadas al método $extensions.invalidateSubscriptions() únicas en una sola solicitud. Si supera este límite, recibirá un error de GraphQL.

Argumento: filterJsonObject

El objeto JSON define los filtros de suscripción o invalidación. Es una matriz de filtros en un filterGroup. Cada filtro es una colección de filtros individuales.

{
    "filterGroup": [
        {
           "filters" : [
                 {
                    "fieldName" : "userId",
                    "operator" : "eq",
                    "value" : 1
                }
           ]
           
        },
        {
           "filters" : [
                {
                    "fieldName" : "group",
                    "operator" : "in",
                    "value" : ["Admin", "Developer"]
                }
           ]
           
        }
    ]
}

Cada filtro tiene tres atributos:

• fieldName: campo de esquema de GraphQL.

• operator: tipo de operador.

• value: valores que se van a comparar con el valor fieldName de notificación de suscripción.

A continuación se muestra un ejemplo de asignación de estos atributos:

{
 "fieldName" : "severity",
 "operator" : "le",
 "value" : $context.result.severity
}

Campo: fieldName

El tipo de cadena fieldName hace referencia a un campo definido en el esquema de GraphQL que coincide con el fieldName en la carga útil de notificaciones de suscripción. Cuando se encuentra una coincidencia, el value del campo de esquema de GraphQL se compara con el value del filtro de notificaciones de suscripción. En el siguiente ejemplo, el filtro fieldName coincide con el campo service definido en un tipo de GraphQL determinado. Si la carga útil de notificaciones contiene un campo service con un value equivalente a AWS AppSync, el filtro se evalúa como true:

{
 "fieldName" : "service",
 "operator" : "eq",
 "value" : "AWS AppSync"
}

Campo: valor

El valor puede ser de un tipo diferente según el operador:

• Un solo número o booleano

  • Ejemplos de cadena: "test" y "service"

  • Ejemplos de número: 1, 2 y 45.75

  • Ejemplos de booleano: true y false

• Pares de números o cadenas

  • Ejemplo de par de cadenas: ["test1","test2"] y ["start","end"]

  • Ejemplo de par de números: [1,4], [67,89] y [12.45, 95.45]

• Matrices de números o cadenas

  • Ejemplo de matriz de cadenas: ["test1","test2","test3","test4","test5"]

  • Ejemplo de matriz de números: [1,2,3,4,5] y [12.11,46.13,45.09,12.54,13.89]

Campo: operador

Una cadena que distingue entre mayúsculas y minúsculas con los siguientes valores posibles:

Operador	Descripción	Tipos de valor posibles
eq	Igualdad	entero, flotante, cadena, booleano
¿Uno	Desigualdad	entero, flotante, cadena, booleano
le	Menor que o igual a	entero, flotante, cadena
lt	Menor que	entero, flotante, cadena
edad	Mayor que o igual a	entero, flotante, cadena
gt	Mayor que	entero, flotante, cadena
contains	Comprueba si hay una subsecuencia o un valor en el conjunto.	entero, flotante, cadena
no contiene	Comprueba la ausencia de una subsecuencia o la ausencia de un valor en el conjunto.	entero, flotante, cadena
Empieza con	Comprueba si hay un prefijo.	cadena
in	Comprueba si hay elementos coincidentes en la lista.	Matriz de números enteros, flotantes o cadenas
notIn	Comprueba si hay elementos coincidentes que no están en la lista.	Matriz de números enteros, flotantes o cadenas
entre	Entre dos valores	entero, flotante, cadena
Contiene cualquier	Contiene elementos comunes	entero, flotante, cadena

En la siguiente tabla se describe la utilización de cada operador en la notificación de suscripción.

eq (equal)

El operador eq se evalúa como true si el valor del campo de notificación de suscripción coincide y es igual al valor del filtro de forma estricta. En el siguiente ejemplo, el filtro se evalúa como true si la notificación de suscripción tiene un campo service con el valor equivalente a AWS AppSync.

Tipos de valor posibles: entero, flotante, cadena y booleano

{
 "fieldName" : "service",
 "operator" : "eq",
 "value" : "AWS AppSync"
}

ne (not equal)

El operador ne se evalúa como true si el valor del campo de notificación de suscripción es diferente al valor del filtro. En el siguiente ejemplo, el filtro se evalúa como true si la notificación de suscripción tiene un campo service con un valor diferente a AWS AppSync.

Tipos de valor posibles: entero, flotante, cadena y booleano

{
 "fieldName" : "service",
 "operator" : "ne",
 "value" : "AWS AppSync"
}

le (less or equal)

El operador le se evalúa como true si el valor del campo de notificación de suscripción es inferior o igual al valor del filtro. En el siguiente ejemplo, el filtro se evalúa como true si la notificación de suscripción tiene un campo size con un valor inferior o igual a 5.

Tipos de valor posibles: entero, flotante y cadena

{
 "fieldName" : "size",
 "operator" : "le",
 "value" : 5
}

lt (less than)

El operador lt se evalúa como true si el valor del campo de notificación de suscripción es inferior al valor del filtro. En el siguiente ejemplo, el filtro se evalúa como true si la notificación de suscripción tiene un campo size con un valor inferior a 5.

Tipos de valor posibles: entero, flotante y cadena

{
 "fieldName" : "size",
 "operator" : "lt",
 "value" : 5
}

ge (greater or equal)

El operador ge se evalúa como true si el valor del campo de notificación de suscripción es superior o igual al valor del filtro. En el siguiente ejemplo, el filtro se evalúa como true si la notificación de suscripción tiene un campo size con un valor superior o igual a 5.

Tipos de valor posibles: entero, flotante y cadena

{
 "fieldName" : "size",
 "operator" : "ge",
 "value" : 5
}

gt (greater than)

El operador gt se evalúa como true si el valor del campo de notificación de suscripción es superior al valor del filtro. En el siguiente ejemplo, el filtro se evalúa como true si la notificación de suscripción tiene un campo size con un valor superior a 5.

Tipos de valor posibles: entero, flotante y cadena

{
 "fieldName" : "size",
 "operator" : "gt",
 "value" : 5
}

contains

El operador contains comprueba si hay una subcadena, una subsecuencia o un valor en un conjunto o un único elemento. Un filtro con el operador contains se evalúa como true si el valor del campo de notificación de suscripción contiene el valor del filtro. En el siguiente ejemplo, el filtro se evalúa como true si la notificación de suscripción tiene un campo seats con el valor de matriz que contiene el valor 10.

Tipos de valor posibles: entero, flotante y cadena

{
 "fieldName" : "seats",
 "operator" : "contains",
 "value" : 10
}

En otro ejemplo, el filtro se evalúa como true si la notificación de suscripción tiene un campo event con launch como subcadena.

{
 "fieldName" : "event",
 "operator" : "contains",
 "value" : "launch"
}

notContains

El operador notContains busca la ausencia de una subcadena, una subsecuencia o un valor en un conjunto o un único elemento. El filtro con el operador notContains se evalúa como true si el valor del campo de notificación de suscripción no contiene el valor del filtro. En el siguiente ejemplo, el filtro se evalúa como true si la notificación de suscripción tiene un campo seats con el valor de matriz que no contiene el valor 10.

Tipos de valor posibles: entero, flotante y cadena

{
 "fieldName" : "seats",
 "operator" : "notContains",
 "value" : 10
}

En otro ejemplo, el filtro se evalúa como true si la notificación de suscripción tiene un valor de campo event sin launch como su subsecuencia.

{
 "fieldName" : "event",
 "operator" : "notContains",
 "value" : "launch"
}

beginsWith

El operador beginsWith comprueba si hay un prefijo en una cadena. El filtro que contiene el operador beginsWith se evalúa como true si el valor del campo de notificación de suscripción comienza con el valor del filtro. En el siguiente ejemplo, el filtro se evalúa como true si la notificación de suscripción tiene un campo service con un valor que comienza con AWS.

Tipo de valor posible: cadena

{
 "fieldName" : "service",
 "operator" : "beginsWith",
 "value" : "AWS"
}

in

El operador in comprueba si hay elementos coincidentes en una matriz. El filtro que contiene el operador in se evalúa como true si el valor del campo de notificación de suscripción existe en una matriz. En el siguiente ejemplo, el filtro se evalúa como true si la notificación de suscripción tiene un campo severity con uno de los valores presentes en la matriz: [1,2,3].

Tipo de valor posible: matriz de enteros, flotantes o cadenas

{
 "fieldName" : "severity",
 "operator" : "in",
 "value" : [1,2,3]
}

notIn

El operador notIn comprueba si faltan elementos en una matriz. El filtro que contiene el operador notIn se evalúa como true si el valor del campo de notificación de suscripción no existe en la matriz. En el siguiente ejemplo, el filtro se evalúa como true si la notificación de suscripción tiene un campo severity con uno de los valores no presentes en la matriz: [1,2,3].

Tipo de valor posible: matriz de enteros, flotantes o cadenas

{
 "fieldName" : "severity",
 "operator" : "notIn",
 "value" : [1,2,3]
}

between

El operador between comprueba si hay valores entre dos números o cadenas. El filtro que contiene el operador between se evalúa como true si el valor del campo de notificación de suscripción se encuentra entre el par de valores del filtro. En el siguiente ejemplo, el filtro se evalúa como true si la notificación de suscripción tiene un campo severity con los valores 2, 3 y 4.

Tipos de valor posibles: par de enteros, flotantes o cadenas

{
 "fieldName" : "severity",
 "operator" : "between",
 "value" : [1,5]
}

containsAny

El operador containsAny comprueba si hay elementos en matrices. Un filtro con el operador containsAny se evalúa como true si la intersección del valor de conjunto de campos de notificación de suscripción y el valor de conjunto de filtros no está vacía. En el siguiente ejemplo, el filtro se evalúa como true si la notificación de suscripción tiene un campo seats con un valor de matriz que contiene 10 o 15. Esto significa que el filtro se evaluaría como true si la notificación de suscripción tuviera un valor de campo seats de [10,11] o [15,20,30].

Tipos de valor posibles: entero, flotante o cadena

{
 "fieldName" : "seats",
 "operator" : "containsAny",
 "value" : [10, 15]
}

Lógica AND

Puede combinar varios filtros mediante la lógica AND definiendo varias entradas dentro del objeto filters de la matriz filterGroup. En el siguiente ejemplo, los filtros se evalúan como true si la notificación de suscripción tiene un campo userId con un valor equivalente a 1 Y un valor de campo group de Admin o Developer.

{
    "filterGroup": [
        {
           "filters" : [
                 {
                    "fieldName" : "userId",
                    "operator" : "eq",
                    "value" : 1
                },
                {
                    "fieldName" : "group",
                    "operator" : "in",
                    "value" : ["Admin", "Developer"]
                }
           ]
           
        }
    ]
}

Lógica OR

Puede combinar varios filtros mediante la lógica OR definiendo varios objetos de filtro dentro de la matriz filterGroup. En el siguiente ejemplo, los filtros se evalúan como true si la notificación de suscripción tiene un campo userId con un valor equivalente a 1 O un valor de campo group de Admin o Developer.

{
    "filterGroup": [
        {
           "filters" : [
                 {
                    "fieldName" : "userId",
                    "operator" : "eq",
                    "value" : 1
                }
           ]
           
        },
        {
           "filters" : [
                {
                    "fieldName" : "group",
                    "operator" : "in",
                    "value" : ["Admin", "Developer"]
                }
           ]
           
        }
    ]
}

Excepciones

Tenga en cuenta que existen varias restricciones del uso de filtros:

• En el objeto filters, puede haber un máximo de cinco elementos fieldName únicos por filtro. Esto significa que puede combinar un máximo de cinco objetos fieldName individuales mediante la lógica AND.

• Puede haber un máximo de veinte valores para el operador containsAny.

• Puede haber un máximo de cinco valores para los operadores in y notIn.

• Cada cadena puede tener un máximo de 256 caracteres.

• Cada comparación entre cadenas distingue entre mayúsculas y minúsculas.

• El filtrado de objetos anidados permite hasta cinco niveles anidados de filtrado.

• Cada filterGroup puede tener un máximo de 10 filters. Esto significa que puede combinar un máximo de 10 filters mediante la lógica OR.

  • El operador in es un caso especial de lógica OR. En el siguiente ejemplo, hay dos filters:

    {
        "filterGroup": [
            {
               "filters" : [
                     {
                        "fieldName" : "userId",
                        "operator" : "eq",
                        "value" : 1
                    },
                    {
                        "fieldName" : "group",
                        "operator" : "in",
                        "value" : ["Admin", "Developer"]
                    }
               ]  
            }
        ]
    }

    El grupo de filtros anterior se evalúa de la siguiente manera y cuenta para el límite máximo de filtros:

    {
        "filterGroup": [
            {
               "filters" : [
                     {
                        "fieldName" : "userId",
                        "operator" : "eq",
                        "value" : 1
                    },
                    {
                        "fieldName" : "group",
                        "operator" : "eq",
                        "value" : "Admin"
                    }
               ]  
            },
            {
               "filters" : [
                     {
                        "fieldName" : "userId",
                        "operator" : "eq",
                        "value" : 1
                    },
                    {
                        "fieldName" : "group",
                        "operator" : "eq",
                        "value" : "Developer"
                    }
               ]  
            }
        ]
    }

Argumento: invalidationJsonObject

El invalidationJsonObject define lo siguiente:

• subscriptionField: suscripción del esquema de GraphQL a invalidar. Se baraja la posibilidad de invalidar una suscripción única, definida como cadena en el subscriptionField.

• payload: lista de pares clave-valor que se utiliza como entrada para la invalidación de suscripciones si el filtro de invalidación se evalúa como true en comparación con sus valores.

  En el siguiente ejemplo se invalida a los clientes suscritos y conectados que utilizan la suscripción onUserDelete cuando el filtro de invalidación definido en el solucionador de suscripción se evalúa como true en comparación con el valor payload.

  $extensions.invalidateSubscriptions({
          "subscriptionField": "onUserDelete",
          "payload": {
                  "group": "Developer"
                  "type" : "Full-Time"
        }
      })