Questo documento fornisce una panoramica di un abbonamento pull, del relativo flusso di lavoro e delle proprietà associate.
In una sottoscrizione pull, il client sottoscrittore richiede i 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. Puoi anche scegliere tra l'elaborazione dei messaggi asincrona e sincrona.
Prima di iniziare
Prima di leggere questo documento, assicurati di conoscere quanto segue:
Come funziona Pub/Sub e i diversi termini di Pub/Sub.
I diversi tipi di abbonamenti supportati da Pub/Sub e il motivo per cui potresti voler utilizzare un abbonamento pull.
Flusso di lavoro della sottoscrizione pull
Per una sottoscrizione pull, il client sottoscrittore avvia richieste a un server Pub/Sub per recuperare i messaggi. Il client abbonato utilizza una delle seguenti API:
La maggior parte dei client abbonati non effettua direttamente queste richieste. I client si basano invece sulla libreria client di alto livello fornita da Trusted Cloud by S3NS, che esegue internamente le richieste pull di streaming e invia i messaggi in modo asincrono. Per un client abbonato che ha bisogno di un maggiore controllo su come vengono recuperati i messaggi, Pub/Sub utilizza una libreria gRPC di basso livello generata automaticamente. Questa libreria crea direttamente richieste pull o pull di streaming. Queste richieste possono essere sincrone o asincrone.
Le due immagini seguenti mostrano il flusso di lavoro tra un client sottoscrittore e un abbonamento pull.


