Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.
# Definition erweiterter Abonnementfilter in AWS AppSync
**Wichtig**
Ab dem 13. März 2025 können Sie WebSockets mithilfe von AWS AppSync Events eine PubSub Echtzeit-API erstellen. Weitere Informationen finden Sie unter [Ereignisse veröffentlichen über WebSocket](https://docs.aws.amazon.com/appsync/latest/eventapi/publish-websocket.html) im *AWS AppSync Events Developer Guide*.
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 unter[Abonnementargumente verwenden](aws-appsync-real-time-data.md#using-subscription-arguments). Eine Liste der Operatoren finden Sie unter[AWS AppSync Referenz zum Hilfsprogramm für Resolver-Mapping-Vorlagen](resolver-util-reference.md).
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](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html).
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.](https://docs.aws.amazon.com//appsync/latest/devguide/extensions-js.html)
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 Resolver`onSpecialTicketCreated`, 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:
+ `priority`Stufe oder `high` `medium`
AND
+ `severity`Stufe größer oder gleich `7` (`ge`)
ODER
+ `classification`Ticket gesetzt auf `Security`
AND
+ `group`Die Zuweisung ist auf `admin` oder gesetzt `operators`
![\[Beispiel für eine Ticketfilterabfrage\]](http://docs.aws.amazon.com/de_de/appsync/latest/devguide/images/aws-priority-example.png)
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](https://docs.aws.amazon.com//appsync/latest/devguide/aws-appsync-real-time-data.html#using-subscription-arguments)).
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 ist`extensions.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 [`context`Variable](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-context-reference-js.html) 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öchten`onGroupTicketCreated`. 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](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-real-time-data.html#using-subscription-arguments) 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 [JavaScriptResolver](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-overview-js.html).
## 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,
}
}
}
```