In questa pagina viene spiegato come pubblicare messaggi negli argomenti Lite. Puoi pubblicare messaggi con la libreria client Pub/Sub Lite per Java.
Dopo aver pubblicato messaggi e creato una sottoscrizione Lite in un argomento Lite, puoi ricevere messaggi dalla sottoscrizione Lite.
Formato dei messaggi
Un messaggio è costituito da campi contenenti i dati e i metadati del messaggio. Specifica nel messaggio quanto segue:
- I dati dei messaggi
- Una chiave di ordinazione.
- 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 streaming all'argomento Lite, quindi invia i messaggi tramite la connessione in modalità flusso.
Il seguente esempio 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 per la configurazione di Go in Librerie client di Pub/Sub Lite.
Java
Prima di eseguire questo esempio, segui le istruzioni di configurazione Java in Librerie client di Pub/Sub Lite.
Python
Prima di eseguire questo esempio, segui le istruzioni di configurazione di Python in 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 all'editore.
Utilizzo delle chiavi di ordinamento
Se i messaggi hanno la stessa chiave di ordinamento, la libreria client assegna i messaggi 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 per la configurazione di Go in Librerie client di Pub/Sub Lite.
Java
Prima di eseguire questo esempio, segui le istruzioni di configurazione Java in Librerie client di Pub/Sub Lite.
Python
Prima di eseguire questo esempio, segui le istruzioni di configurazione di Python in Librerie client di Pub/Sub Lite.
Puoi inviare più messaggi alla stessa partizione utilizzando le chiavi di ordinamento, in modo che i sottoscrittori ricevano i messaggi in ordine. La libreria client potrebbe assegnare più chiavi di ordinamento alla stessa partizione.
Impostare l'ora dell'evento
Puoi utilizzare l'ora evento per pubblicare i messaggi Lite. L'ora dell'evento è un attributo personalizzato che puoi aggiungere al tuo 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: l'ora dell'evento specificata dall'utente. Per scoprire di più 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 di 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 messaggio
- VALUE: il valore della chiave dell'attributo del messaggio
Go
Prima di eseguire questo esempio, segui le istruzioni per la configurazione di Go in Librerie client di Pub/Sub Lite.
Java
Prima di eseguire questo esempio, segui le istruzioni di configurazione Java in Librerie client di Pub/Sub Lite.
Python
Prima di eseguire questo esempio, segui le istruzioni di configurazione di Python in 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 elaborarlo in base ai suoi attributi.
Raggruppamento dei messaggi in gruppo
La libreria client pubblica i messaggi in batch. I batch più grandi utilizzano meno risorse di calcolo, ma aumentano la latenza. Puoi modificare le dimensioni del batch con le impostazioni di batch.
Nella tabella seguente sono elencate le impostazioni di raggruppamento che puoi configurare:
Impostazione | Descrizione | Predefinito |
---|---|---|
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 di pubblicazione | Il tempo, in millisecondi, tra l'aggiunta del messaggio a un batch e l'invio del batch all'argomento Lite. | 50 millisecondi |
Puoi configurare le impostazioni di raggruppamento con la libreria client.
Go
Prima di eseguire questo esempio, segui le istruzioni per la configurazione di Go in Librerie client di Pub/Sub Lite.
Java
Prima di eseguire questo esempio, segui le istruzioni di configurazione Java in Librerie client di Pub/Sub Lite.
Python
Prima di eseguire questo esempio, segui le istruzioni di configurazione di Python in Librerie client di Pub/Sub Lite.
Quando un'applicazione dell'editore viene avviata, la libreria client crea un batch per ogni partizione in un argomento Lite. Ad esempio, se un argomento Lite ha due partizioni, gli editori creano due batch e inviano ogni batch a una partizione.
Dopo aver pubblicato un messaggio, la libreria client esegue il buffering 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 loro pubblicazione. Per assegnare i messaggi alla stessa partizione, utilizza una chiave di ordinamento.
Pub/Sub Lite recapita i messaggi da una partizione in ordine e i sottoscrittori possono elaborarli in ordine. Per maggiori dettagli, vedi Ricezione di messaggi.
Pubblica idempotenza
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 viene tentata una nuova pubblicazione 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 dell'editore. Non comporta costi di servizio aggiuntivi né aumenta la latenza di pubblicazione.
Attiva o disattiva la pubblicazione idempotente
La pubblicazione idempotente è abilitata per impostazione predefinita nelle librerie client di Pub/Sub Lite. Può essere disattivata utilizzando le impostazioni del client dell'editore nella rispettiva libreria client.
Se la pubblicazione idempotente è abilitata, l'offset restituito in un risultato di pubblicazione
potrebbe essere -1
. Questo valore viene restituito quando il messaggio viene identificato come 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 duplicati se ricrei il client dell'editore per pubblicare gli stessi messaggi.
Un client sottoscrittore potrebbe 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 a un client di un altro sottoscrittore quando si verifica una riassegnazione.
Errore del publisher
Lo stato di una sessione del publisher è la garbage collection nel server dopo 7 giorni di inattività. Se una sessione viene ripresa dopo questo periodo di tempo, il client dell'editore viene chiuso con un messaggio di errore simile a "Precondizione non riuscita: il messaggio previsto deve contenere un numero di sequenza di pubblicazione di..." e non accetta nuovi messaggi. Ricrea il client del publisher per risolvere l'errore.