Questa pagina spiega come ricevere e confermare i messaggi utilizzando la semantica "exactly-once". Solo il tipo di sottoscrizione pull supporta la distribuzione "exactly-once", inclusi gli abbonati che utilizzano l'API StreamingPull.
Le sottoscrizioni di push ed esportazione non supportano la consegna "exactly-once".
Versioni consigliate della libreria client
- Per ottenere prestazioni ottimali, utilizza l'ultima versione della libreria client, Python v2.13.6 o successiva, Java v1.120.11 o successiva, PHP v1.39.0 o successiva, C# v3.2.0 o successiva, C++ v2.1.0, Go 1.v1 o successiva{/1.v1}v 1.v1 o successiva{/1.v1}v
Consegna "exactly-once"
Pub/Sub supporta la consegna "exactly-once", all'interno di una regione cloud, in base a un ID messaggio univoco definito da Pub/Sub.
Quando la funzionalità è abilitata, Pub/Sub fornisce quanto segue:
Una volta che il messaggio è stato confermato, non si verifica alcun nuovo recapito.
Quando un messaggio è in sospeso, non viene eseguito alcun nuovo recapito. Un messaggio viene considerato in sospeso fino alla scadenza della scadenza della conferma o fino alla sua conferma.
In caso di più consegne valide, a causa della scadenza della scadenza della conferma o della conferma negativa avviata dal client, è possibile utilizzare solo l'ID di conferma più recente per confermare il messaggio. Eventuali richieste con un ID di conferma precedente non andranno a buon fine.
Ripubblicazione e duplicazione
È importante capire la differenza tra caricamenti previsti e ricaricati inaspettati.
Una nuova consegna può verificarsi a causa della conferma negativa di un messaggio avviata dal client o quando il client non estende la scadenza per la conferma del messaggio prima della scadenza della conferma. I ricaricamenti sono considerati validi e il sistema funziona come previsto.
Per risolvere i problemi relativi ai nuovi caricamenti, consulta Gestire i duplicati e forzare i nuovi tentativi.
Si verifica un duplicato quando un messaggio viene inviato nuovamente dopo una conferma di accettazione o prima della scadenza della scadenza della conferma.
Un messaggio ricaricato conserva lo stesso ID messaggio tra un tentativo di nuova consegna e l'altro.
Gli abbonamenti con la consegna "exactly-once" abilitata non ricevono caricamenti duplicati.
Supporto per la distribuzione "exactly-once" nelle librerie client
Le librerie client supportate hanno un'interfaccia per il riconoscimento con risposta (esempio: Go). Puoi utilizzare questa interfaccia per verificare se la richiesta di conferma è andata a buon fine. Se la richiesta di conferma ha esito positivo, i client hanno la certezza che non riceveranno una nuova consegna. Se la richiesta di conferma non va a buon fine, i clienti possono aspettarsi una nuova pubblicazione.
I client possono utilizzare anche le librerie client supportate senza l'interfaccia di conferma. Tuttavia, in questi casi, gli errori di conferma possono comportare il reinvio silenzioso dei messaggi.
Le librerie client supportate hanno interfacce per l'impostazione del tempo minimo di estensione per il lease (ad esempio: Go). Devi impostare un numero elevato per l'estensione di lease minima per evitare scadenze di conferma correlate alla rete. Il valore massimo è impostato su 600 secondi.
I valori predefiniti e l'intervallo per le variabili relative alla pubblicazione "exactly-once" e i nomi delle variabili potrebbero variare a seconda delle librerie client. Ad esempio, nella libreria client Java, le seguenti variabili controllano la distribuzione "exactly-once".
Variabile | Descrizione | Valore |
---|---|---|
setEnableExactlyOnceDelivery |
Attiva o disattiva la consegna "exactly-once". | true o false Predefinito=falso |
minDurationPerAckExtension |
Il tempo minimo in secondi da utilizzare per estendere la scadenza per la conferma della modifica. | Intervallo=da 0 a 600 Valore predefinito=nessuno |
maxDurationPerAckExtension |
Il tempo massimo in secondi da utilizzare per estendere la scadenza per la conferma della modifica. | Intervallo=da 0 a 600 Valore predefinito=nessuno |
Nel caso della consegna "exactly-once", la richiesta modifyAckDeadline
o acknowledgment
a Pub/Sub non va a buon fine quando l'ID di conferma è già scaduto. In questi casi, il servizio considera l'ID di conferma scaduto come non valido, poiché una distribuzione più recente potrebbe essere già in corso. Questo è progettato per la
pubblicazione "exactly-once". Quindi vedrai le richieste acknowledgment
e ModifyAckDeadline
che restituiscono una
risposta INVALID_ARGUMENT
. Quando la pubblicazione "exactly-once" viene disattivata, queste richieste restituiscono OK
nel caso di ID di conferma scaduti.
Per assicurarti che le richieste acknowledgment
e ModifyAckDeadline
abbiano ID di conferma validi, valuta la possibilità di impostare il valore per minDurationPerAckExtension
su un numero elevato.
Creare sottoscrizioni con consegna "exactly-once"
Puoi creare un abbonamento con la consegna "exactly-once" utilizzando la console Google Cloud, Google Cloud CLI, la libreria client o l'API Pub/Sub.
Esegui il pull della sottoscrizione
Console
Per creare una sottoscrizione pull con consegna "exactly-once", segui questi passaggi:
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 Pubblicazione esatta una volta, seleziona Attiva la consegna "esattamente una volta".
Fai clic su Crea.
gcloud
Per creare una sottoscrizione pull con la consegna "exactly-once", utilizza il comando gcloud pubsub subscriptions create
con il flag --enable-exactly-once-delivery
:
gcloud pubsub subscriptions create SUBSCRIPTION_ID \ --topic=TOPIC_ID \ --enable-exactly-once-delivery
Sostituisci quanto segue:
- SUBSCRIPTION_ID: l'ID della sottoscrizione da creare
- TOPIC_ID: l'ID dell'argomento da collegare alla sottoscrizione
REST
Per creare un abbonamento con consegna "exactly-once", 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 del progetto in cui creare la sottoscrizione
- SUBSCRIPTION_ID: l'ID della sottoscrizione da creare
Per creare una sottoscrizione pull con consegna "exactly-once", specifica quanto segue nel corpo della richiesta:
{ "topic": "projects/PROJECT_ID/topics/TOPIC_ID", "enableExactlyOnceDelivery": true, }
Sostituisci quanto segue:
- PROJECT_ID: l'ID del progetto con l'argomento
- TOPIC_ID: l'ID dell'argomento da collegare alla sottoscrizione
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.
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.
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.
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.
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.
Abbonati con la consegna del messaggio "exactly-once"
Di seguito sono riportati alcuni esempi di codice per l'iscrizione con la consegna "exactly-once" utilizzando la libreria client.
Esegui il pull della sottoscrizione
Go
Prima di provare questo esempio, segui le istruzioni di configurazione di Go nella guida rapida di Pub/Sub sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Go di Pub/Sub.
Per eseguire l'autenticazione in Pub/Sub, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Java
Prima di provare questo esempio, segui le istruzioni di configurazione di Java nella guida rapida di Pub/Sub sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Java di Pub/Sub.
Per eseguire l'autenticazione in Pub/Sub, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Node.js
Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js nella guida rapida di Pub/Sub sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Node.js di Pub/Sub.
Per eseguire l'autenticazione in Pub/Sub, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
PHP
Prima di provare questo esempio, segui le istruzioni di configurazione di PHP nella guida rapida di Pub/Sub sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API PHP di Pub/Sub.
Per eseguire l'autenticazione in Pub/Sub, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Python
Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di Pub/Sub sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Python di Pub/Sub.
Per eseguire l'autenticazione in Pub/Sub, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Ruby
Prima di provare questo esempio, segui le istruzioni di configurazione di Ruby nella guida rapida di Pub/Sub sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Ruby di Pub/Sub.
Per eseguire l'autenticazione in Pub/Sub, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
C++
Prima di provare questo esempio, segui le istruzioni di configurazione di C++ nella guida rapida di Pub/Sub sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API C++ di Pub/Sub.
Per eseguire l'autenticazione in Pub/Sub, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
C#
Prima di provare questo esempio, segui le istruzioni di configurazione di C# nella guida rapida di Pub/Sub sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API C# di Pub/Sub.
Per eseguire l'autenticazione in Pub/Sub, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Node.js (TypeScript)
Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js nella guida rapida di Pub/Sub sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Node.js Pub/Sub.
Per eseguire l'autenticazione in Pub/Sub, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Monitorare le sottoscrizioni con pubblicazione "exactly-once"
La metrica subscription/exactly_once_warning_count
registra il numero di eventi che possono portare a possibili ricaricamenti (validi o duplicati). Questa metrica conteggia il numero di volte in cui Pub/Sub non riesce a elaborare le richieste associate agli ID di conferma (richiesta ModifyAckDeadline
o acknowledgment
). I motivi dell'errore potrebbero essere basati sul server o sul client. Ad esempio, se il livello di persistenza utilizzato per mantenere le informazioni di consegna "exactly-once" non è disponibile, si tratta di un evento basato su server. Se il client cerca di confermare un messaggio con un ID di conferma non valido, si tratta di un evento basato su client.
Comprendere la metrica
subscription/exactly_once_warning_count
acquisisce gli eventi che potrebbero determinare o meno
ricaricamenti effettivi e, in base al comportamento del cliente, possono presentare problemi. Ad esempio, le richieste acknowledgment
o ModifyAckDeadline
ripetute con ID di conferma non validi incrementano la metrica ripetutamente.
Le seguenti metriche sono utili anche per comprendere il comportamento del cliente:
La metrica
subscription/expired_ack_deadlines_count
mostra il numero di scadenze dell'ID di conferma. La scadenza dell'ID di conferma può causare errori per le richiesteModifyAckDeadline
eacknowledgment
.La metrica
service.serviceruntime.googleapis.com/api/request_count
può essere utilizzata per acquisire gli errori delle richiesteModifyAckDeadline
oacknowledgment
nei casi in cui queste raggiungano Google Cloud, ma non raggiungino Pub/Sub. Si sono verificati errori che questa metrica non acquisirà, ad esempio quando i client sono disconnessi da Google Cloud.
Nella maggior parte dei casi di eventi di errore che è possibile riprovare, le librerie client supportate riprovano automaticamente la richiesta.
Quote
Le sottoscrizioni con pubblicazione "exactly-once" sono soggette a requisiti di quota aggiuntivi. Questa quota viene applicata a:
- Numero di messaggi utilizzati dalle sottoscrizioni con la consegna "exactly-once" abilitata per regione.
- Numero di messaggi confermati o la cui scadenza è estesa se si utilizzano abbonamenti con la consegna "exactly-once" abilitata per regione.
Per ulteriori informazioni su queste quote, consulta la tabella nell'argomento Quote.
Consegna "exactly-once" e abbonamenti ordinati
Pub/Sub supporta la consegna "exactly-once" con la consegna ordinata.
Quando utilizzi l'ordinamento con la consegna "exactly-once", Pub/Sub si aspetta che le conferme siano in ordine. Se le conferme sono nell'ordine sbagliato, il servizio non supera le richieste con errori temporanei. Se la scadenza per la conferma scade prima della conferma dell'ordine per la consegna, il client riceverà un nuovo recapito del messaggio. Per questo motivo, quando utilizzi l'ordinamento con la consegna "exactly-once", la velocità effettiva del client è limitata a un ordine di migliaia di messaggi al secondo.
Consegna "exactly-once" e abbonamenti push
Pub/Sub supporta la distribuzione "exactly-once" solo con le sottoscrizioni pull.
I client che utilizzano i messaggi delle sottoscrizioni push confermano i messaggi rispondendo alle richieste push con una risposta corretta. Tuttavia, i client non sanno se la sottoscrizione Pub/Sub ha ricevuto la risposta e l'ha elaborata. È diverso dalle sottoscrizioni pull, in cui le richieste di conferma vengono avviate dai client e la sottoscrizione Pub/Sub risponde se la richiesta è stata elaborata correttamente. Per questo motivo, la semantica della consegna "exactly-once" non è in linea con le sottoscrizioni push.
Aspetti da tenere presenti
Se la scadenza per la conferma non è specificata al momento di CreateSubscription, le sottoscrizioni abilitate per la pubblicazione "exactly-once" avranno una scadenza predefinita di conferma di 60 secondi.
Scadenze di conferma più lunghe sono utili per evitare la ripubblicazione causata da eventi di rete. Le librerie client supportate non utilizzano la scadenza predefinita di conferma degli abbonamenti.
Gli abbonamenti con pubblicazione "exactly-once" hanno una latenza di pubblicazione-sottoscrizione significativamente maggiore rispetto agli abbonamenti normali.
Se richiedi una velocità effettiva elevata, i client di distribuzione "exactly-once" devono anche utilizzare il streaming pull.
Una sottoscrizione potrebbe ricevere più copie dello stesso messaggio a causa di duplicati sul lato di pubblicazione, anche con la consegna "exactly-once" abilitata. I duplicati lato pubblicazione possono essere dovuti a più nuovi tentativi di pubblicazione univoci da parte del client di pubblicazione o del servizio Pub/Sub. Più pubblicazioni univoche da parte del cliente editore, tra diversi tentativi, portano a nuovi caricamenti con ID messaggio diversi. Più pubblicazioni univoche da parte del servizio Pub/Sub, per rispondere a una richiesta di pubblicazione del cliente, comportano il ricaricamento con gli stessi ID messaggio.
Puoi riprovare a risolvere gli errori in
subscription/exactly_once_warning_count
. Le librerie client supportate li ripeteranno automaticamente. Tuttavia, gli errori relativi a ID di conferma non validi non possono essere riprovati.