In questa pagina viene spiegato come pubblicare messaggi in argomenti Lite. Puoi pubblicare i messaggi con la libreria client Pub/Sub Lite per Java.
Dopo aver pubblicato messaggi e aver creato una sottoscrizione Lite in un argomento Lite, puoi ricevere messaggi dalla sottoscrizione Lite.
Formato dei messaggi
Un messaggio è costituito da campi con i relativi dati e metadati. Specifica nel messaggio uno qualsiasi dei seguenti elementi:
- I dati dei messaggi
- Una chiave di ordinamento
- L'ora di un evento
- Attributi con metadati aggiuntivi
La libreria client assegna automaticamente il messaggio a una partizione e il servizio Pub/Sub Lite aggiunge i seguenti campi al messaggio:
- Un ID messaggio univoco all'interno della partizione
- Un timestamp che indica quando il servizio Pub/Sub Lite archivia il messaggio nella partizione
Pubblicazione di messaggi
Per pubblicare messaggi, richiedi una connessione in modalità flusso all'argomento Lite, quindi invia i messaggi tramite la connessione in modalità flusso.
L'esempio seguente mostra come pubblicare messaggi in un argomento Lite:
gcloud
Questo comando richiede Python 3.6 o versioni successive e l'installazione del pacchetto Python grpcio. Per gli utenti di MacOS, Linux e Cloud Shell, esegui:
sudo pip3 install grpcio
export CLOUDSDK_PYTHON_SITEPACKAGES=1
Per pubblicare un messaggio, utilizza il comando gcloud pubsub lite-topics publish:
gcloud pubsub lite-topics publish TOPIC_ID \
--location=LITE_LOCATION \
--message=MESSAGE_DATA
Sostituisci quanto segue:
- TOPIC_ID: l'ID dell'argomento Lite
- LITE_LOCATION: la posizione dell'argomento Lite
- MESSAGE_DATA: una stringa con i dati del messaggio
Go
Prima di eseguire questo esempio, segui le istruzioni di configurazione di Go nelle librerie client di Pub/Sub Lite.
Java
Prima di eseguire questo esempio, segui le istruzioni di configurazione di Java nelle librerie client di Pub/Sub Lite.
Python
Prima di eseguire questo esempio, segui le istruzioni di configurazione di Python nelle librerie client di Pub/Sub Lite.
La libreria client invia i messaggi e gestisce gli errori in modo asincrono. Se si verifica un errore, la libreria client invia di nuovo il messaggio.
- Il servizio Pub/Sub Lite chiude il flusso.
- La libreria client memorizza i messaggi nel buffer e ristabilisce una connessione all'argomento Lite.
- La libreria client invia i messaggi in ordine.
Dopo aver pubblicato un messaggio, il servizio Pub/Sub Lite lo archivia in una partizione e restituisce l'ID messaggio al publisher.
Utilizzo delle chiavi di ordinamento
Se i messaggi hanno la stessa chiave di ordinamento, la libreria client li assegna alla stessa partizione. La chiave di ordinamento deve essere una stringa di massimo 1024 byte.
La chiave di ordinamento si trova nel campo key
di un messaggio.
Puoi impostare le chiavi di ordinamento con la libreria client.
gcloud
Questo comando richiede Python 3.6 o versioni successive e l'installazione del pacchetto Python grpcio. Per gli utenti di MacOS, Linux e Cloud Shell, esegui:
sudo pip3 install grpcio
export CLOUDSDK_PYTHON_SITEPACKAGES=1
Per pubblicare un messaggio, utilizza il comando gcloud pubsub lite-topics publish:
gcloud pubsub lite-topics publish TOPIC_ID \
--location=LITE_LOCATION \
--ordering-key=ORDERING_KEY \
--message=MESSAGE_DATA
Sostituisci quanto segue:
- TOPIC_ID: l'ID dell'argomento Lite
- LITE_LOCATION: la posizione dell'argomento Lite
- ORDERING_KEY: una stringa utilizzata per assegnare messaggi alle partizioni
- MESSAGE_DATA: una stringa con i dati del messaggio
Go
Prima di eseguire questo esempio, segui le istruzioni di configurazione di Go nelle librerie client di Pub/Sub Lite.
Java
Prima di eseguire questo esempio, segui le istruzioni di configurazione di Java nelle librerie client di Pub/Sub Lite.
Python
Prima di eseguire questo esempio, segui le istruzioni di configurazione di Python nelle librerie client di Pub/Sub Lite.
Puoi inviare più messaggi alla stessa partizione utilizzando le chiavi di ordinamento, in modo che i sottoscrittori li ricevano in ordine. La libreria client potrebbe assegnare più chiavi di ordinamento alla stessa partizione.
Imposta l'ora dell'evento
Puoi utilizzare l'ora evento per pubblicare i messaggi Lite. L'ora evento è un attributo personalizzato che puoi aggiungere al messaggio.
Puoi impostare il timestamp dell'evento con la libreria client o con gCloud CLI.
Questo comando richiede Python 3.6 o versioni successive e l'installazione del pacchetto Python grpcio. Per gli utenti di MacOS, Linux e Cloud Shell, esegui:
sudo pip3 install grpcio
export CLOUDSDK_PYTHON_SITEPACKAGES=1
Per pubblicare un messaggio, utilizza il comando gcloud pubsub lite-topics publish:
gcloud pubsub lite-topics publish TOPIC_ID \
--location=LITE_LOCATION \
--event-time=EVENT_TIME \
--message=MESSAGE_DATA
Sostituisci quanto segue:
TOPIC_ID: l'ID dell'argomento Lite
LITE_LOCATION: la posizione dell'argomento Lite
EVENT_TIME: ora dell'evento specificata dall'utente. Per maggiori informazioni sui formati dell'ora, esegui
gcloud topic datetimes
.MESSAGE_DATA: una stringa con i dati del messaggio
Utilizzo degli attributi
Gli attributi del messaggio sono coppie chiave-valore con metadati relativi al messaggio. Gli attributi possono essere stringhe di testo o byte.
Gli attributi si trovano nel campo attributes
di un messaggio. Puoi impostare gli attributi con la libreria client.
gcloud
Questo comando richiede Python 3.6 o versioni successive e l'installazione del pacchetto Python grpcio. Per gli utenti di MacOS, Linux e Cloud Shell, esegui:
sudo pip3 install grpcio
export CLOUDSDK_PYTHON_SITEPACKAGES=1
Per pubblicare un messaggio, utilizza il comando gcloud pubsub lite-topics publish:
gcloud pubsub lite-topics publish TOPIC_ID \
--location=LITE_LOCATION \
--message=MESSAGE_DATA \
--attribute=KEY=VALUE,...
Sostituisci quanto segue:
- TOPIC_ID: l'ID dell'argomento Lite
- LITE_LOCATION: la posizione dell'argomento Lite
- MESSAGE_DATA: una stringa con i dati del messaggio
- KEY: la chiave di un attributo del messaggio
- VALUE: il valore della chiave dell'attributo del messaggio
Go
Prima di eseguire questo esempio, segui le istruzioni di configurazione di Go nelle librerie client di Pub/Sub Lite.
Java
Prima di eseguire questo esempio, segui le istruzioni di configurazione di Java nelle librerie client di Pub/Sub Lite.
Python
Prima di eseguire questo esempio, segui le istruzioni di configurazione di Python nelle librerie client di Pub/Sub Lite.
Gli attributi possono indicare come elaborare un messaggio. I sottoscrittori possono analizzare il campo attributes
di un messaggio ed elaborare il messaggio in base ai suoi attributi.
Raggruppamento dei messaggi in batch
La libreria client pubblica i messaggi in batch. I batch più grandi usano meno risorse di calcolo, ma aumentano la latenza. Puoi modificare la dimensione del batch con le impostazioni di batch.
La tabella seguente elenca le impostazioni di raggruppamento in batch che puoi configurare:
Impostazione | Descrizione | Predefinita |
---|---|---|
Dimensioni richiesta | La dimensione massima, in byte, del batch. | 3,5 MiB |
Numero di messaggi | Il numero massimo di messaggi in un batch. | 1000 messaggi |
Ritardo nella pubblicazione | La quantità di tempo, in millisecondi, tra l'aggiunta del messaggio a un batch e l'invio del batch all'argomento Lite. | 50 millisecondi |
È possibile configurare le impostazioni di raggruppamento in batch con la libreria client.
Go
Prima di eseguire questo esempio, segui le istruzioni di configurazione di Go nelle librerie client di Pub/Sub Lite.
Java
Prima di eseguire questo esempio, segui le istruzioni di configurazione di Java nelle librerie client di Pub/Sub Lite.
Python
Prima di eseguire questo esempio, segui le istruzioni di configurazione di Python nelle librerie client di Pub/Sub Lite.
Quando viene avviata un'applicazione dell'editore, la libreria client crea un batch per ogni partizione in un argomento Lite. Ad esempio, se un argomento Lite ha due partizioni, i publisher creano due batch e inviano ogni batch a una partizione.
Dopo aver pubblicato un messaggio, la libreria client lo memorizza nel buffer finché il batch non supera la dimensione massima della richiesta, il numero massimo di messaggi o il ritardo di pubblicazione.
Ordinamento dei messaggi
Gli argomenti Lite ordinano i messaggi in ogni partizione in base alla data di pubblicazione. Per assegnare messaggi alla stessa partizione, utilizza una chiave di ordinamento.
Pub/Sub Lite consegna i messaggi da una partizione in ordine e i sottoscrittori possono elaborarli in ordine. Per maggiori dettagli, vedi Ricezione di messaggi.
Idempotenza della pubblicazione
Le librerie client di Pub/Sub Lite supportano la pubblicazione idempotente dalle seguenti versioni:
- java-pubsublite: versione 1.10.0.
- python-pubsublite: versione 1.8.0.
- google-cloud-go: pubsublite versione 1.7.0.
Se si tenta di nuovo la pubblicazione di un messaggio a causa di errori di rete o del server, il messaggio viene archiviato una sola volta. L'idempotenza è garantita solo nella stessa sessione; non può essere garantita se lo stesso messaggio viene ripubblicato utilizzando un nuovo client publisher. Non comporta costi di servizio aggiuntivi né aumenta la latenza di pubblicazione.
Abilita o disabilita la pubblicazione idempotente
La pubblicazione idempotente è abilitata per impostazione predefinita nelle librerie client di Pub/Sub Lite. Può essere disattivato utilizzando le impostazioni del client dell'editore nella rispettiva libreria client.
Se la pubblicazione idempotente è abilitata, l'offset restituito in un risultato della pubblicazione
potrebbe essere -1
. Questo valore viene restituito quando il messaggio viene identificato come un duplicato di un messaggio già pubblicato, ma il server non disponeva di informazioni sufficienti per restituire l'offset del messaggio al momento della pubblicazione.
I messaggi ricevuti dai sottoscrittori hanno sempre un offset valido.
Risoluzione dei problemi
Duplicati ricevuti
Poiché l'idempotenza è limitata a una singola sessione, potrebbero essere ricevuti dei duplicati se ricrei il client del publisher per pubblicare gli stessi messaggi.
Un client sottoscrittore può ricevere lo stesso messaggio più volte se le partizioni vengono assegnate automaticamente ai sottoscrittori dal servizio Pub/Sub Lite (impostazione predefinita). Un messaggio potrebbe essere recapitato nuovamente al client di un altro sottoscrittore quando si verifica una riassegnazione.
Errore del publisher
Lo stato di una sessione del publisher è la garbage collection sul server dopo 7 giorni di inattività. Se una sessione viene ripresa dopo questo periodo di tempo, il client del publisher termina con un messaggio di errore simile a "Non riuscita Condizione: è previsto che il messaggio abbia un numero di sequenza di pubblicazione..." e non accetta nuovi messaggi. Ricrea il client del publisher per risolvere questo errore.