Questa pagina mostra come avviare e monitorare le operazioni di ricerca per le sottoscrizioni Lite.
La funzionalità di ricerca Pub/Sub Lite consente di riprodurre di nuovo ed eliminare definitivamente i messaggi. Riguarda gli stessi casi d'uso della ricerca di Pub/Sub. A differenza di Pub/Sub, non è necessario configurare argomenti o sottoscrizioni Lite per utilizzare la ricerca e non sono previsti costi aggiuntivi.
La propagazione della ricerca nei sottoscrittori può essere monitorata utilizzando un'operazione a lunga esecuzione. Questo è un pattern API utilizzato dai prodotti Google Cloud per monitorare l'avanzamento delle attività a lunga esecuzione.
Avvio della ricerca
Le operazioni di ricerca di Pub/Sub Lite vengono avviate fuori banda (ovvero da Google Cloud CLI o dall'API Pub/Sub Lite separata) e vengono propagate ai sottoscrittori. Gli abbonati online riceveranno una notifica relativa alla ricerca e all'invio di una reazione mentre sono in diretta. Gli abbonati offline reagiranno alla ricerca quando saranno online.
Devi specificare una località di destinazione per la ricerca, che può essere una delle seguenti:
- Inizio del backlog dei messaggi: riproduce tutti i messaggi conservati. Tieni presente che la quantità di backlog disponibile è determinata dal periodo di conservazione dei messaggi e dalla capacità di archiviazione dell'argomento Lite.
- Fine del backlog dei messaggi: elimina definitivamente i messaggi saltando tutti i messaggi pubblicati attuali.
- Timestamp pubblicazione: cerca il primo messaggio con un timestamp di pubblicazione (generato dal server) maggiore o uguale al timestamp specificato. Se questo messaggio non può essere trovato, cerca fino alla fine del backlog dei messaggi. Per i messaggi successivi è garantito un timestamp di pubblicazione maggiore o uguale al timestamp specificato, ad eccezione dei timestamp specificati che sono nel futuro.
- Timestamp evento: vai al primo messaggio con un timestamp dell'evento (specificato dall'utente) maggiore o uguale al timestamp specificato. Se questo messaggio non può essere trovato, cerca fino alla fine del backlog dei messaggi. Poiché i timestamp degli eventi vengono forniti dall'utente, i messaggi successivi potrebbero avere timestamp degli eventi inferiori all'ora dell'evento specificata e devono essere filtrati dal client, se necessario. Se per i messaggi non è impostato un timestamp evento, i relativi timestamp di pubblicazione vengono utilizzati come riserva.
Puoi avviare una ricerca per una sottoscrizione Lite con Google Cloud CLI o l'API Pub/Sub Lite.
gcloud
Per cercare una sottoscrizione Lite, utilizza il comando gcloud pubsub lite-subscriptions seek
:
gcloud pubsub lite-subscriptions seek SUBSCRIPTION_ID \ --location=LITE_LOCATION \ (--publish-time=PUBLISH_TIME | --event-time=EVENT_TIME | \ --starting-offset=STARTING_OFFSET) \ [--async]
Sostituisci quanto segue:
SUBSCRIPTION_ID: l'ID della sottoscrizione Lite
LITE_LOCATION: la località della sottoscrizione Lite
PUBLISH_TIME: il timestamp di pubblicazione da cercare
EVENT_TIME: il timestamp dell'evento in cui cercare
STARTING_OFFSET:
beginning
oend
Consulta gcloud topic datetimes
per
informazioni sui formati dell'ora.
Se specifichi il flag --async
e la richiesta ha esito positivo, la riga di comando visualizza l'ID dell'operazione di ricerca:
Check operation [projects/PROJECT_NUMBER/locations/LITE_LOCATION/operations/OPERATION_ID] for status.
Utilizza il comando gcloud pubsub lite-operations describe
per ottenere lo stato dell'operazione.
REST
Per cercare un abbonamento Lite, invia una richiesta POST
come la seguente:
POST https://REGION-pubsublite.googleapis.com/v1/admin/projects/PROJECT_NUMBER/locations/LITE_LOCATION/subscriptions/SUBSCRIPTION_ID:seek Authorization: Bearer $(gcloud auth print-access-token)
Sostituisci quanto segue:
REGION: la regione in cui si trova la sottoscrizione Lite
PROJECT_NUMBER: il numero del progetto con la sottoscrizione Lite
LITE_LOCATION: la località della sottoscrizione Lite
SUBSCRIPTION_ID: l'ID della sottoscrizione Lite
Per andare all'inizio o alla fine del backlog dei messaggi, imposta i seguenti campi nel corpo della richiesta:
{ "namedTarget": NAMED_TARGET }
Sostituisci quanto segue:
- NAMED_TARGET:
TAIL
per l'inizio oHEAD
per la fine del backlog dei messaggi.
Per cercare un timestamp di pubblicazione, imposta i seguenti campi nel corpo della richiesta:
{ "timeTarget": { "publishTime": TIMESTAMP } }
Specifica "eventTime"
per cercare un timestamp di un evento.
Sostituisci quanto segue:
- TIMESTAMP: un timestamp in formato UTC RFC 3339, con risoluzione
in nanosecondi e fino a nove cifre frazionarie. Esempi:
"2014-10-02T15:01:23Z"
e"2014-10-02T15:01:23.045123456Z"
.
Se la richiesta ha esito positivo, la risposta è un'operazione a lunga esecuzione in formato JSON:
{ "name": projects/PROJECT_NUMBER/locations/LITE_LOCATION/operations/OPERATION_ID, ... }
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 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.
Se la richiesta di ricerca ha esito positivo, la risposta è un ID operazione a lunga esecuzione. Consulta le informazioni sulla propagazione della ricerca di monitoraggio di seguito se hai bisogno di sapere quando gli abbonati hanno aggiunto una reazione alla ricerca.
Client supportati
Le operazioni di ricerca richiedono sottoscrittori che utilizzano le seguenti librerie client Pub/Sub Lite e versioni minime:
- java-pubsublite: versione 0.15.0.
- java-pubsublite-kafka: versione 0.6.0. I consumatori devono anche avere abilitato il commit automatico.
- python-pubsublite: versione 0.6.0.
- google-cloud-go: pubsublite versione 0.10.0.
Le operazioni di ricerca non funzionano quando Pub/Sub Lite viene utilizzato con Apache Beam o Apache Spark perché questi sistemi eseguono il proprio monitoraggio degli offset all'interno delle partizioni. La soluzione alternativa consiste nello svuotare, cercare e riavviare i flussi di lavoro.
Il servizio Pub/Sub Lite è in grado di rilevare un client abbonato che non supporta le operazioni di ricerca (ad esempio una versione precedente della libreria client o un framework non supportato) e interromperà la ricerca con uno stato di errore FAILED_PRECONDITION
.
Propagazione della ricerca di monitoraggio
Se viene restituito un ID operazione a lunga esecuzione per la richiesta di ricerca iniziale, significa che la ricerca è stata registrata correttamente nel servizio Pub/Sub Lite e alla fine verrà propagata ai sottoscrittori (se il client è supportato, come spiegato in precedenza). L'operazione monitora questa propagazione e completa dopo che gli abbonati hanno reagito alla ricerca, per tutte le partizioni.
Se gli abbonati sono online, potrebbero essere necessari fino a 30 secondi prima che ricevano la notifica di richiesta. Le notifiche di ricerca vengono inviate in modo indipendente per ogni partizione, quindi le partizioni potrebbero non reagire alla ricerca contemporaneamente. Se gli abbonati sono offline, l'operazione di ricerca verrà completata quando saranno online.
Se la propagazione di una chiamata di ricerca precedente ai sottoscrittori non è terminata, viene interrotta e sostituita dalla nuova operazione di ricerca. I metadati dell'operazione di ricerca scadono dopo 30 giorni, interrompendo di fatto qualsiasi operazione di ricerca incomplete.
Cerca stato operazione
Puoi ottenere lo stato di un'operazione di ricerca utilizzando Google Cloud CLI o l'API Pub/Sub Lite.
gcloud
Per ottenere dettagli su un'operazione Lite, utilizza il comando gcloud pubsub lite-operations describe
:
gcloud pubsub lite-operations describe OPERATION_ID \ --location=LITE_LOCATION
Sostituisci quanto segue:
OPERATION_ID: l'ID dell'operazione Lite
LITE_LOCATION: la località dell'operazione Lite
Se la richiesta ha esito positivo, la riga di comando visualizza i metadati relativi all'operazione Lite:
metadata: '@type': type.googleapis.com/google.cloud.pubsublite.v1.OperationMetadata createTime: '2021-01-02T03:04:05Z' target: projects/PROJECT_NUMBER/locations/LITE_LOCATION/subscriptions/SUBSCRIPTION_ID verb: seek name: projects/PROJECT_NUMBER/locations/LITE_LOCATION/operations/OPERATION_ID
REST
Per ottenere dettagli su un'operazione Lite, invia una richiesta GET
come la seguente:
GET https://REGION-pubsublite.googleapis.com/v1/admin/projects/PROJECT_NUMBER/locations/LITE_LOCATION/operations/OPERATION_ID Authorization: Bearer $(gcloud auth print-access-token)
Sostituisci quanto segue:
REGION: la regione in cui si trova l'operazione Lite
PROJECT_NUMBER: il numero del progetto con l'operazione Lite
LITE_LOCATION: la località dell'operazione Lite
OPERATION_ID: l'ID dell'operazione Lite
Se la richiesta ha esito positivo, la risposta è un'operazione a lunga esecuzione in formato JSON:
{ "name": projects/PROJECT_NUMBER/locations/LITE_LOCATION/operations/OPERATION_ID, ... }
Operazioni di ricerca elenco
Le operazioni di ricerca completate e attive possono essere elencate utilizzando Google Cloud CLI o l'API Pub/Sub Lite.
gcloud
Per elencare le operazioni Lite in un progetto, utilizza il comando gcloud pubsub lite-operations list
:
gcloud pubsub lite-operations list \
--location=LITE_LOCATION \
[--subscription=SUBSCRIPTION] \
[--done=DONE] \
[--limit=LIMIT]
Sostituisci quanto segue:
LITE_LOCATION: la località in cui si trovano le operazioni Lite
SUBSCRIPTION: operazioni di filtro per sottoscrizione Lite
DONE:
true
per includere solo le operazioni completate,false
per includere solo le operazioni attiveLIMIT: un numero intero per limitare il numero di operazioni restituite
Se la richiesta ha esito positivo, la riga di comando visualizza un riepilogo delle operazioni Lite:
OPERATION_ID TARGET CREATE_TIME DONE ERROR_CODE MESSAGE operation2 projects/PROJECT_NUMBER/locations/LITE_LOCATION/subscriptions/SUBSCRIPTION_ID 2021-05-06T07:08:00Z True operation1 projects/PROJECT_NUMBER/locations/LITE_LOCATION/subscriptions/SUBSCRIPTION_ID 2021-01-02T03:04:00Z True
REST
Per elencare le operazioni Lite in un progetto, invia una richiesta GET
come la seguente:
GET https://REGION-pubsublite.googleapis.com/v1/admin/projects/PROJECT_NUMBER/locations/LITE_LOCATION/operations Authorization: Bearer $(gcloud auth print-access-token)
Sostituisci quanto segue:
REGION: la regione in cui si trovano le operazioni Lite
PROJECT_NUMBER: il numero del progetto con le operazioni Lite
LITE_LOCATION: la località in cui si trovano le operazioni Lite
Se la richiesta ha esito positivo, la risposta sarà un elenco di operazioni Lite in formato JSON:
{ "operations": [ { "name": "projects/PROJECT_NUMBER/locations/LITE_LOCATION/operations/OPERATION_ID", ... }, { "name": "projects/PROJECT_NUMBER/locations/LITE_LOCATION/operations/OPERATION_ID", ... } ] }