Definition erweiterter Abonnementfilter in AWS AppSync

In AWS AppSync können Sie die Geschäftslogik für die Datenfilterung im Backend direkt in den GraphQL-API-Abonnement-Resolvern definieren und aktivieren, indem Sie Filter verwenden, die zusätzliche logische Operatoren unterstützen. Im Gegensatz zu den Abonnementargumenten, die in der Abonnementabfrage im Client definiert sind, können Sie diese Filter konfigurieren. Weitere Hinweise zur Verwendung von Abonnementargumenten finden Sie unterAbonnementargumente verwenden. Eine Liste der Operatoren finden Sie unterAWS AppSync Referenz zum Hilfsprogramm für Resolver-Mapping-Vorlagen.

Für die Zwecke dieses Dokuments unterteilen wir die Echtzeit-Datenfilterung in die folgenden Kategorien:

• Grundlegendes Filtern — Filterung auf der Grundlage von vom Kunden definierten Argumenten in der Abonnementabfrage.

• Verbesserte Filterung — Filterung auf der Grundlage einer Logik, die zentral im AWS AppSync Service-Backend definiert ist.

In den folgenden Abschnitten wird erklärt, wie erweiterte Abonnementfilter konfiguriert werden und wie sie in der Praxis angewendet werden.

Definieren von Abonnements in Ihrem GraphQL-Schema

Um erweiterte Abonnementfilter zu verwenden, definieren Sie das Abonnement im GraphQL-Schema und definieren dann den erweiterten Filter mithilfe einer Filtererweiterung. Um zu veranschaulichen, wie die erweiterte Abonnementfilterung funktioniert AWS AppSync, verwenden Sie als Beispiel das folgende GraphQL-Schema, das eine Ticket-Management-System-API definiert:

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
	

Angenommen, Sie erstellen eine NONE Datenquelle für Ihre API und fügen dann mithilfe dieser Datenquelle einen Resolver an die createTicket Mutation an. Ihre Handler könnten so aussehen:

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

Anmerkung

Verbesserte Filter werden im Handler des GraphQL-Resolvers in einem bestimmten Abonnement aktiviert. Weitere Informationen finden Sie in der Resolver-Referenz.

Um das Verhalten des erweiterten Filters zu implementieren, müssen Sie die extensions.setSubscriptionFilter() Funktion verwenden, um einen Filterausdruck zu definieren, der anhand veröffentlichter Daten aus einer GraphQL-Mutation ausgewertet wird, an der die abonnierten Clients interessiert sein könnten. Weitere Informationen zu den Filtererweiterungen finden Sie unter Erweiterungen.

Im folgenden Abschnitt wird erklärt, wie Sie Filtererweiterungen verwenden, um erweiterte Filter zu implementieren.

Erstellen erweiterter Abonnementfilter mithilfe von Filtererweiterungen

Verbesserte Filter werden in JSON in den Antworthandler der Resolver des Abonnements geschrieben. Filter können in einer Liste zusammengefasst werden, die als a filterGroup bezeichnet wird. Filter werden mithilfe von mindestens einer Regel definiert, die jeweils Felder, Operatoren und Werte enthält. Definieren wir einen neuen ResolveronSpecialTicketCreated, der einen erweiterten Filter einrichtet. Sie können mehrere Regeln in einem Filter konfigurieren, die mithilfe der UND-Logik ausgewertet werden, während mehrere Filter in einer Filtergruppe mithilfe der OR-Logik ausgewertet werden:

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

Basierend auf den im vorherigen Beispiel definierten Filtern werden wichtige Tickets automatisch an abonnierte API-Clients weitergeleitet, wenn ein Ticket erstellt wird mit:

• priorityStufe oder high medium

  AND

• severityStufe größer oder gleich 7 (ge)

ODER

• classificationTicket gesetzt auf Security

  AND

• groupDie Zuweisung ist auf admin oder gesetzt operators

Im Abonnement-Resolver definierte Filter (erweiterte Filterung) haben Vorrang vor Filtern, die nur auf Abonnementargumenten basieren (grundlegende Filterung). Weitere Informationen zur Verwendung von Abonnementargumenten finden Sie unter Abonnementargumente verwenden).

Wenn ein Argument im GraphQL-Schema des Abonnements definiert und erforderlich ist, erfolgt die Filterung auf der Grundlage des angegebenen Arguments nur, wenn das Argument in der Regel in der Methode des Resolvers definiert istextensions.setSubscriptionFilter(). Wenn der Abonnement-Resolver jedoch keine extensions Filtermethoden enthält, werden die im Client definierten Argumente nur für die grundlegende Filterung verwendet. Sie können die Standardfilterung und die erweiterte Filterung nicht gleichzeitig verwenden.

Sie können die contextVariable in der Filtererweiterungslogik des Abonnements verwenden, um auf Kontextinformationen zur Anfrage zuzugreifen. Wenn Sie beispielsweise Amazon Cognito User Pools, OIDC oder benutzerdefinierte Lambda-Autorisierer für die Autorisierung verwenden, können Sie Informationen über Ihre Benutzer abrufen, sobald das Abonnement eingerichtet wird. context.identity Sie können diese Informationen verwenden, um Filter auf der Grundlage der Identität Ihrer Benutzer einzurichten.

