Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Définition de filtres d'abonnement améliorés dans AWS AppSync

Dans AWS AppSync, vous pouvez définir et activer la logique métier pour le filtrage des données sur le backend directement dans les résolveurs d'abonnement à l'API GraphQL à l'aide de filtres prenant en charge des opérateurs logiques supplémentaires. Vous pouvez configurer ces filtres, à la différence des arguments d'abonnement définis dans la requête d'abonnement du client. Pour plus d'informations sur l'utilisation des arguments d'abonnement, consultezUtilisation d'arguments d'abonnement. Pour obtenir la liste des opérateurs, consultezAWS AppSync référence de l'utilitaire du modèle de mappage du résolveur.

Aux fins de ce document, nous répartissons le filtrage des données en temps réel dans les catégories suivantes :

Les sections suivantes expliquent comment configurer des filtres d'abonnement améliorés et montrent leur utilisation pratique.

Définition des abonnements dans votre schéma GraphQL

Pour utiliser des filtres d'abonnement améliorés, vous définissez l'abonnement dans le schéma GraphQL, puis vous définissez le filtre amélioré à l'aide d'une extension de filtrage. Pour illustrer le fonctionnement du filtrage amélioré des abonnements AWS AppSync, utilisez le schéma GraphQL suivant, qui définit l'API d'un système de gestion des tickets, à titre d'exemple :

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
	

Supposons que vous créiez une source de NONE données pour votre API, puis que vous associiez un résolveur à la createTicket mutation à l'aide de cette source de données. Vos gestionnaires peuvent ressembler à ceci :

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

Pour implémenter le comportement du filtre amélioré, vous devez utiliser la extensions.setSubscriptionFilter() fonction pour définir une expression de filtre évaluée par rapport aux données publiées à partir d'une mutation GraphQL susceptible d'intéresser les clients abonnés. Pour plus d'informations sur les extensions de filtrage, voir Extensions.

La section suivante explique comment utiliser les extensions de filtrage pour implémenter des filtres améliorés.

Création de filtres d'abonnement améliorés à l'aide d'extensions de filtrage

Les filtres améliorés sont écrits en JSON dans le gestionnaire de réponses des résolveurs de l'abonnement. Les filtres peuvent être regroupés dans une liste appeléefilterGroup. Les filtres sont définis à l'aide d'au moins une règle, chacune comportant des champs, des opérateurs et des valeurs. Définissons un nouveau résolveur onSpecialTicketCreated qui configure un filtre amélioré. Vous pouvez configurer plusieurs règles dans un filtre qui sont évaluées à l'aide de la logique ET, tandis que plusieurs filtres d'un groupe de filtres sont évalués à l'aide de la logique OU :

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

Sur la base des filtres définis dans l'exemple précédent, les tickets importants sont automatiquement transmis aux clients API abonnés si un ticket est créé avec :

OU

Les filtres définis dans le résolveur d'abonnement (filtrage amélioré) ont priorité sur le filtrage basé uniquement sur les arguments de l'abonnement (filtrage de base). Pour plus d'informations sur l'utilisation des arguments d'abonnement, voir Utilisation des arguments d'abonnement).

Si un argument est défini et requis dans le schéma GraphQL de l'abonnement, le filtrage basé sur l'argument donné n'a lieu que si l'argument est défini en tant que règle dans la méthode du extensions.setSubscriptionFilter() résolveur. Toutefois, s'il n'existe aucune méthode de extensions filtrage dans le résolveur d'abonnement, les arguments définis dans le client ne sont utilisés que pour le filtrage de base. Vous ne pouvez pas utiliser simultanément le filtrage de base et le filtrage amélioré.

Vous pouvez utiliser la context variable dans la logique d'extension de filtre de l'abonnement pour accéder aux informations contextuelles relatives à la demande. Par exemple, lorsque vous utilisez les groupes d'utilisateurs Amazon Cognito, OIDC ou les autorisations personnalisées Lambda pour l'autorisation, vous pouvez récupérer des informations sur vos utilisateurs au context.identity moment de l'établissement de l'abonnement. Vous pouvez utiliser ces informations pour établir des filtres en fonction de l'identité de vos utilisateurs.

Supposons maintenant que vous souhaitiez implémenter le comportement de filtre amélioré pouronGroupTicketCreated. L'onGroupTicketCreatedabonnement nécessite un group nom obligatoire comme argument. Une fois créés, les tickets se voient automatiquement attribuer un pending statut. Vous pouvez configurer un filtre d'abonnement pour ne recevoir que les tickets nouvellement créés qui appartiennent au groupe fourni :

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

Lorsque les données sont publiées à l'aide d'une mutation, comme dans l'exemple suivant :

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

Les clients abonnés écoutent les données qui seront automatiquement WebSockets transmises dès qu'un ticket est créé avec la createTicket mutation :

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

Les clients peuvent être abonnés sans arguments car la logique de filtrage est implémentée dans le AWS AppSync service avec un filtrage amélioré, ce qui simplifie le code client. Les clients reçoivent des données uniquement si les critères de filtre définis sont remplis.

Définition de filtres améliorés pour les champs de schéma imbriqués

Vous pouvez utiliser un filtrage d'abonnement amélioré pour filtrer les champs de schéma imbriqués. Supposons que nous ayons modifié le schéma de la section précédente pour inclure les types d'emplacement et d'adresse :

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

Avec ce schéma, vous pouvez utiliser un . séparateur pour représenter l'imbrication. L'exemple suivant ajoute une règle de filtre pour un champ de schéma imbriqué en dessouslocation.address.country. L'abonnement sera déclenché si l'adresse du billet est définie comme suit 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;
}

Dans l'exemple ci-dessus, location représente le niveau d'imbrication un, address représente le niveau d'imbrication deux et country représente le niveau d'imbrication trois, qui sont tous séparés par le séparateur. .

Vous pouvez tester cet abonnement en utilisant la createTicket mutation :

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

Définition de filtres améliorés depuis le client

Vous pouvez utiliser le filtrage de base dans GraphQL avec des arguments d'abonnement. Le client qui effectue l'appel dans la requête d'abonnement définit les valeurs des arguments. Lorsque les filtres améliorés sont activés dans un résolveur AWS AppSync d'abonnement avec le extensions filtrage, les filtres principaux définis dans le résolveur ont priorité et priorité.

Configurez des filtres améliorés dynamiques définis par le client à l'aide d'un filter argument dans l'abonnement. Lorsque vous configurez ces filtres, vous devez mettre à jour le schéma GraphQL pour refléter le nouvel argument :

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

Le client peut ensuite envoyer une requête d'abonnement comme dans l'exemple suivant :

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

Vous pouvez configurer la variable de requête comme dans l'exemple suivant :

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

L'utilitaire de util.transform.toSubscriptionFilter() résolution peut être implémenté dans le modèle de mappage des réponses d'abonnement pour appliquer le filtre défini dans l'argument d'abonnement pour chaque client :

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

Grâce à cette stratégie, les clients peuvent définir leurs propres filtres qui utilisent une logique de filtrage améliorée et des opérateurs supplémentaires. Les filtres sont attribués lorsqu'un client donné appelle la requête d'abonnement dans une WebSocket connexion sécurisée. Pour plus d'informations sur l'utilitaire de transformation pour un filtrage amélioré, notamment sur le format de la charge utile de la variable de filter requête, consultez la section Présentation JavaScript des résolveurs.

Restrictions de filtrage supplémentaires améliorées

Vous trouverez ci-dessous plusieurs cas d'utilisation dans lesquels des restrictions supplémentaires sont imposées aux filtres améliorés :