Questo documento fornisce una panoramica di una sottoscrizione pull, del relativo flusso di lavoro e delle proprietà associate.
In una sottoscrizione pull, un client di un sottoscrittore richiede messaggi al server Pub/Sub.
La modalità pull può utilizzare una delle due API di servizio, Pull o StreamingPull. Per eseguire l'API scelta, puoi selezionare una libreria client di alto livello fornita da Google o una libreria client di basso livello generata automaticamente. Inoltre, puoi scegliere tra elaborazione asincrona e sincrona dei messaggi.
Prima di iniziare
Prima di leggere questo documento, assicurati di acquisire familiarità con quanto segue:
Come funziona Pub/Sub e i diversi termini di Pub/Sub.
I diversi tipi di sottoscrizioni supportati da Pub/Sub e perché potresti utilizzare una sottoscrizione pull.
Esegui il pull del flusso di lavoro della sottoscrizione
Per una sottoscrizione pull, il client del sottoscrittore avvia le richieste a un server Pub/Sub per recuperare i messaggi. Il client abbonato utilizza una delle seguenti API:
La maggior parte dei clienti abbonati non effettua queste richieste direttamente. I client si affidano invece alla libreria client di alto livello fornita da Google Cloud, che esegue internamente le richieste di pull in modalità flusso e recapita i messaggi in modo asincrono. Per un client sottoscrittore che ha bisogno di un maggiore controllo sulle modalità di pull dei messaggi, Pub/Sub utilizza una libreria gRPC di basso livello generata automaticamente. che invia richieste pull o flussi di dati pull direttamente. Queste richieste possono essere sincrone o asincrone.
Le due immagini seguenti mostrano il flusso di lavoro tra un client abbonato e una sottoscrizione pull.
Esegui il pull del flusso di lavoro
Il flusso di lavoro pull è il seguente e fa riferimento alla Figura 1:
- Il client dell'abbonato chiama esplicitamente il metodo
pull
, che richiede la consegna dei messaggi. Questa richiesta è l'oggettoPullRequest
, come mostrato nell'immagine. Il server Pub/Sub risponde con zero o più messaggi e ID di conferma. Una risposta con zero messaggi o con un errore non indica necessariamente che non sono disponibili messaggi da ricevere. Questa risposta è il
PullResponse
, come mostrato nell'immagine.Il client dell'abbonato chiama esplicitamente il metodo
acknowledge
. Il client utilizza l'ID di conferma restituito per confermare che il messaggio è stato elaborato e non deve essere recapitato di nuovo.
Per una singola richiesta di pull in modalità flusso, il client di un sottoscrittore può ricevere più risposte a causa della connessione aperta. Al contrario, viene restituita una sola risposta per ogni richiesta di pull.
Proprietà di una sottoscrizione pull
Le proprietà configurate per una sottoscrizione pull determinano il modo in cui scrivi i messaggi nella sottoscrizione. Per ulteriori informazioni, consulta le proprietà dell'abbonamento.
API del servizio Pub/Sub
La sottoscrizione pull di Pub/Sub può utilizzare una delle seguenti due API per recuperare i messaggi:
- Pull
- StreamingPull
Utilizza le RPC unary Acknowledge e ChangeAckDeadline quando ricevi messaggi utilizzando queste API. Le due API Pub/Sub sono descritte nelle schede seguenti.
API StreamingPull
Ove possibile, le librerie client Pub/Sub utilizzano StreamingPull per la massima velocità effettiva e la latenza minima. Anche se potresti non usare mai direttamente l'API StreamingPull, è importante sapere in che modo differisce dall'API Pull.
L'API StreamingPull si basa su una connessione bidirezionale permanente per ricevere più messaggi non appena diventano disponibili. Di seguito è riportato il flusso di lavoro:
Il client invia una richiesta al server per stabilire una connessione. Se la quota di connessione viene superata, il server restituisce un errore di risorse esaurite. La libreria client riprova automaticamente gli errori fuori quota.
Se non ci sono errori o se la quota di connessione è di nuovo disponibile, il server invia continuamente messaggi al client connesso.
Se o quando la quota di velocità effettiva viene superata, il server smette di inviare messaggi. ma la connessione non si interrompe. Ogni volta che è disponibile una quota di velocità effettiva sufficiente, il flusso riprende.
Il client o il server chiude la connessione.
L'API StreamingPull mantiene una connessione aperta. I server Pub/Sub chiudono periodicamente la connessione dopo un determinato periodo di tempo per evitare una connessione persistente a lunga esecuzione. La libreria client riapre automaticamente una connessione StreamingPull.
I messaggi vengono inviati alla connessione quando sono disponibili. L'API StreamingPull consente così di ridurre al minimo la latenza e massimizzare la velocità effettiva dei messaggi.
Scopri di più sui metodi REST StreamingPull: StreamingPullRequest e StreamingPullResponse.
Scopri di più sui metodi RPC StreamingPull: StreamingPullRequest e StreamingPullResponse.
API Pull
Questa API è una RPC unaria tradizionale basata su un modello di richiesta e risposta. Una singola risposta pull corrisponde a una singola richiesta di pull. Di seguito è riportato il flusso di lavoro:
Il client invia una richiesta di messaggi al server. Se la quota di velocità effettiva viene superata, il server restituisce un errore di esaurimento delle risorse.
Se non ci sono errori o se la quota di velocità effettiva è di nuovo disponibile, il server risponde con zero o più messaggi e ID di conferma.
Quando si utilizza l'API Pull unario, una risposta con zero messaggi o con un errore non indica necessariamente che non ci sono messaggi disponibili da ricevere.
L'utilizzo dell'API Pull non garantisce una bassa latenza e un'elevata velocità effettiva dei messaggi. Per ottenere una velocità effettiva elevata e una bassa latenza con l'API Pull, devi avere più richieste in sospeso simultanee. Le nuove richieste vengono create quando richieste precedenti ricevono una risposta. L'architettura di una soluzione di questo tipo è soggetta a errori e difficile da gestire. Ti consigliamo di usare l'API StreamingPull per questi casi d'uso.
Utilizza l'API Pull anziché l'API StreamingPull solo se hai bisogno di un controllo rigoroso su quanto segue:
- Il numero di messaggi che il client del sottoscrittore può elaborare
- La memoria e le risorse del client
Puoi utilizzare questa API anche quando il tuo sottoscrittore è un proxy tra Pub/Sub e un altro servizio che opera in modo più orientato al pull.
Scopri di più sui metodi REST di pull: Metodo: projects.subscriptions.pull.
Scopri di più sui metodi RPC pull: PullRequest e PullResponse.
Tipi di modalità di elaborazione dei messaggi
Scegli una delle seguenti modalità pull per i client degli abbonati.
Modalità pull asincrona
La modalità pull asincrono disaccoppia la ricezione dei messaggi dall'elaborazione dei messaggi in un client del sottoscrittore. Questa è la modalità predefinita per la maggior parte dei client abbonati. La modalità pull asincrono può usare l'API StreamingPull o l'API Unary Pull. Il pull asincrono può anche usare la libreria client di alto livello o la libreria client di basso livello generata automaticamente.
Per ulteriori informazioni sulle librerie client, consulta le sezioni successive di questo documento.
Modalità pull sincrono
In modalità pull sincrona, la ricezione e l'elaborazione dei messaggi avvengono in sequenza e non sono disaccoppiate l'una dall'altra. Di conseguenza, in modo analogo alle API StreamingPull e Pull unario, l'elaborazione asincrona offre una latenza più bassa e una velocità effettiva superiore rispetto all'elaborazione sincrona.
Utilizza la modalità di pull sincrona solo per le applicazioni in cui la bassa latenza e la velocità effettiva elevata non sono i fattori più importanti rispetto ad altri requisiti. Ad esempio, un'applicazione potrebbe essere limitata all'uso del modello di programmazione sincrono. Oppure, un'applicazione con vincoli delle risorse potrebbe richiedere un controllo più esatto su memoria, rete o CPU. In questi casi, utilizza la modalità sincrona con l'API Pull unario.
Librerie client Pub/Sub
Pub/Sub offre una libreria client di alto e di basso livello generata automaticamente.
Libreria client Pub/Sub di alto livello
La libreria client di alto livello offre opzioni per controllare le scadenze di conferma utilizzando la gestione del lease. Queste opzioni sono più granulari rispetto alla configurazione delle scadenze di conferma utilizzando la console o l'interfaccia a riga di comando a livello di abbonamento. La libreria client di alto livello implementa anche il supporto per funzionalità come la distribuzione ordinata, la distribuzione "exactly-once" e il controllo del flusso.
Consigliamo di utilizzare il pull asincrono e l'API StreamingPull con la libreria client di alto livello. Non tutti i linguaggi supportati da Google Cloud supportano anche l'API Pull nella libreria client di alto livello.
Per utilizzare le librerie client di alto livello, consulta librerie client Pub/Sub.
Libreria client Pub/Sub generata automaticamente di basso livello
È disponibile una libreria client di basso livello per i casi in cui devi utilizzare direttamente l'API Pull. Puoi usare l'elaborazione sincrona o asincrona con la libreria client di basso livello generata automaticamente. Quando utilizzi la libreria client generata automaticamente di basso livello, devi codificare manualmente funzionalità come la pubblicazione ordinata, la consegna "exactly-once", il controllo del flusso e la gestione del lease.
Puoi utilizzare il modello di elaborazione sincrona quando usi la libreria client di basso livello generata automaticamente per tutte le lingue supportate. Potresti utilizzare la libreria client di basso livello generata automaticamente e il pull sincrono nei casi in cui l'uso diretto dell'API Pull abbia senso. Ad esempio, potresti avere una logica applicazione esistente che si basa su questo modello.
Per utilizzare direttamente le librerie client di basso livello generate automaticamente, consulta la panoramica delle API Pub/Sub.
Esempi di codice delle librerie client
StreamingPull e esempi di codice delle librerie client di alto livello
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.
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.
Recuperare gli attributi personalizzati utilizzando la libreria client di alto livello
Gli esempi riportati di seguito mostrano come eseguire il pull dei messaggi in modo asincrono e recuperare gli attributi personalizzati dai metadati.
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.
Gestire gli errori utilizzando la libreria client di alto livello
I seguenti esempi mostrano come gestire gli errori che si verificano durante l'iscrizione ai messaggi.
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.
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 Go nella Guida rapida sull'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Go Pub/Sub.
Esempi di codice pull unaario
Ecco alcuni codice campione per pull e confermare un numero fisso di messaggi.
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++ 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.
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.
PHP
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.
Protocollo
Richiesta:
POST https://pubsub.googleapis.com/v1/projects/myproject/subscriptions/mysubscription:pull
{
"returnImmediately": "false",
"maxMessages": "1"
}
Risposta:
200 OK
{
"receivedMessages": [{
"ackId": "dQNNHlAbEGEIBERNK0EPKVgUWQYyODM2LwgRHFEZDDsLRk1SK...",
"message": {
"data": "SGVsbG8gQ2xvdWQgUHViL1N1YiEgSGVyZSBpcyBteSBtZXNzYWdlIQ==",
"messageId": "19917247034"
}
}]
}
Richiesta:
POST https://pubsub.googleapis.com/v1/projects/myproject/subscriptions/mysubscription:acknowledge
{
"ackIds": [
"dQNNHlAbEGEIBERNK0EPKVgUWQYyODM2LwgRHFEZDDsLRk1SK..."
]
}
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.
Pub/Sub recapita un elenco di messaggi. Se l'elenco contiene più messaggi, Pub/Sub li ordina con la stessa chiave di ordinamento. Di seguito sono riportate alcune importanti considerazioni:
L'impostazione di un valore per
max_messages
nella richiesta non garantisce che vengano restituitimax_messages
, anche se ci sono così tanti messaggi nel backlog. L'API Pub/Sub Pull potrebbe restituire meno dimax_messages
per ridurre la latenza di consegna dei messaggi subito disponibili per la consegna.Una risposta pull che viene fornita con 0 messaggi non deve essere utilizzata come indicatore della mancanza di messaggi nel backlog. È possibile ricevere una risposta con 0 messaggi e avere una richiesta successiva che restituisce messaggi.
Per ottenere una bassa latenza di consegna dei messaggi con la modalità pull unaria, è essenziale disporre di molte richieste di pull contemporaneamente in sospeso. Con l'aumento della velocità effettiva dell'argomento, sono necessarie più richieste di pull. In generale, la modalità StreamingPull è preferibile per le applicazioni sensibili alla latenza.
Quote e limiti
Entrambe le connessioni Pull e StreamingPull sono soggette a quote e limiti. Per ulteriori informazioni, consulta Quote e limiti di Pub/Sub.
Passaggi successivi
Crea una sottoscrizione pull per il tuo argomento.
Crea o modifica una sottoscrizione con gcloud CLI.
Creare o modificare una sottoscrizione con le API REST.
Crea o modifica una sottoscrizione con le API RPC.