Questo documento fornisce una panoramica di una sottoscrizione pull, del relativo flusso di lavoro e proprietà associate.
In una sottoscrizione pull, il client sottoscrittore richiede i messaggi il server Pub/Sub.
La modalità pull può utilizzare una delle due API di servizio, Pull o StreamingPull. Per eseguire l'API scelta, puoi selezionare un client di alto livello fornito da Google libreria client o una libreria client di basso livello generata automaticamente. Puoi anche scegliere tra l'elaborazione dei messaggi asincrona e quella sincrona.
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 abbonamenti supportato da Pub/Sub e perché potrebbe essere utile utilizzare una query pull abbonamento.
Flusso di lavoro della sottoscrizione pull
Per una sottoscrizione pull, il client sottoscrittore avvia richieste a un il server Pub/Sub per recuperare i messaggi. Il client abbonato utilizza una delle seguenti API:
La maggior parte dei client sottoscrittori non effettua queste richieste direttamente. Invece, si affidano alla libreria client di alto livello fornita da Google Cloud, esegue internamente le richieste di pull in modalità flusso e recapita i messaggi in modo asincrono. Per il cliente abbonato che necessita di un maggiore controllo su come viene eseguito il pull dei messaggi, Pub/Sub usa una nella libreria gRPC generata. Questa libreria effettua richieste di pull o in modalità flusso strato Add. Queste richieste possono essere sincrone o asincrone.
Le due immagini seguenti mostrano il flusso di lavoro tra un client sottoscrittore e un sottoscrizione pull.
Flusso di lavoro pull
Il flusso di lavoro pull è il seguente e fa riferimento alla Figura 1:
- Il client del sottoscrittore chiama esplicitamente il metodo
pull
, che richiede messaggi da consegnare. Questa richiesta è l'PullRequest
, come mostrato in dell'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 indicano necessariamente che non ci sono messaggi disponibili da ricevere. Questo la risposta è
PullResponse
, come mostrato nell'immagine.Il client del sottoscrittore chiama esplicitamente il metodo
acknowledge
. Il cliente utilizza l'ID di conferma restituito per confermare che il messaggio sono elaborati e non devono essere recapitati di nuovo.
Per una singola richiesta di pull in modalità flusso, un client sottoscrittore può avere più risposte restituite a causa della connessione aperta. Al contrario, solo una risposta restituiti per ogni richiesta di pull.
Proprietà di una sottoscrizione pull
Le proprietà configurate per una sottoscrizione pull determinano il modo in cui di scrivere messaggi nella sottoscrizione. Per ulteriori informazioni, vedi proprietà abbonamento.
API di servizio Pub/Sub
La sottoscrizione al pull Pub/Sub può utilizzare uno dei le due API seguenti per il recupero dei messaggi:
- Pull
- StreamingPull
Usa le RPC Unary Acknowledge e EditAckDeadline quando ricevi i messaggi utilizzando queste API. Le due API Pub/Sub sono descritte nel le schede seguenti.
API StreamingPull
Ove possibile, le librerie client di Pub/Sub utilizzano StreamingPull per la velocità effettiva massima e la latenza più bassa. Anche se non potresti mai usare direttamente l'API StreamingPull, è importante conoscerne le differenze dall'API Pull.
L'API StreamingPull si basa su una connessione bidirezionale permanente ricevere più messaggi non appena sono disponibili. Di seguito sono riportate le flusso di lavoro personalizzato:
Il client invia una richiesta al server per stabilire una connessione. Se viene superata la quota di connessioni, il server restituisce una risorsa esaurita. . La libreria client esegue un nuovo tentativo automatico per gli errori relativi al superamento della quota.
Se non si verificano errori o se la quota di connessione è di nuovo disponibile, il server invia messaggi continui al client connesso.
Se o quando viene superata la quota di velocità effettiva, il server interrompe l'invio messaggi. Tuttavia, la connessione non si interrompe. Ogni volta che c'è quota di velocità effettiva di nuovo disponibile, il flusso riprende.
Il client o il server alla fine chiude la connessione.
L'API StreamingPull mantiene una connessione aperta. Pub/Sub i server chiudono ripetutamente la connessione dopo un determinato periodo di tempo per evitare con una connessione costante a lunga durata. La libreria client si riapre automaticamente una connessione StreamingPull.
I messaggi vengono inviati alla connessione quando sono disponibili. StreamingPull L'API riduce al minimo la latenza e massimizza la velocità effettiva per i 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 una richiesta e una risposta un modello di machine learning. 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 viene superata la quota di velocità effettiva, il server restituisce una risorsa errore di esaurimento.
Se non si verificano errori o se la quota di velocità effettiva è di nuovo disponibile, il server risposte con zero o più messaggi e ID di conferma.
Quando si utilizza l'API Pull unary, una risposta con zero messaggi o con un l'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 di messaggi. Per ottenere una velocità effettiva elevata e una bassa latenza con l'API Pull, devono avere più richieste in sospeso simultanee. Vengono create nuove richieste quando le vecchie richieste ricevono una risposta. L'architettura di una soluzione di questo tipo soggetta a errori e difficile da gestire. Ti consigliamo di utilizzare StreamingPull per questi casi d'uso.
Usa l'API Pull anziché l'API StreamingPull solo se hai bisogno controllo 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 abbonato è un proxy tra Pub/Sub e un altro servizio che opera in un ambiente 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à pull per i client sottoscrittori.
Modalità pull asincrona
La modalità pull asincrona disaccoppia la ricezione dei messaggi dall'elaborazione di messaggi in un client sottoscrittore. Questa è la modalità predefinita client sottoscrittori. La modalità pull asincrono può usare l'API StreamingPull o l'API unary Pull. Il pull asincrono può utilizzare anche la libreria client di alto livello libreria client generata automaticamente o di basso livello.
Puoi scoprire di più sulle librerie client più avanti in questo documento.
Modalità pull sincrono
In modalità pull sincrona, la ricezione e l'elaborazione dei messaggi avvengono in sequenza e non sono disaccoppiati tra loro. Pertanto, in modo simile StreamingPull e API unary Pull, l'elaborazione asincrona offre minore latenza e velocità effettiva superiore rispetto all'elaborazione sincrona.
Utilizza la modalità pull sincrona solo per le applicazioni in cui bassa latenza e alta la velocità effettiva non sono i fattori più importanti rispetto ad altri i tuoi requisiti. Ad esempio, un'applicazione potrebbe essere limitata all'utilizzo il modello di programmazione sincrona. Oppure, un'applicazione con risorse potrebbero richiedere un controllo più esatto su memoria, rete per la CPU. In questi casi, utilizza la modalità sincrona con l'API Pull unary.
Librerie client di Pub/Sub
Pub/Sub offre un'architettura di alto livello e una di basso livello libreria client.
Libreria client Pub/Sub di alto livello
La libreria client di alto livello offre opzioni per controllare delle scadenze di conferma utilizzando la gestione dei leasing. Queste opzioni sono più granulare rispetto a quando configuri le scadenze di conferma utilizzando la console o l'interfaccia a riga di comando a livello di abbonamento. Il cliente di alto livello implementano il supporto di funzionalità quali la consegna ordinata, la distribuzione "exactly-once" e il controllo del flusso.
Consigliamo di utilizzare il pull asincrono e l'API StreamingPull con libreria client di alto livello. Non tutte le lingue supportate Google Cloud supporta 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 nei casi in cui è necessario utilizzare Esegui il pull dell'API direttamente. Puoi utilizzare l'elaborazione sincrona o asincrona con la libreria client generata automaticamente di basso livello. Devi programmare manualmente funzionalità come consegna ordinata, consegna "exactly-once", controllo del flusso e gestione dei leasing quando utilizzi la libreria client di basso livello generata automaticamente.
Puoi utilizzare il modello di elaborazione sincrona quando usi il modello una libreria client generata automaticamente per tutte le lingue supportate. Potresti usare lo libreria client generata automaticamente di basso livello e pull sincrono nei casi in cui l'uso diretto dell'API Pull ha senso. Ad esempio, potresti avere della logica dell'applicazione che si basa su questo modello.
Per utilizzare direttamente le librerie client di basso livello generate automaticamente, consulta Panoramica delle API Pub/Sub.
Esempi di codice della libreria client
StreamingPull e esempi di codice della libreria client di alto livello
C++
Prima di provare questo esempio, segui le istruzioni per la configurazione di C++ in 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 C# in Guida rapida all'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API C# Pub/Sub.
Vai
Prima di provare questo esempio, segui le istruzioni di configurazione di Go in Guida rapida all'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Pub/Sub Go.
Java
Prima di provare questo esempio, segui le istruzioni di configurazione di Java in Guida rapida all'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 all'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 all'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 all'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 in Guida rapida all'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 recuperarli gli attributi personalizzati dei metadati.
C++
Prima di provare questo esempio, segui le istruzioni per la configurazione di C++ in 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 C# in Guida rapida all'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API C# Pub/Sub.
Vai
Prima di provare questo esempio, segui le istruzioni di configurazione di Go in Guida rapida all'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Pub/Sub Go.
Java
Prima di provare questo esempio, segui le istruzioni di configurazione di Java in Guida rapida all'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 all'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 all'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 in Guida rapida all'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
Gli esempi riportati di seguito mostrano come gestire gli errori che si verificano quando la sottoscrizione ai messaggi.
C++
Prima di provare questo esempio, segui le istruzioni per la configurazione di C++ in Guida rapida all'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Pub/Sub C++.
Vai
Prima di provare questo esempio, segui le istruzioni di configurazione di Go in Guida rapida all'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Pub/Sub Go.
Java
Prima di provare questo esempio, segui le istruzioni di configurazione di Java in Guida rapida all'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 all'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 all'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 in Guida rapida all'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Pub/Sub Go.
Esempi di codice di pull unari
Ecco un codice campione tira e riconoscere un numero fisso di messaggi.
C++
Prima di provare questo esempio, segui le istruzioni per la configurazione di C++ in 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 C# in Guida rapida all'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API C# Pub/Sub.
Java
Prima di provare questo esempio, segui le istruzioni di configurazione di Java in Guida rapida all'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 all'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 all'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 in Guida rapida all'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 all'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Python Pub/Sub.
Pub/Sub consegna 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 avvertenze:
L'impostazione di un valore per
max_messages
nella richiesta non garantisce che vengano restituitimax_messages
, anche se il numero di messaggi arretrato. L'API Pull di Pub/Sub potrebbe restituire meno dimax_messages
per ridurre la latenza di recapito dei messaggi subito disponibili per la pubblicazione.Una risposta pull che viene fornita con 0 messaggi non deve essere utilizzata come indicatore per assicurarti che non ci siano messaggi nel backlog. È possibile ottenere 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 unario, essenziale avere molte richieste di pull simultaneamente in sospeso. Come aumenta la velocità effettiva dell'argomento, sono necessarie più richieste di pull. In generale, la modalità StreamingPull è preferibile per sensibili alla latenza.
Quote e limiti
Sia le connessioni pull che StreamingPull sono soggette a quote e limiti. Per ulteriori informazioni, consulta Quote e limiti di Pub/Sub.
Passaggi successivi
Crea una sottoscrizione pull per l'argomento.
Crea o modifica una sottoscrizione con gcloud CLI.
Crea o modifica un abbonamento con le API REST.
Crea o modifica una sottoscrizione con le API RPC.