Cancelando a assinatura de WebSocket conexões usando filtros no AWS AppSync

Importante

A partir de 13 de março de 2025, você pode criar uma PubSub API em tempo real baseada no WebSockets uso de AWS AppSync Eventos. Para obter mais informações, consulte Publicar eventos WebSocket no Guia do desenvolvedor de AWS AppSync eventos.

Em AWS AppSync, você pode cancelar a assinatura à força e fechar (invalidar) uma WebSocket conexão de um cliente conectado com base em uma lógica de filtragem específica. Isso será útil em cenários relacionados à autorização, como quando você remove um usuário de um grupo.

A invalidação da assinatura ocorre em resposta a uma carga definida em uma mutação. Recomendamos que você trate as mutações usadas para invalidar conexões de assinatura como operações administrativas em sua API e permissões de escopo de modo adequado, limitando o uso a um usuário administrador, grupo ou serviço de back-end. Por exemplo, usando diretivas de autorização de esquema, como @aws_auth(cognito_groups: ["Administrators"]) ou @aws_iam. Para obter mais informações, consulte Usar modos de autorização adicionais.

Os filtros de invalidação usam a mesma sintaxe e lógica dos filtros de assinatura aprimorados. Defina esses filtros usando os seguintes utilitários:

• extensions.invalidateSubscriptions() — Definido no manipulador de resposta do resolvedor do GraphQL para uma mutação.

• extensions.setSubscriptionInvalidationFilter() — Definido no manipulador de resposta do resolvedor do GraphQL das assinaturas vinculadas à mutação.

Para obter mais informações sobre extensões de filtragem de invalidação, consulte a visão geral dos JavaScriptresolvedores.

Usar a invalidação da assinatura

Para ver como funciona a invalidação de assinatura AWS AppSync, use o seguinte esquema do GraphQL:

type User {
  userId: ID!
  groupId: ID!
}
    
type Group {
  groupId: ID!
  name: String!
  members: [ID!]!
}

type GroupMessage {
  userId: ID!
  groupId: ID!
  message: String!
}

type Mutation {
    createGroupMessage(userId: ID!, groupId : ID!, message: String!): GroupMessage
    removeUserFromGroup(userId: ID!, groupId : ID!) : User @aws_iam
}

type Subscription {
    onGroupMessageCreated(userId: ID!, groupId : ID!): GroupMessage
        @aws_subscribe(mutations: ["createGroupMessage"])
}

type Query {
	none: String
}

Defina um filtro de invalidação no código do resolvedor de mutação removeUserFromGroup:

import { extensions } from '@aws-appsync/utils';

export function request(ctx) {
	return { payload: null };
}

export function response(ctx) {
	const { userId, groupId } = ctx.args;
	extensions.invalidateSubscriptions({
		subscriptionField: 'onGroupMessageCreated',
		payload: { userId, groupId },
	});
	return { userId, groupId };
}

Quando a mutação é invocada, os dados definidos no objeto payload são usados para cancelar a assinatura definida em subscriptionField. Um filtro de invalidação também é definido no modelo de mapeamento de resposta da assinatura do onGroupMessageCreated.

Se a extensions.invalidateSubscriptions() carga contiver uma ID que corresponda à IDs do cliente inscrito, conforme definido no filtro, a assinatura correspondente será cancelada. Além disso, a WebSocket conexão está fechada. Defina o código do resolvedor de assinatura para a assinatura onGroupMessageCreated:

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 = { groupId: { eq: ctx.args.groupId } };
	extensions.setSubscriptionFilter(util.transform.toSubscriptionFilter(filter));

	const invalidation = { groupId: { eq: ctx.args.groupId }, userId: { eq: ctx.args.userId } };
	extensions.setSubscriptionInvalidationFilter(util.transform.toSubscriptionFilter(invalidation));

	return null;
}

Observe que o gerenciador de respostas da assinatura pode ter filtros de assinatura e filtros de invalidação definidos ao mesmo tempo.

Por exemplo, suponha que o cliente A inscreva um novo usuário com o ID user-1 no grupo com o ID group-1 usando a seguinte solicitação de assinatura:

onGroupMessageCreated(userId : "user-1", groupId: :"group-1"){...}

AWS AppSync executa o resolvedor de assinaturas, que gera filtros de assinatura e invalidação conforme definido no modelo de mapeamento de onGroupMessageCreated resposta anterior. Para o cliente A, os filtros de assinatura permitem que os dados sejam enviados somente para group-1, e os filtros de invalidação são definidos para user-1 e group-1.

Agora suponha que o cliente B inscreva um usuário com o ID user-2 no grupo com o ID group-2 usando a seguinte solicitação de assinatura:

onGroupMessageCreated(userId : "user-2", groupId: :"group-2"){...}

AWS AppSync executa o resolvedor de assinaturas, que gera filtros de assinatura e invalidação. Para o cliente B, os filtros de assinatura permitem que os dados sejam enviados somente para group-2, e os filtros de invalidação são definidos para user-2 e group-2.

Em seguida, suponha que uma nova mensagem de grupo com o ID message-1 seja criada usando uma solicitação de mutação, como no exemplo a seguir:

createGroupMessage(id: "message-1", groupId :
      "group-1", message: "test message"){...}

Os clientes inscritos que correspondem aos filtros definidos recebem automaticamente a seguinte carga de dados por meio de: WebSockets

{
  "data": {
    "onGroupMessageCreated": {
      "id": "message-1",
      "groupId": "group-1",
      "message": "test message",
    }
  }
}

O cliente A recebe a mensagem porque os critérios de filtragem correspondem ao filtro de assinatura definido. No entanto, o cliente B não recebe a mensagem, pois o usuário não faz parte de group-1. Além disso, a solicitação não corresponde ao filtro de assinatura definido no resolvedor de assinatura.

Por fim, suponha que user-1 seja removido de group-1 usando a seguinte solicitação de mutação:

removeUserFromGroup(userId: "user-1", groupId : "group-1"){...}

A mutação inicia uma invalidação de assinatura, conforme definido no código do manipulador de respostas do extensions.invalidateSubscriptions() resolvedor. AWS AppSync em seguida, cancela a assinatura do cliente A e fecha sua conexão. WebSocket O cliente B não é afetado, pois a carga de invalidação definida na mutação não corresponde ao usuário ou grupo.

Quando AWS AppSync invalida uma conexão, o cliente recebe uma mensagem confirmando que sua assinatura foi cancelada:

{
  "message": "Subscription complete."
}

Usar variáveis de contexto em filtros de invalidação de assinatura

Assim como nos filtros de assinatura aprimorados, você pode usar a variável context na extensão do filtro de invalidação de assinatura para acessar determinados dados.

Por exemplo, é possível configurar um endereço de e-mail como a carga de invalidação na mutação e, em seguida, compará-lo ao atributo de e-mail ou à solicitação de um usuário inscrito autorizado com grupos de usuários do Amazon Cognito ou OpenID Connect. O filtro de invalidação definido no invalidador de assinatura extensions.setSubscriptionInvalidationFilter() verifica se o endereço de e-mail definido pela carga extensions.invalidateSubscriptions() da mutação corresponde ao endereço de e-mail recuperado do token JWT do usuário em context.identity.claims.email, iniciando a invalidação.