Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
# Definizione di filtri di sottoscrizione avanzati in AWS AppSync
**Importante**
A partire dal 13 marzo 2025, puoi creare un' PubSub API in tempo reale basata su WebSockets AWS AppSync Events. Per ulteriori informazioni, consulta [Pubblicare eventi tramite WebSocket](https://docs.aws.amazon.com/appsync/latest/eventapi/publish-websocket.html) nella *AWS AppSync Events Developer Guide*.
Inoltre AWS AppSync, puoi definire e abilitare la logica aziendale per il filtraggio dei dati sul backend direttamente nei resolver di sottoscrizione dell'API GraphQL utilizzando filtri che supportano operatori logici aggiuntivi. È possibile configurare questi filtri, a differenza degli argomenti di sottoscrizione definiti nella query di sottoscrizione nel client. Per ulteriori informazioni sull'utilizzo degli argomenti di sottoscrizione, vedere[Utilizzo degli argomenti di sottoscrizione](aws-appsync-real-time-data.md#using-subscription-arguments). Per un elenco degli operatori, vedere[AWS AppSync riferimento all'utilità del modello di mappatura del resolver](resolver-util-reference.md).
Ai fini di questo documento, suddividiamo il filtraggio dei dati in tempo reale nelle seguenti categorie:
+ **Filtraggio di base**: filtraggio basato su argomenti definiti dal client nella query di sottoscrizione.
+ **Filtraggio avanzato: filtraggio** basato sulla logica definita centralmente nel backend del servizio. AWS AppSync
Le sezioni seguenti spiegano come configurare i filtri di abbonamento avanzati e ne mostrano l'uso pratico.
## Definizione degli abbonamenti nello schema GraphQL
Per utilizzare i filtri di sottoscrizione avanzati, è necessario definire l'abbonamento nello schema GraphQL, quindi definire il filtro avanzato utilizzando un'estensione di filtro. Per illustrare come funziona il filtraggio avanzato degli abbonamenti AWS AppSync, usa il seguente schema GraphQL, che definisce un'API del sistema di gestione dei ticket, come esempio:
```
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
```
Supponete di creare una fonte di `NONE` dati per la vostra API, quindi di collegare un resolver alla mutazione utilizzando questa fonte di dati. `createTicket` I tuoi gestori potrebbero avere questo aspetto:
```
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;
}
```
**Nota**
I filtri avanzati sono abilitati nel gestore del resolver GraphQL in un determinato abbonamento. [Per ulteriori informazioni, consulta Resolver reference.](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)
Per implementare il comportamento del filtro avanzato, è necessario utilizzare la `extensions.setSubscriptionFilter()` funzione per definire un'espressione di filtro valutata rispetto ai dati pubblicati da una mutazione GraphQL che potrebbe interessare i client sottoscritti. [Per ulteriori informazioni sulle estensioni di filtraggio, consulta Estensioni.](https://docs.aws.amazon.com//appsync/latest/devguide/extensions-js.html)
La sezione seguente spiega come utilizzare le estensioni di filtraggio per implementare filtri avanzati.
## Creazione di filtri di abbonamento avanzati utilizzando estensioni di filtraggio
I filtri avanzati sono scritti in JSON nel gestore delle risposte dei resolver dell'abbonamento. I filtri possono essere raggruppati in un elenco chiamato a. `filterGroup` I filtri vengono definiti utilizzando almeno una regola, ciascuna con campi, operatori e valori. Definiamo un nuovo resolver `onSpecialTicketCreated` che imposta un filtro avanzato. È possibile configurare più regole in un filtro che vengono valutate utilizzando la logica AND, mentre più filtri in un gruppo di filtri vengono valutati utilizzando la logica OR:
```
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;
}
```
In base ai filtri definiti nell'esempio precedente, i ticket importanti vengono automaticamente inviati ai client API sottoscritti se viene creato un ticket con:
+ `priority`livello o `high` `medium`
AND
+ `severity`livello maggiore o uguale a `7` (`ge`)
O
+ `classification`biglietto impostato su `Security`
AND
+ `group`assegnazione impostata su o `admin` `operators`
![\[Esempio che mostra una query di filtraggio dei ticket\]](http://docs.aws.amazon.com/it_it/appsync/latest/devguide/images/aws-priority-example.png)
I filtri definiti nel resolver di sottoscrizione (filtro avanzato) hanno la precedenza sui filtri basati solo sugli argomenti di sottoscrizione (filtro di base). [Per ulteriori informazioni sull'utilizzo degli argomenti di sottoscrizione, vedere Utilizzo degli argomenti di sottoscrizione).](https://docs.aws.amazon.com//appsync/latest/devguide/aws-appsync-real-time-data.html#using-subscription-arguments)
Se un argomento è definito e richiesto nello schema GraphQL dell'abbonamento, il filtraggio basato sull'argomento specificato avviene solo se l'argomento è definito come regola nel metodo del resolver. `extensions.setSubscriptionFilter()` Tuttavia, se non sono presenti metodi di `extensions` filtraggio nel resolver di sottoscrizione, gli argomenti definiti nel client vengono utilizzati solo per il filtraggio di base. Non è possibile utilizzare contemporaneamente il filtro di base e il filtro avanzato.
Puoi utilizzare la [`context`variabile](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-context-reference-js.html) nella logica di estensione del filtro dell'abbonamento per accedere alle informazioni contestuali sulla richiesta. Ad esempio, quando utilizzi gli autorizzatori personalizzati Amazon Cognito User Pools, OIDC o Lambda per l'autorizzazione, puoi recuperare informazioni sui tuoi utenti nel momento in cui viene stabilito l'abbonamento. `context.identity` Puoi utilizzare queste informazioni per stabilire filtri in base all'identità degli utenti.
Supponiamo ora di voler implementare il comportamento di filtro avanzato per`onGroupTicketCreated`. L'`onGroupTicketCreated`abbonamento richiede un `group` nome obbligatorio come argomento. Una volta creati, ai ticket viene assegnato automaticamente uno `pending` stato. Puoi impostare un filtro di abbonamento per ricevere solo i biglietti appena creati che appartengono al gruppo fornito:
```
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;
}
```
Quando i dati vengono pubblicati utilizzando una mutazione come nell'esempio seguente:
```
mutation CreateTicket {
createTicket(input: {priority: medium, severity: 2, group: "aws"}) {
id
priority
severity
status
group
createdAt
}
}
```
I clienti abbonati attendono che i dati vengano trasmessi automaticamente non WebSockets appena viene creato un ticket con la mutazione: `createTicket`
```
subscription OnGroup {
onGroupTicketCreated(group: "aws") {
category
status
severity
priority
id
group
createdAt
content
}
}
```
I client possono essere sottoscritti senza argomenti perché la logica di filtraggio è implementata nel AWS AppSync servizio con un filtraggio avanzato, che semplifica il codice client. I client ricevono i dati solo se vengono soddisfatti i criteri di filtro definiti.
## Definizione di filtri avanzati per i campi dello schema annidati
È possibile utilizzare il filtro di sottoscrizione avanzato per filtrare i campi dello schema annidati. Supponiamo di aver modificato lo schema della sezione precedente per includere i tipi di posizione e indirizzo:
```
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
```
Con questo schema, è possibile utilizzare un `.` separatore per rappresentare la nidificazione. L'esempio seguente aggiunge una regola di filtro per un campo dello schema annidato in. `location.address.country` L'abbonamento verrà attivato se l'indirizzo del ticket è impostato su: `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;
}
```
Nell'esempio precedente, `location` rappresenta il livello di nidificazione uno, `address` rappresenta il livello di nidificazione due e `country` rappresenta il livello di nidificazione tre, tutti separati dal separatore. `.`
Puoi testare questo abbonamento usando la mutazione: `createTicket`
```
mutation CreateTicketInUSA {
createTicket(input: {location: "{\"address\":{\"country\":\"USA\"}}"}) {
category
content
createdAt
group
id
location {
address {
country
}
}
priority
severity
status
}
}
```
## Definizione di filtri avanzati dal client
È possibile utilizzare il filtraggio di base in GraphQL [con](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-real-time-data.html#using-subscription-arguments) argomenti di sottoscrizione. Il client che effettua la chiamata nella query di sottoscrizione definisce i valori degli argomenti. Quando i filtri avanzati sono abilitati in un resolver di AWS AppSync sottoscrizione con il `extensions` filtro, i filtri di backend definiti nel resolver hanno la precedenza e la priorità.
Configura filtri avanzati dinamici e definiti dal client utilizzando un argomento nella sottoscrizione. `filter` Quando configuri questi filtri, devi aggiornare lo schema GraphQL in modo che rifletta il nuovo argomento:
```
...
type Subscription {
onSpecialTicketCreated(filter: String): Ticket
@aws_subscribe(mutations: ["createTicket"])
}
...
```
Il client può quindi inviare una richiesta di sottoscrizione come nell'esempio seguente:
```
subscription onSpecialTicketCreated($filter: String) {
onSpecialTicketCreated(filter: $filter) {
id
group
description
priority
severity
}
}
```
È possibile configurare la variabile di query come nell'esempio seguente:
```
{"filter" : "{\"severity\":{\"le\":2}}"}
```
L'utilità `util.transform.toSubscriptionFilter()` resolver può essere implementata nel modello di mappatura delle risposte all'abbonamento per applicare il filtro definito nell'argomento dell'abbonamento per ogni 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;
}
```
Con questa strategia, i clienti possono definire i propri filtri che utilizzano una logica di filtraggio avanzata e operatori aggiuntivi. I filtri vengono assegnati quando un determinato client richiama la query di sottoscrizione in una connessione sicura. WebSocket [Per ulteriori informazioni sull'utilità di trasformazione per un filtraggio avanzato, incluso il formato del payload della variabile di `filter` query, consulta la panoramica sui resolver. JavaScript](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-overview-js.html)
## Restrizioni di filtraggio avanzate aggiuntive
Di seguito sono riportati diversi casi d'uso in cui vengono applicate restrizioni aggiuntive ai filtri avanzati:
+ I filtri avanzati non supportano il filtraggio per gli elenchi di oggetti di primo livello. In questo caso d'uso, i dati pubblicati relativi alla mutazione verranno ignorati per gli abbonamenti avanzati.
+ AWS AppSync supporta fino a cinque livelli di nidificazione. I filtri sui campi dello schema che hanno superato il quinto livello di nidificazione verranno ignorati. Prendi la risposta GraphQL qui sotto. Il `continent` field in ingresso `venue.address.country.metadata.continent` è consentito perché si tratta di un nido di livello cinque. Tuttavia, `financial` `venue.address.country.metadata.capital.financial` è un nido di livello sei, quindi il filtro non funzionerà:
```
{
"data": {
"onCreateFilterEvent": {
"venue": {
"address": {
"country": {
"metadata": {
"capital": {
"financial": "New York"
},
"continent" : "North America"
}
},
"state": "WA"
},
"builtYear": 2023
},
"private": false,
}
}
}
```