Utilizzo delle operazioni a lunga esecuzione

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:

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:

  1. Aggiungi dichiarazioni use per abbreviare i percorsi dei tipi:

    use anyhow::anyhow;
    use google_cloud_longrunning as longrunning;
    use google_cloud_storage::client::StorageControl;

  2. Definisci una funzione async che accetti l'ID bucket, l'ID cartella di origine e l'ID cartella di destinazione:

    pub async fn manual(bucket: &str, folder: &str, dest: &str) -> anyhow::Result<()> {

  3. Inizializza il client StorageControl:

    let client = StorageControl::builder().build().await?;

  4. Crea il generatore di richieste rename_folder:

    let operation = client
        .rename_folder()
        .set_name(format!("projects/_/buckets/{bucket}/folders/{folder}"))
        .set_destination_folder_id(dest)

  5. Invia la richiesta e attendi la risorsa Operation iniziale, che rappresenta l'operazione in background:

    .send()
    .await?;

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:

  1. Porta il tratto Poller nell'ambito:

    use google_cloud_lro::Poller;

  2. Inizializza un client StorageControl e configura il generatore di richieste rename_folder:

    let response = client
        .rename_folder()
        .set_name(format!("projects/_/buckets/{bucket}/folders/{folder}"))
        .set_destination_folder_id(dest)

  3. Chiama poller e until_done sul generatore di richieste per attendere il completamento e stampare il risultato:

        .poller()
        .until_done()
        .await?;
    
    println!("LRO completed, response={response:?}");

Codice di polling automatico completo

La seguente funzione mostra l'esempio completo di polling automatico:

pub async fn automatic(bucket: &str, folder: &str, dest: &str) -> anyhow::Result<()> {
    use google_cloud_lro::Poller;

    let client = StorageControl::builder().build().await?;

    let response = client
        .rename_folder()
        .set_name(format!("projects/_/buckets/{bucket}/folders/{folder}"))
        .set_destination_folder_id(dest)
        .poller()
        .until_done()
        .await?;

    println!("LRO completed, response={response:?}");

    Ok(())
}

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:

  1. Importa Poller e PollingResult:

    use google_cloud_lro::{Poller, PollingResult};

  2. Converti il generatore di richieste in un poller utilizzando poller:

    .poller();

  3. Chiama poller.poll().await in un loop per elaborare gli stati InProgress, PollingError e Completed:

    while let Some(p) = poller.poll().await {
        match p {
            PollingResult::Completed(r) => {
                println!("LRO completed, response={r:?}");
            }
            PollingResult::InProgress(m) => {
                println!("LRO in progress, metadata={m:?}");
            }
            PollingResult::PollingError(e) => {
                println!("Transient error polling the LRO: {e}");
            }
        }
        tokio::time::sleep(std::time::Duration::from_millis(500)).await;
    }

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:

pub async fn polling(bucket: &str, folder: &str, dest: &str) -> anyhow::Result<()> {
    use google_cloud_lro::{Poller, PollingResult};

    let client = StorageControl::builder().build().await?;

    let mut poller = client
        .rename_folder()
        .set_name(format!("projects/_/buckets/{bucket}/folders/{folder}"))
        .set_destination_folder_id(dest)
        .poller();

    while let Some(p) = poller.poll().await {
        match p {
            PollingResult::Completed(r) => {
                println!("LRO completed, response={r:?}");
            }
            PollingResult::InProgress(m) => {
                println!("LRO in progress, metadata={m:?}");
            }
            PollingResult::PollingError(e) => {
                println!("Transient error polling the LRO: {e}");
            }
        }
        tokio::time::sleep(std::time::Duration::from_millis(500)).await;
    }

    Ok(())
}

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:

  1. Dopo aver avviato l'LRO con send, inserisci un loop e controlla il campo done:

    let response: anyhow::Result<Folder> = loop {
        if operation.done {

  2. Ispeziona operation.result. Il campo result è un Option perché alcune operazioni, come le eliminazioni, terminano senza restituire un payload. Per rename_folder, il servizio restituisce una risorsa Folder:

    match &operation.result {
        None => {
            break Err(anyhow!("missing result for finished operation"));
        }

  3. Controlla se l'operazione è stata completata con un errore. La variante di errore contiene un messaggio Status che l'esempio seguente formatta in un errore o che puoi convertire in un errore client utilizzando Error::service:

    Some(r) => {
        break match r {
            longrunning::model::operation::Result::Error(s) => {
                Err(anyhow!("operation completed with error {s:?}"))
            }

  4. Se l'operazione è riuscita, decomprimi il payload Any nel tipo di risposta Folder previsto:

    longrunning::model::operation::Result::Response(any) => {
        let response = any.to_msg::<Folder>()?;
        Ok(response)
    }

  5. Aggiungi un braccio con carattere jolly perché gli enum nelle librerie client di Cloud per Rust sono contrassegnati con #[non_exhaustive]:

    _ => Err(anyhow!("unexpected result branch {r:?}")),

  6. (Facoltativo) Mentre operation.done è false, decomprimi operation.metadata per esaminare gli aggiornamenti sull'avanzamento:

    if let Some(any) = &operation.metadata {
        let metadata = any.to_msg::<RenameFolderMetadata>()?;
        println!("LRO in progress, metadata={metadata:?}");
    }

  7. 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:

    tokio::time::sleep(std::time::Duration::from_millis(500)).await;

  8. Chiama get_operation con operation.name per aggiornare lo stato dell'operazione:

    if let Ok(attempt) = client
        .get_operation()
        .set_name(&operation.name)
        .send()
        .await
    {
        operation = attempt;
    }

Codice di polling manuale completo

La seguente funzione combina tutti i passaggi di polling manuale:

pub async fn manual(bucket: &str, folder: &str, dest: &str) -> anyhow::Result<()> {
    use google_cloud_storage::model::Folder;
    use google_cloud_storage::model::RenameFolderMetadata;

    let client = StorageControl::builder().build().await?;

    let operation = client
        .rename_folder()
        .set_name(format!("projects/_/buckets/{bucket}/folders/{folder}"))
        .set_destination_folder_id(dest)
        .send()
        .await?;
    println!("LRO started, response={operation:?}");

    let mut operation = operation;
    let response: anyhow::Result<Folder> = loop {
        if operation.done {
            match &operation.result {
                None => {
                    break Err(anyhow!("missing result for finished operation"));
                }
                Some(r) => {
                    break match r {
                        longrunning::model::operation::Result::Error(s) => {
                            Err(anyhow!("operation completed with error {s:?}"))
                        }
                        longrunning::model::operation::Result::Response(any) => {
                            let response = any.to_msg::<Folder>()?;
                            Ok(response)
                        }
                        _ => Err(anyhow!("unexpected result branch {r:?}")),
                    };
                }
            }
        }
        if let Some(any) = &operation.metadata {
            let metadata = any.to_msg::<RenameFolderMetadata>()?;
            println!("LRO in progress, metadata={metadata:?}");
        }
        tokio::time::sleep(std::time::Duration::from_millis(500)).await;
        if let Ok(attempt) = client
            .get_operation()
            .set_name(&operation.name)
            .send()
            .await
        {
            operation = attempt;
        }
    };
    println!("LRO completed, response={response:?}");

    Ok(())
}