Questa pagina spiega come creare abbonamenti Pub/Sub con filtri.
Quando ricevi i messaggi da una sottoscrizione con un filtro, riceverai solo quelli che corrispondono a un filtro. Il servizio Pub/Sub riconosce automaticamente i messaggi che non corrispondono al filtro. Puoi filtrare i messaggi in base ai rispettivi attributi, ma non in base ai dati contenuti nel messaggio.
Puoi avere più abbonamenti collegati a un argomento e ogni abbonamento può avere un filtro diverso.
Ad esempio, se hai un argomento che riceve notizie da diverse parti del mondo, puoi configurare un abbonamento per filtrare le notizie pubblicate solo da una regione specifica. Per questa configurazione, devi assicurarti che uno degli attributi del messaggio dell'argomento trasmetta la regione di pubblicazione delle notizie.
Quando ricevi i messaggi da una sottoscrizione con un filtro, non ti vengono addebitati costi per i messaggi in uscita per i messaggi che Pub/Sub riconosce automaticamente. Per questi messaggi sono previsti costi di consegna dei messaggi e tariffe per l'archiviazione correlate alla ricerca.
Creare un abbonamento con un filtro
Le sottoscrizioni pull e push possono avere filtri. Tutti gli abbonati possono ricevere messaggi dalle sottoscrizioni con filtri, inclusi gli abbonati che utilizzano l'API StreamingPull.
Puoi creare una sottoscrizione con un filtro utilizzando la Google Cloud console, Google Cloud CLI, le librerie client o l'API Pub/Sub.
Console
Per creare un abbonamento pull con un filtro:
Nella console Google Cloud , vai alla pagina Abbonamenti.
Fai clic su Crea sottoscrizione.
Inserisci l'ID abbonamento.
Scegli o crea un argomento dal menu a discesa. La sottoscrizione riceve i messaggi dall'argomento.
Nella sezione Filtro abbonamento, inserisci l'espressione di filtro.
Fai clic su Crea.
Per creare un abbonamento push con un filtro:
Nella console Google Cloud , vai alla pagina Abbonamenti.
Fai clic su Crea sottoscrizione.
Inserisci l'ID abbonamento.
Scegli o crea un argomento dal menu a discesa. La sottoscrizione riceve i messaggi dall'argomento.
Nella sezione Tipo di pubblicazione, fai clic su Push.
Nel campo Endpoint URL (URL endpoint), inserisci l'URL dell'endpoint push.
Nella sezione Filtro abbonamento, inserisci l'espressione di filtro.
Fai clic su Crea.
gcloud
Per creare un abbonamento pull con un filtro, utilizza il
comando gcloud pubsub subscriptions create
con il flag --message-filter
:
gcloud pubsub subscriptions create SUBSCRIPTION_ID \ --topic=TOPIC_ID \ --message-filter='FILTER'
Sostituisci quanto segue:
- SUBSCRIPTION_ID: l'ID dell'abbonamento da creare
- TOPIC_ID: l'ID dell'argomento da collegare all'abbonamento
- FILTER: un'espressione nella sintassi di filtraggio
Per creare una sottoscrizione push con un filtro, utilizza il comando gcloud pubsub subscriptions create
con i flag --push-endpoint
e --message-filter
:
gcloud pubsub subscriptions create SUBSCRIPTION_ID \ --topic=TOPIC_ID \ --push-endpoint=PUSH_ENDPOINT \ --message-filter='FILTER'
Sostituisci quanto segue:
- SUBSCRIPTION_ID: l'ID dell'abbonamento da creare
- TOPIC_ID: l'ID dell'argomento da collegare all'abbonamento
- PUSH_ENDPOINT: l'URL del server su cui viene eseguito l'abbonato push
- FILTER: un'espressione nella sintassi di filtraggio
REST
Per creare un abbonamento con un filtro, utilizza il metodo
projects.subscriptions.create
.
PUT https://pubsub.googleapis.com/v1/projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID Authorization: Bearer $(gcloud auth print-access-token)
Sostituisci quanto segue:
- PROJECT_ID: l'ID progetto in cui creare l'abbonamento
- SUBSCRIPTION_ID: l'ID dell'abbonamento da creare
Per creare un abbonamento pull con un filtro, specifica il filtro nel corpo della richiesta:
{ "topic": "projects/PROJECT_ID/topics/TOPIC_ID", "filter": "FILTER" }
Sostituisci quanto segue:
- PROJECT_ID: l'ID progetto per il progetto con l'argomento
- TOPIC_ID: l'ID dell'argomento da collegare all'abbonamento
- FILTER: un'espressione nella sintassi di filtraggio
Per creare un abbonamento push con un filtro, specifica l'endpoint push e il filtro nel corpo della richiesta:
{ "topic": "projects/PROJECT_ID/topics/TOPIC_ID", "pushConfig": { "pushEndpoint": "PUSH_ENDPOINT" }, "filter": "FILTER" }
Sostituisci quanto segue:
- PROJECT_ID: l'ID progetto per il progetto con l'argomento
- TOPIC_ID: l'ID dell'argomento da collegare all'abbonamento
- PUSH_ENDPOINT: l'URL del server su cui viene eseguito l'abbonato push
- FILTER: un'espressione nella sintassi di filtraggio
C++
Prima di provare questo esempio, segui le istruzioni di configurazione di C++ nella guida rapida all'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Pub/Sub C++.
C#
Prima di provare questo esempio, segui le istruzioni di configurazione di C# nella guida rapida all'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Pub/Sub C#.
Vai
L'esempio seguente utilizza la versione principale della libreria client Go Pub/Sub (v2). Se utilizzi ancora la libreria v1, consulta la guida alla migrazione alla v2. Per visualizzare un elenco di esempi di codice della versione 1, consulta gli esempi di codice ritirati.
Prima di provare questo esempio, segui le istruzioni di configurazione di Go nella guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Go.
Java
Prima di provare questo esempio, segui le istruzioni di configurazione di Java nella Guida rapida all'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Java di Pub/Sub.
Node.js
Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js nella Guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Node.js.
Node.js
Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js nella Guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Node.js.
PHP
Prima di provare questo esempio, segui le istruzioni di configurazione di PHP nella guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub PHP.
Python
Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Python.
Ruby
Prima di provare questo esempio, segui le istruzioni di configurazione di Ruby nella guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Ruby.
La lunghezza massima di un filtro è di 256 byte. Il filtro è una proprietà immutabile di un abbonamento. Dopo aver creato un abbonamento, non puoi aggiornarlo per modificare il filtro.
In che modo i filtri influiscono sulle metriche del backlog
Per monitorare l'abbonamento che hai appena creato, consulta Monitorare gli abbonamenti con i filtri.
Se hai attivato il filtro, le metriche del backlog includono solo i dati dei messaggi che corrispondono al filtro. Di seguito è riportato un elenco delle metriche del backlog:
subscription/backlog_bytes
subscription/unacked_bytes_by_region
subscription/num_undelivered_messages
subscription/num_unacked_messages_by_region
subscription/oldest_unacked_message_age
subscription/oldest_unacked_message_age_by_region
topic/unacked_bytes_by_region
topic/num_unacked_messages_by_region
topic/oldest_unacked_messages_age_by_region
Per scoprire di più su queste metriche, consulta l'elenco delle metriche Pub/Sub.
Aggiornare il filtro per un abbonamento
Non puoi aggiornare il filtro per un abbonamento esistente. Segui invece questa soluzione alternativa.
Scatta uno snapshot dell'iscrizione per cui vuoi modificare il filtro.
Per saperne di più su come creare uno snapshot utilizzando la console, consulta Creare uno snapshot.
Crea un nuovo abbonamento con il nuovo filtro.
Per scoprire di più sulla creazione di un abbonamento con un filtro, vedi Creare un abbonamento con un filtro.
Nella Google Cloud console, vai alla pagina Sottoscrizioni Pub/Sub.
Fai clic sull'abbonamento che hai appena creato.
Nella pagina dei dettagli della sottoscrizione, fai clic su Riproduci messaggi.
Per Cerca, fai clic su In uno snapshot.
Seleziona lo snapshot che hai creato per l'abbonamento originale nel passaggio 1 e poi fai clic su Ricerca.
Non perderai alcun messaggio durante la transizione.
Modifica gli abbonati in modo che utilizzino il nuovo abbonamento.
Una volta completata questa procedura, puoi eliminare l'abbonamento originale.
Sintassi per creare un filtro
Per filtrare i messaggi, scrivi un'espressione che agisce sugli attributi. Puoi
scrivere un'espressione che corrisponda alla chiave o al valore degli attributi. L'identificatore
attributes
seleziona gli attributi nel messaggio.
Ad esempio, i filtri nella tabella seguente selezionano l'attributo name
:
Filtro | Descrizione |
---|---|
attributes:name |
Messaggi con l'attributo name |
NOT attributes:name |
Messaggi senza l'attributo name |
attributes.name = "com" |
Messaggi con l'attributo name e il valore com |
attributes.name != "com" |
Messaggi senza l'attributo name e il valore com |
hasPrefix(attributes.name, "co") |
Messaggi con l'attributo name e un valore che inizia con co |
NOT hasPrefix(attributes.name, "co") |
Messaggi senza l'attributo name e un valore che inizia con co |
Operatori di confronto per l'espressione di filtro
Puoi filtrare gli attributi con i seguenti operatori di confronto:
:
=
!=
L'operatore :
corrisponde a una chiave in un elenco di attributi.
attributes:KEY
Gli operatori di uguaglianza corrispondono a chiavi e valori. Il valore deve essere una stringa letterale.
attributes.KEY = "VALUE"
Un'espressione con un operatore di uguaglianza deve iniziare con una chiave e l'operatore di uguaglianza deve confrontare una chiave e un valore.
Valido: il filtro confronta una chiave e un valore
attributes.name = "com"
Non valido: il lato sinistro del filtro è un valore
"com" = attributes.name
Non valido: il filtro confronta due chiavi
attributes.name = attributes.website
La chiave e il valore sono sensibili alle maiuscole e devono corrispondere esattamente all'attributo. Se una chiave contiene caratteri diversi da trattini, trattini bassi o caratteri alfanumerici, utilizza un valore letterale stringa.
attributes."iana.org/language_tag" = "en"
Per utilizzare barre rovesciate, virgolette e caratteri non stampabili in un filtro, esegui l'escape dei caratteri all'interno di un valore letterale stringa. Puoi anche utilizzare sequenze di escape Unicode, esadecimali e ottali all'interno di un valore letterale stringa.
Valido: il filtro esegue l'escape dei caratteri all'interno di un valore letterale stringa
attributes:"\u307F\u3093\u306A"
Non valido: il filtro esegue l'escape dei caratteri senza un valore letterale di stringa
attributes:\u307F\u3093\u306A
Operatori booleani per l'espressione di filtro
Puoi utilizzare gli operatori booleani AND
, NOT
e OR
in un filtro. Gli operatori
devono essere in maiuscolo. Ad esempio, il
seguente filtro è per i messaggi con l'attributo iana.org/language_tag
,
ma senza l'attributo name
e il valore com
.
attributes:"iana.org/language_tag" AND NOT attributes.name = "com"
L'operatore NOT
ha la precedenza più alta. Per combinare gli operatori AND
e OR
, utilizza le parentesi e le espressioni complete.
Valido: operatori
AND
eOR
con parentesiattributes:"iana.org/language_tag" AND (attributes.name = "net" OR attributes.name = "org")
Non valido: operatori
AND
eOR
senza parentesiattributes:"iana.org/language_tag" AND attributes.name = "net" OR attributes.name = "org"
Non valido: gli operatori
AND
eOR
combinano espressioni incompleteattributes.name = "com" AND ("net" OR "org")
Puoi anche utilizzare l'operatore meno unario anziché l'operatore NOT
.
attributes.name = "com" AND -attributes:"iana.org/language_tag"
Funzioni per l'espressione di filtro
Puoi utilizzare la funzione hasPrefix
per filtrare gli attributi con valori che
iniziano con una sottostringa. hasPrefix
è l'unica funzione supportata in un filtro.
La corrispondenza dei prefissi è supportata con la funzione hasPrefix
, ma le espressioni regolari generali non sono supportate.
hasPrefix(attributes.KEY, "SUBSTRING")
Sostituisci quanto segue:
- KEY: il nome dell'attributo
- SUBSTRING: una sottostringa del valore