Pull workflow
Il flusso di lavoro pull è il seguente e fa riferimento alla figura 1:
- Il client sottoscrittore chiama esplicitamente il metodo
pull
, che richiede i messaggi per la consegna. Questa richiesta èPullRequest
come mostrato nell'immagine. Il server Pub/Sub risponde con zero o più messaggi e ID di riconoscimento. Una risposta con zero messaggi o con un errore non indica necessariamente che non sono disponibili messaggi da ricevere. Questa risposta è
PullResponse
come mostrato nell'immagine.Il client sottoscrittore chiama esplicitamente il metodo
acknowledge
. Il client utilizza l'ID riconoscimento restituito per confermare che il messaggio è stato elaborato e non deve essere inviato di nuovo.
Per una singola richiesta di pull di streaming, un client abbonato può ricevere più risposte a causa della connessione aperta. Al contrario, per ogni richiesta pull viene restituita una sola risposta.
Proprietà di una sottoscrizione pull
Le proprietà che configuri per una sottoscrizione pull determinano la modalità di scrittura dei messaggi nella sottoscrizione. Per ulteriori informazioni, consulta la sezione sulle proprietà dell'abbonamento.
API di servizio Pub/Sub
La sottoscrizione pull Pub/Sub può utilizzare una delle due API seguenti per recuperare i messaggi:
- Pull
- StreamingPull
Utilizza le RPC unarie Acknowledge e ModifyAckDeadline quando ricevi messaggi utilizzando queste API. Le due API Pub/Sub sono descritte nelle sezioni seguenti.
API StreamingPull
Ove possibile, le librerie client Pub/Sub utilizzano StreamingPull per la massima velocità effettiva e la latenza più bassa. Anche se potresti non utilizzare mai direttamente l'API StreamingPull, è importante sapere in che modo differisce dall'API Pull.
L'API StreamingPull si basa su una connessione bidirezionale persistente per ricevere più messaggi man mano che diventano disponibili. Di seguito è riportato il flusso di lavoro:
Il client invia una richiesta al server per stabilire una connessione. Se la quota di connessioni viene superata, il server restituisce un errore di esaurimento delle risorse. La libreria client riprova automaticamente gli errori relativi alla quota.
Se non si verifica alcun errore o 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. Tuttavia, la connessione non è interrotta. Lo stream riprende non appena la quota di throughput disponibile è sufficiente.
Il client o il server alla fine chiude la connessione.
L'API StreamingPull mantiene una connessione aperta. I server Pub/Sub chiudono periodicamente la connessione dopo un periodo di tempo per evitare una connessione persistente di lunga durata. La libreria client riapre automaticamente una connessione StreamingPull.
I messaggi vengono inviati alla connessione quando sono disponibili. L'API StreamingPull riduce al minimo la latenza e massimizza la velocità effettiva per i messaggi.
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 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 si verifica alcun errore o la quota di velocità effettiva è di nuovo disponibile, il server risponde con zero o più messaggi e ID di riconoscimento.
Quando si utilizza l'API Pull unaria, una risposta con zero messaggi o con un errore non indica necessariamente che non sono disponibili messaggi da ricevere.
L'utilizzo dell'API Pull non garantisce una bassa latenza e un'elevata velocità effettiva dei messaggi. Per ottenere un throughput elevato e una bassa latenza con l'API Pull, devi avere più richieste simultanee in sospeso. Le nuove richieste vengono create quando le vecchie richieste ricevono una risposta. Progettare una soluzione di questo tipo è soggetto a errori e difficile da gestire. Ti consigliamo di utilizzare l'API StreamingPull per questi casi d'uso.
Utilizza l'API Pull anziché l'API StreamingPull solo se richiedi un controllo rigoroso su quanto segue:
- Il numero di messaggi che il client sottoscrittore può elaborare
- Memoria e risorse del client
Puoi utilizzare questa API anche quando l'abbonato è un proxy tra Pub/Sub e un altro servizio che opera in modo più orientato al pull.
Scopri di più sui metodi REST 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à di pull per i client abbonati.
Modalità pull asincrona
La modalità pull asincrona disaccoppia la ricezione dei messaggi dall'elaborazione dei messaggi in un client sottoscrittore. Questa modalità è predefinita per la maggior parte dei client abbonati. La modalità pull asincrona può utilizzare l'API StreamingPull o l'API Pull unaria. Il pull asincrono può utilizzare anche la libreria client di alto livello o la libreria client di basso livello generata automaticamente.
Puoi scoprire di più sulle librerie client più avanti in questo documento.
Modalità sincrona
Nella modalità pull sincrona, la ricezione e l'elaborazione dei messaggi avvengono in sequenza e non sono disaccoppiate tra loro. Pertanto, in modo simile alle API StreamingPull rispetto alle API Pull unarie, l'elaborazione asincrona offre latenza inferiore e throughput più elevato rispetto all'elaborazione sincrona.
Utilizza la modalità pull sincrona solo per le applicazioni in cui la bassa latenza e l'alta velocità effettiva non sono i fattori più importanti rispetto ad altri requisiti. Ad esempio, un'applicazione potrebbe essere limitata all'utilizzo solo del modello di programmazione sincrona. In alternativa, un'applicazione con vincoli di risorse potrebbe richiedere un controllo più preciso di memoria, rete o CPU. In questi casi, utilizza la modalità sincrona con l'API Pull unaria.
Librerie client Pub/Sub
Pub/Sub offre una libreria client di alto e basso livello generata automaticamente.
Libreria client Pub/Sub di alto livello
La libreria client di alto livello fornisce opzioni per controllare le scadenze di conferma utilizzando la gestione del leasing. Queste opzioni sono più granulari rispetto a quando configuri le scadenze di riconoscimento utilizzando la console o la CLI a livello di abbonamento. La libreria client di alto livello implementa anche il supporto per funzionalità come la consegna ordinata, la consegna exactly-once e il controllo del flusso.
Ti consigliamo di utilizzare il pull asincrono e l'API StreamingPull con la libreria client di alto livello. Non tutte le lingue supportate per Trusted Cloud by S3NS 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 di basso livello generata automaticamente
È disponibile una libreria client di basso livello per i casi in cui devi utilizzare direttamente l'API Pull. Puoi utilizzare l'elaborazione sincrona o asincrona con la libreria client di basso livello generata automaticamente. Quando utilizzi la libreria client di basso livello generata automaticamente, devi codificare manualmente funzionalità come la pubblicazione ordinata, la pubblicazione esattamente una volta, il controllo del flusso e la gestione dei lease.
Puoi utilizzare il modello di elaborazione sincrona quando utilizzi la libreria client di basso livello generata automaticamente per tutti i linguaggi supportati. Potresti utilizzare la libreria client di basso livello generata automaticamente e il pull sincrono nei casi in cui l'utilizzo diretto dell'API Pull ha senso. Ad esempio, potresti avere una logica dell'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
Esempi di codice di StreamingPull e della libreria client di alto livello
C++
Prima di provare questo esempio, segui le istruzioni di configurazione di C++ nella guida rapida all'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Pub/Sub C++.
C#
Prima di provare questo esempio, segui le istruzioni di configurazione di C# nella guida rapida all'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Pub/Sub C#.
Vai
L'esempio seguente utilizza la versione principale della libreria client Go Pub/Sub (v2). Se utilizzi ancora la libreria v1, consulta la guida alla migrazione alla v2. Per visualizzare un elenco di esempi di codice della versione 1, consulta gli esempi di codice ritirati.
Prima di provare questo esempio, segui le istruzioni di configurazione di Go nella guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Go.
Java
Prima di provare questo esempio, segui le istruzioni di configurazione di Java nella guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Java di Pub/Sub.
Node.js
Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js nella Guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Node.js.
Node.js
Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js nella Guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Node.js.
Python
Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Python.
Ruby
Il seguente esempio utilizza la libreria client Ruby Pub/Sub v3. Se utilizzi ancora la libreria v2, consulta la guida alla migrazione alla v3. Per visualizzare un elenco di esempi di codice Ruby v2, consulta gli esempi di codice ritirati.
Prima di provare questo esempio, segui le istruzioni di configurazione di Ruby nella guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Ruby.
Recuperare gli attributi personalizzati utilizzando la libreria client di alto livello
Gli esempi riportati di seguito mostrano come estrarre i messaggi in modo asincrono e recuperare gli attributi personalizzati dai metadati.
C++
Prima di provare questo esempio, segui le istruzioni di configurazione di C++ nella guida rapida all'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Pub/Sub C++.
C#
Prima di provare questo esempio, segui le istruzioni di configurazione di C# nella guida rapida all'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Pub/Sub C#.
Vai
L'esempio seguente utilizza la versione principale della libreria client Go Pub/Sub (v2). Se utilizzi ancora la libreria v1, consulta la guida alla migrazione alla v2. Per visualizzare un elenco di esempi di codice della versione 1, consulta gli esempi di codice ritirati.
Prima di provare questo esempio, segui le istruzioni di configurazione di Go nella guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Go.
Java
Prima di provare questo esempio, segui le istruzioni di configurazione di Java nella guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Java di Pub/Sub.
Node.js
Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js nella Guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Node.js.
Python
Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Python.
Ruby
Il seguente esempio utilizza la libreria client Ruby Pub/Sub v3. Se utilizzi ancora la libreria v2, consulta la guida alla migrazione alla v3. Per visualizzare un elenco di esempi di codice Ruby v2, consulta gli esempi di codice ritirati.
Prima di provare questo esempio, segui le istruzioni di configurazione di Ruby nella guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Ruby.
Gestire gli errori utilizzando la libreria client di alto livello
Gli esempi riportati di seguito mostrano come gestire gli errori che si verificano durante la sottoscrizione ai messaggi.
C++
Prima di provare questo esempio, segui le istruzioni di configurazione di C++ nella guida rapida all'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Pub/Sub C++.
Vai
L'esempio seguente utilizza la versione principale della libreria client Go Pub/Sub (v2). Se utilizzi ancora la libreria v1, consulta la guida alla migrazione alla v2. Per visualizzare un elenco di esempi di codice della versione 1, consulta gli esempi di codice ritirati.
Prima di provare questo esempio, segui le istruzioni di configurazione di Go nella guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Go.
Java
Prima di provare questo esempio, segui le istruzioni di configurazione di Java nella guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Java di Pub/Sub.
Node.js
Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js nella Guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Node.js.
Python
Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Python.
Ruby
L'esempio seguente utilizza la versione principale della libreria client Go Pub/Sub (v2). Se utilizzi ancora la libreria v1, consulta la guida alla migrazione alla v2. Per visualizzare un elenco di esempi di codice della versione 1, consulta gli esempi di codice ritirati.
Prima di provare questo esempio, segui le istruzioni di configurazione di Go nella guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Go.
Esempi di codice per il pull unario
Ecco un codice campione per recuperare e confermare un numero fisso di messaggi.
C++
Prima di provare questo esempio, segui le istruzioni di configurazione di C++ nella guida rapida all'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Pub/Sub C++.
C#
Prima di provare questo esempio, segui le istruzioni di configurazione di C# nella guida rapida all'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Pub/Sub C#.
Java
Prima di provare questo esempio, segui le istruzioni di configurazione di Java nella guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Java di Pub/Sub.
Node.js
Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js nella Guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Node.js.
PHP
Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js nella Guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Node.js.
Ruby
Il seguente esempio utilizza la libreria client Ruby Pub/Sub v3. Se utilizzi ancora la libreria v2, consulta la guida alla migrazione alla v3. Per visualizzare un elenco di esempi di codice Ruby v2, consulta gli esempi di codice ritirati.
Prima di provare questo esempio, segui le istruzioni di configurazione di Ruby nella guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Ruby.
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 nella guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Python.
Pub/Sub fornisce un elenco di messaggi. Se l'elenco contiene più messaggi, Pub/Sub ordina i messaggi con la stessa chiave di ordinamento. Di seguito sono riportate alcune avvertenze importanti:
L'impostazione di un valore per
max_messages
nella richiesta non garantisce che vengano restituitimax_messages
, anche se ci sono molti messaggi nel backlog. L'API Pub/Sub Pull potrebbe restituire meno dimax_messages
per ridurre la latenza di consegna dei messaggi che sono immediatamente disponibili per la consegna.Una risposta pull che include 0 messaggi non deve essere utilizzata come indicatore che non ci sono messaggi nel backlog. È possibile ricevere una risposta con 0 messaggi e avere una richiesta successiva che restituisce messaggi.
Per ottenere una bassa latenza di distribuzione dei messaggi con la modalità pull unario, è essenziale avere molte richieste di pull in sospeso contemporaneamente. Man mano che aumenta la velocità effettiva dell'argomento, sono necessarie più richieste pull. In generale, la modalità StreamingPull è preferibile per le applicazioni sensibili alla latenza.
Quote e limiti
Le connessioni Pull e StreamingPull sono soggette a quote e limiti. Per maggiori informazioni, consulta Quote e limiti di Pub/Sub.
Passaggi successivi
Crea una sottoscrizione pull per l'argomento.
Risolvi i problemi relativi a una sottoscrizione pull.
Crea o modifica un abbonamento con gcloud CLI.
Crea o modifica un abbonamento con le API REST.
Crea o modifica un abbonamento con le API RPC.