Gehen Sie nun davon aus, dass Sie das erweiterte Filterverhalten für implementieren möchtenonGroupTicketCreated. Für das onGroupTicketCreated Abonnement ist ein obligatorischer group Name als Argument erforderlich. Bei der Erstellung wird den Tickets automatisch ein pending Status zugewiesen. Sie können einen Abonnementfilter einrichten, um nur neu erstellte Tickets zu erhalten, die zu der angegebenen Gruppe gehören:

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

Wenn Daten mithilfe einer Mutation wie im folgenden Beispiel veröffentlicht werden:

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

Abonnierte Kunden warten darauf, dass die Daten automatisch weitergeleitet werden, WebSockets sobald ein Ticket mit der createTicket Mutation erstellt wird:

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

Clients können ohne Argumente abonniert werden, da die Filterlogik im AWS AppSync Service mit erweiterter Filterung implementiert ist, wodurch der Client-Code vereinfacht wird. Clients erhalten Daten nur, wenn die definierten Filterkriterien erfüllt sind.

Definition erweiterter Filter für verschachtelte Schemafelder

Sie können die erweiterte Abonnementfilterung verwenden, um verschachtelte Schemafelder zu filtern. Angenommen, wir haben das Schema aus dem vorherigen Abschnitt geändert, um Standort- und Adresstypen einzubeziehen:

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

Mit diesem Schema können Sie ein . Trennzeichen verwenden, um die Verschachtelung darzustellen. Im folgenden Beispiel wird eine Filterregel für ein verschachteltes Schemafeld unter hinzugefügt. location.address.country Das Abonnement wird ausgelöst, wenn die Adresse des Tickets wie folgt gesetzt USA ist:

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

Steht im obigen Beispiel location für Verschachtelungsebene eins, address für Verschachtelungsebene zwei und country für Verschachtelungsebene drei, die alle durch das Trennzeichen getrennt sind. .

Sie können dieses Abonnement testen, indem Sie die folgende Mutation verwenden: createTicket

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

Definition erweiterter Filter vom Client aus

Sie können die grundlegende Filterung in GraphQL mit Abonnementargumenten verwenden. Der Client, der den Aufruf in der Abonnementabfrage durchführt, definiert die Werte der Argumente. Wenn erweiterte Filter in einem AWS AppSync Abonnement-Resolver mit der extensions Filterung aktiviert werden, haben die im Resolver definierten Backend-Filter Vorrang und Priorität.

Konfigurieren Sie dynamische, vom Client definierte erweiterte Filter mithilfe eines Arguments im Abonnement. filter Wenn Sie diese Filter konfigurieren, müssen Sie das GraphQL-Schema aktualisieren, um das neue Argument widerzuspiegeln:

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

Der Client kann dann eine Abonnementabfrage wie im folgenden Beispiel senden:

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

Sie können die Abfragevariable wie im folgenden Beispiel konfigurieren:

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

Das util.transform.toSubscriptionFilter() Resolver-Hilfsprogramm kann in der Vorlage für die Zuordnung von Abonnementantworten implementiert werden, um den im Abonnementargument definierten Filter für jeden Client anzuwenden:

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

Mit dieser Strategie können Kunden ihre eigenen Filter definieren, die eine erweiterte Filterlogik und zusätzliche Operatoren verwenden. Filter werden zugewiesen, wenn ein bestimmter Client die Abonnementabfrage in einer sicheren WebSocket Verbindung aufruft. Weitere Informationen zum Transformationsprogramm für erweiterte Filterung, einschließlich des Formats der Payload der filter Abfragevariablen, finden Sie unter Übersicht über JavaScript Resolver.

Zusätzliche erweiterte Filtereinschränkungen

Im Folgenden sind mehrere Anwendungsfälle aufgeführt, in denen erweiterte Filter zusätzlichen Einschränkungen unterliegen:

• Verbesserte Filter unterstützen keine Filterung für Objektlisten der obersten Ebene. In diesem Anwendungsfall werden veröffentlichte Daten aus der Mutation bei erweiterten Abonnements ignoriert.

• AWS AppSync unterstützt bis zu fünf Verschachtelungsebenen. Filter für Schemafelder, die nach der Verschachtelungsebene fünf liegen, werden ignoriert. Nehmen Sie die unten stehende GraphQL-Antwort. Das continent Eingabefeld venue.address.country.metadata.continent ist zulässig, da es sich um ein Nest der Stufe 5 handelt. Da venue.address.country.metadata.capital.financial es financial sich jedoch um ein Nest der Stufe sechs handelt, funktioniert der Filter nicht:

  {
      "data": {
          "onCreateFilterEvent": {
              "venue": {
                  "address": {
                      "country": {
                          "metadata": {
                              "capital": {
                                  "financial": "New York"
                              },
                              "continent" : "North America"
                          }
                      },
                      "state": "WA"
                  },
                  "builtYear": 2023
              },
              "private": false,
          }
      }
  }