Questo documento fornisce informazioni sulla pubblicazione dei messaggi.
Un'applicazione del publisher crea e invia messaggi in un argomento. Pub/Sub offre la consegna di messaggi "at almeno una volta" e il "best effort" dell'ordine ai sottoscrittori esistenti.
Il flusso generale per un'applicazione del publisher è:
- Crea un messaggio contenente i tuoi dati.
- Invia una richiesta al server Pub/Sub per pubblicare il messaggio nell'argomento specificato.
Prima di iniziare
Prima di configurare il flusso di lavoro di pubblicazione, assicurati di aver completato le seguenti attività:
- Scopri di più sugli argomenti e sul flusso di lavoro di pubblicazione.
- Crea un argomento.
- Scegli e crea un abbonamento.
Ruoli obbligatori
Per ottenere le autorizzazioni necessarie per pubblicare messaggi in un argomento,
chiedi all'amministratore di concederti il ruolo IAM
Publisher Pub/Sub (roles/pubsub.publisher
) per l'argomento.
Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso.
Potresti anche essere in grado di ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.
Devi disporre di autorizzazioni aggiuntive per creare o aggiornare argomenti e sottoscrizioni.
Formato dei messaggi
Un messaggio è costituito da campi contenenti i dati e i metadati del messaggio. Specifica nel messaggio almeno uno dei seguenti valori:
- I dati dei messaggi
- Una chiave di ordinazione.
- Attributi con metadati aggiuntivi
Il servizio Pub/Sub aggiunge i seguenti campi al messaggio:
- Un ID messaggio univoco per l'argomento
- Un timestamp che indica quando il servizio Pub/Sub riceve il messaggio
Per scoprire di più sui messaggi, vedi Formato del messaggio.
pubblica dei messaggi
Puoi pubblicare messaggi con la console Google Cloud, Google Cloud CLI, l'API Pub/Sub e le librerie client. Le librerie client possono pubblicare messaggi in modo asincrono.
I seguenti esempi mostrano come pubblicare un messaggio in un argomento.
Console
Per pubblicare un messaggio:
Nella console Google Cloud, vai alla pagina Argomenti Pub/Sub.
Fai clic sull'ID argomento.
Nella pagina Dettagli argomento, in Messaggi, fai clic su Pubblica messaggio.
Nel campo Corpo del messaggio, inserisci i dati del messaggio.
Fai clic su Pubblica.
gcloud
Per pubblicare un messaggio, utilizza il comando gcloud pubsub topics publish:
gcloud pubsub topics publish TOPIC_ID \ --message=MESSAGE_DATA \ [--attribute=KEY="VALUE",...]
Sostituisci quanto segue:
- TOPIC_ID: l'ID dell'argomento
- MESSAGE_DATA: una stringa con i dati del messaggio
- KEY: la chiave di un attributo messaggio
- VALUE: il valore della chiave dell'attributo del messaggio
REST
Per pubblicare un messaggio, invia una richiesta POST come la seguente:
POST https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics/TOPIC_ID:publish Content-Type: application/json Authorization: Bearer $(gcloud auth application-default print-access-token)
Sostituisci quanto segue:
- PROJECT_ID: l'ID del progetto con l'argomento
- TOPIC_ID: l'ID dell'argomento
Specifica i seguenti campi nel corpo della richiesta:
{ "messages": [ { "attributes": { "KEY": "VALUE", ... }, "data": "MESSAGE_DATA", } ] }
Sostituisci quanto segue:
- KEY: la chiave di un attributo messaggio
- VALUE: il valore della chiave dell'attributo del messaggio
- MESSAGE_DATA: una stringa con codifica Base64 con i dati del messaggio
Il messaggio deve contenere un campo di dati non vuoto o almeno un attributo.
Se la richiesta ha esito positivo, la risposta è un oggetto JSON con l'ID messaggio. L'esempio seguente è una risposta con un ID messaggio:
{ "messageIds": [ "19916711285", ] }
C++
Prima di provare questo esempio, segui le istruzioni di configurazione di C++ riportate nella Guida rapida sull'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API C++ Pub/Sub.
C#
Prima di provare questo esempio, segui le istruzioni di configurazione di C# nella Guida rapida sull'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API C# di Pub/Sub.
Go
Prima di provare questo esempio, segui le istruzioni di configurazione di Go nella Guida rapida sull'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Go Pub/Sub.
Java
Prima di provare questo esempio, segui le istruzioni di configurazione Java in Guida rapida sull'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Java Pub/Sub.
Node.js
Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js in Guida rapida sull'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Node.js Pub/Sub.
Node.js
Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js in Guida rapida sull'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Node.js Pub/Sub.
PHP
Prima di provare questo esempio, segui le istruzioni di configurazione PHP nella Guida rapida sull'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API PHP Pub/Sub.
Python
Prima di provare questo esempio, segui le istruzioni di configurazione di Python in Guida rapida sull'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Python Pub/Sub.
Ruby
Prima di provare questo esempio, segui le istruzioni di configurazione di Ruby riportate in Guida rapida sull'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Ruby Pub/Sub.
Dopo aver pubblicato un messaggio, il servizio Pub/Sub restituisce l'ID messaggio all'editore.
Utilizzare gli attributi per pubblicare un messaggio
Puoi incorporare attributi personalizzati come metadati nei messaggi Pub/Sub. Gli attributi vengono utilizzati per fornire informazioni aggiuntive sul messaggio, come priorità, origine o destinazione. Gli attributi possono essere utilizzati anche per filtrare i messaggi nella sottoscrizione.
Segui queste linee guida per l'utilizzo degli attributi nei tuoi messaggi:
Gli attributi possono essere stringhe di testo o stringhe di byte.
Puoi avere al massimo 100 attributi per messaggio.
Le chiavi degli attributi non devono iniziare con
goog
e non devono superare i 256 byte.I valori degli attributi non devono superare i 1024 byte.
Lo schema dei messaggi può essere rappresentato come segue:
{ "data": string, "attributes": { string: string, ... }, "messageId": string, "publishTime": string, "orderingKey": string }
Per i duplicati lato pubblicazione, è possibile vedere valori publishTime
diversi per lo stesso messaggio originale lato client, anche con lo stesso messageId
.
Lo schema JSON PubsubMessage
è pubblicato come parte della documentazione relativa a REST e RPC. Puoi utilizzare attributi personalizzati per i timestamp degli eventi.
I seguenti esempi mostrano come pubblicare un messaggio con attributi in un argomento.
Console
Per pubblicare un messaggio con attributi:
Nella console Google Cloud, vai alla pagina Argomenti.
Fai clic sull'argomento per cui vuoi pubblicare messaggi.
Nella pagina dei dettagli dell'argomento, fai clic su Messaggi.
Fai clic su Pubblica messaggio.
Nel campo Corpo del messaggio, inserisci i dati del messaggio.
In Attributi del messaggio, fai clic su Aggiungi un attributo.
Inserisci una coppia chiave-valore.
Aggiungi altri attributi, se necessario.
Fai clic su Pubblica.
gcloud
gcloud pubsub topics publish my-topic --message="hello" \ --attribute="origin=gcloud-sample,username=gcp,eventTime='2021-01-01T12:00:00Z'"
C++
Prima di provare questo esempio, segui le istruzioni di configurazione di C++ riportate nella Guida rapida sull'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API C++ Pub/Sub.
C#
Prima di provare questo esempio, segui le istruzioni di configurazione di C# nella Guida rapida sull'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API C# di Pub/Sub.
Go
Prima di provare questo esempio, segui le istruzioni di configurazione di Go nella Guida rapida sull'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Go Pub/Sub.
Java
Prima di provare questo esempio, segui le istruzioni di configurazione Java in Guida rapida sull'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Java Pub/Sub.
Node.js
Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js in Guida rapida sull'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Node.js Pub/Sub.
Python
Prima di provare questo esempio, segui le istruzioni di configurazione di Python in Guida rapida sull'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Python Pub/Sub.
Ruby
Prima di provare questo esempio, segui le istruzioni di configurazione di Ruby riportate in Guida rapida sull'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Ruby Pub/Sub.
Utilizzare le chiavi di ordinamento per pubblicare un messaggio
Per ricevere i messaggi in ordine nei client abbonati, devi configurare i client publisher in modo da pubblicare i messaggi con chiavi di ordinamento.
Per comprendere il concetto di ordinamento delle chiavi, consulta Messaggi relativi agli ordini.
Di seguito è riportato un elenco di considerazioni chiave per la messaggistica ordinata per i clienti dei publisher:
Ordine in un singolo client publisher: quando un singolo client publisher pubblica messaggi con la stessa chiave di ordinamento nella stessa regione, il client abbonato riceve i messaggi nell'ordine esatto in cui sono stati pubblicati. Ad esempio, se un client editore pubblica i messaggi 1, 2 e 3 con la chiave di ordinamento A, il client dell'abbonato li riceve nell'ordine 1, 2, 3.
Ordine tra più client publisher: l'ordine dei messaggi ricevuti dai client abbonati è coerente con l'ordine in cui sono stati pubblicati nella stessa regione, anche quando più client publisher utilizzano la stessa chiave di ordinamento. Tuttavia, i clienti degli editori non sono a conoscenza di questo ordine.
Ad esempio, se i client del publisher X e Y pubblicano messaggi con la chiave di ordinamento A e il messaggio di X viene ricevuto da Pub/Sub prima di quello della Y, tutti i client sottoscrittori ricevono il messaggio di X prima di quello di Y. Se è richiesto un ordine rigoroso dei messaggi per diversi client di publisher, questi ultimi devono implementare un meccanismo di coordinamento aggiuntivo per garantire che non pubblichino messaggi con la stessa chiave di ordinamento contemporaneamente. Ad esempio, è possibile usare un servizio di blocco per mantenere la proprietà di una chiave di ordinazione durante la pubblicazione.
Ordinamento tra regioni: l'ordinamento dei messaggi è previsto solo per i messaggi pubblicati nella stessa regione. Pertanto, assicurati che i client publisher utilizzino gli endpoint di servizio di geolocalizzazione per pubblicare messaggi nella stessa regione per la stessa chiave di ordinamento. I client abbonati possono quindi ricevere questi messaggi in ordine.
Errori di pubblicazione: se la pubblicazione con una chiave di ordinamento non va a buon fine, i messaggi in coda relativi alla stessa chiave di ordinamento nell'editore non vanno a buon fine, incluse le richieste di pubblicazione future di questa chiave di ordinamento. Quando si verificano errori di questo tipo, devi riprendere la pubblicazione con le chiavi di ordinamento. Per un esempio di ripresa dell'operazione di pubblicazione, consulta Ripetere le richieste con chiavi di ordinazione.
Puoi pubblicare messaggi con chiavi di ordinamento utilizzando la console Google Cloud, Google Cloud CLI, l'API Pub/Sub o le librerie client.
Console
Per pubblicare un messaggio con attributi:
Nella console Google Cloud, vai alla pagina Argomenti.
Fai clic sull'argomento per cui vuoi pubblicare messaggi.
Nella pagina dei dettagli dell'argomento, fai clic su Messaggi.
Fai clic su Pubblica messaggio.
Nel campo Corpo del messaggio, inserisci i dati del messaggio.
Nel campo Ordine dei messaggi, inserisci una chiave di ordinamento.
Fai clic su Pubblica.
gcloud
Per pubblicare un messaggio con una chiave di ordinamento, utilizza il comando gcloud pubsub topics publish
e il flag --ordering-key
:
gcloud pubsub topics publish TOPIC_ID \ --message=MESSAGE_DATA \ --ordering-key=ORDERING_KEY
Sostituisci quanto segue:
- TOPIC_ID: l'ID dell'argomento
- MESSAGE_DATA: una stringa con i dati del messaggio
- ORDERING_KEY: una stringa con una chiave di ordinamento
REST
Per pubblicare un messaggio con una chiave di ordinamento, invia una richiesta POST come la seguente:
POST https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics/TOPIC_ID:publish Content-Type: application/json Authorization: Bearer $(gcloud auth application-default print-access-token)
Sostituisci quanto segue:
- PROJECT_ID: l'ID del progetto con l'argomento
- TOPIC_ID: l'ID dell'argomento
Specifica i seguenti campi nel corpo della richiesta:
{ "messages": [ { "attributes": { "KEY": "VALUE", ... }, "data": "MESSAGE_DATA", "ordering_key": "ORDERING_KEY", } ] }
Sostituisci quanto segue:
- KEY: la chiave di un attributo messaggio
- VALUE: il valore della chiave dell'attributo del messaggio
- MESSAGE_DATA: una stringa con codifica Base64 con i dati del messaggio
- ORDERING_KEY: una stringa con una chiave di ordinamento
Il messaggio deve contenere un campo di dati non vuoto o almeno un attributo.
Se la richiesta ha esito positivo, la risposta è un oggetto JSON con l'ID messaggio. L'esempio seguente è una risposta con un ID messaggio:
{ "messageIds": [ "19916711285", ] }
C++
Prima di provare questo esempio, segui le istruzioni di configurazione di C++ riportate nella Guida rapida sull'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API C++ Pub/Sub.
C#
Prima di provare questo esempio, segui le istruzioni di configurazione di C# nella Guida rapida sull'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API C# di Pub/Sub.
Go
Prima di provare questo esempio, segui le istruzioni di configurazione di Go nella Guida rapida sull'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Go Pub/Sub.
Java
Prima di provare questo esempio, segui le istruzioni di configurazione Java in Guida rapida sull'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Java Pub/Sub.
Node.js
Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js in Guida rapida sull'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Node.js Pub/Sub.
Python
Prima di provare questo esempio, segui le istruzioni di configurazione di Python in Guida rapida sull'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Python Pub/Sub.
Ruby
Prima di provare questo esempio, segui le istruzioni di configurazione di Ruby riportate in Guida rapida sull'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Ruby Pub/Sub.
Monitorare un publisher
Cloud Monitoring fornisce una serie di metriche per monitorare gli argomenti.
Per monitorare un argomento e mantenere un editore integro, consulta Gestire un editore integro.
Passaggi successivi
Per limitare le località in cui Pub/Sub archivia i dati dei messaggi, consulta Limitazione delle località delle risorse Pub/Sub.
Per pubblicare messaggi con uno schema, consulta la Panoramica dello schema.
Per informazioni su come configurare le opzioni di consegna avanzate, consulta quanto segue: