Alcuni metodi API Google Cloud richiedono un tempo significativo per essere completati.
Anziché bloccare l'esecuzione fino al termine del lavoro, questi metodi restituiscono una risorsa Operation che rappresenta un'operazione in corso, in modo che l'applicazione possa eseguire il polling per verificarne lo stato e il risultato finale.
Le librerie client di Cloud per Rust forniscono helper per l'utilizzo di queste operazioni a lunga esecuzione (LRO). Questo documento mostra come avviare un'operazione LRO, eseguire il polling automatico fino al completamento, esaminare gli aggiornamenti intermedi dello stato di avanzamento ed eseguire il polling manualmente.
Prima di iniziare
Questo documento utilizza Cloud Storage per mantenere concreti gli esempi di codice, anche se gli stessi concetti si applicano a qualsiasi servizio Google Cloud che utilizza le LRO.
Prima di eseguire il codice in questo documento, completa i seguenti prerequisiti:
- Crea o seleziona un progettoGoogle Cloud con la fatturazione abilitata.
- Segui Inizia a utilizzare Rust per configurare l'ambiente di sviluppo e le credenziali.
- Crea un bucket Cloud Storage con lo spazio dei nomi gerarchico abilitato e crea una cartella di origine da rinominare.
- Concedi alla tua entità un ruolo Identity and Access Management (IAM) con l'autorizzazione per gestire le cartelle, ad esempio Storage Admin (
roles/storage.admin).
Dipendenze
Aggiungi i crate della libreria client e di LRO al file Cargo.toml:
cargo add google-cloud-storage google-cloud-lro google-cloud-longrunning anyhow
Aggiungi tokio per l'esecuzione asincrona e i timer:
cargo add tokio --features full
Avvia un'operazione a lunga esecuzione
Gli esempi in questo documento chiamano l'operazione di rinomina cartella di Cloud Storage, che restituisce un'LRO. Per avviare un'LRO direttamente e ottenere la risorsa Operation iniziale, completa i seguenti passaggi:
Aggiungi dichiarazioni
useper abbreviare i percorsi dei tipi:Definisci una funzione
asyncche accetti l'ID bucket, l'ID cartella di origine e l'ID cartella di destinazione:Inizializza il client
StorageControl:Crea il generatore di richieste
rename_folder:Invia la richiesta e attendi la risorsa
Operationiniziale, che rappresenta l'operazione in background:
Dopo aver avviato l'operazione, attendi che venga completata per recuperare il risultato finale.
Esegui automaticamente il polling di un'operazione a lunga esecuzione
Per la maggior parte dei casi d'uso, utilizza il metodo until_done della caratteristica Poller anziché chiamare direttamente send. Il poller avvia l'LRO, esegue il polling in base alle policy di backoff e di errore del client e risolve la risposta finale:
Porta il tratto
Pollernell'ambito:Inizializza un client
StorageControle configura il generatore di richiesterename_folder:Chiama
pollereuntil_donesul generatore di richieste per attendere il completamento e stampare il risultato:
Codice di polling automatico completo
La seguente funzione mostra l'esempio completo di polling automatico:
Esegui il polling di un'operazione a lunga esecuzione con risultati intermedi
Il metodo until_done restituisce solo il risultato finale e omette gli aggiornamenti dei metadati intermedi. Se la tua applicazione richiede aggiornamenti sull'avanzamento durante l'esecuzione dell'LRO, ottieni un poller con poller e chiama poll in un loop:
Importa
PollerePollingResult:Converti il generatore di richieste in un poller utilizzando
poller:Chiama
poller.poll().awaitin un loop per elaborare gli statiInProgress,PollingErroreCompleted:
Quando chiami direttamente poll, il loop controlla il ritardo tra i tentativi di polling. Scegli un ritardo adatto alla durata prevista dell'operazione.
Codice completo per il polling con risultati intermedi
La seguente funzione mostra il ciclo poll completo:
Esegui il polling manuale di un'operazione a lunga esecuzione
Sebbene il tratto Poller gestisca quasi tutti i casi d'uso, puoi anche eseguire il polling di un
Operation manualmente utilizzando get_operation:
Dopo aver avviato l'LRO con
send, inserisci un loop e controlla il campodone:Ispeziona
operation.result. Il camporesultè unOptionperché alcune operazioni, come le eliminazioni, terminano senza restituire un payload. Perrename_folder, il servizio restituisce una risorsaFolder:Controlla se l'operazione è stata completata con un errore. La variante di errore contiene un messaggio
Statusche l'esempio seguente formatta in un errore o che puoi convertire in un errore client utilizzandoError::service:Se l'operazione è riuscita, decomprimi il payload
Anynel tipo di rispostaFolderprevisto:Aggiungi un braccio con carattere jolly perché gli enum nelle librerie client di Cloud per Rust sono contrassegnati con
#[non_exhaustive]:(Facoltativo) Mentre
operation.doneèfalse, decomprimioperation.metadataper esaminare gli aggiornamenti sull'avanzamento:Attendi prima di eseguire nuovamente il polling. Questo esempio prevede una pausa di 500 ms per brevità; nel codice di produzione, utilizza il backoff esponenziale troncato:
Chiama
get_operationconoperation.nameper aggiornare lo stato dell'operazione:
Codice di polling manuale completo
La seguente funzione combina tutti i passaggi di polling manuale: