Como trabalhar com operações de longa duração

Alguns métodos da API Google Cloud levam um tempo significativo para serem concluídos. Em vez de bloquear até que o trabalho seja concluído, esses métodos retornam um recurso Operation que representa uma operação em andamento para que o aplicativo possa consultar o status e o resultado final.

As bibliotecas de cliente do Cloud para Rust fornecem auxiliares para trabalhar com essas operações de longa duração (LROs, na sigla em inglês). Neste documento, mostramos como iniciar uma LRO, fazer sondagens automáticas até a conclusão, inspecionar atualizações de progresso intermediárias e fazer sondagens manuais.

Antes de começar

Este documento usa o Cloud Storage para manter os exemplos de código concretos, mas os mesmos conceitos se aplicam a qualquer serviço do Google Cloud que use LROs.

Antes de executar o código neste documento, conclua os seguintes pré-requisitos:

  • Crie ou selecione um projeto doGoogle Cloud com o faturamento ativado.
  • Siga as instruções em Começar a usar o Rust para configurar o ambiente de desenvolvimento e as credenciais.
  • Crie um bucket do Cloud Storage com o namespace hierárquico ativado e crie uma pasta de origem para renomear.
  • Conceda ao principal um papel do Identity and Access Management (IAM) com permissão para gerenciar pastas, como Administrador do Storage (roles/storage.admin).

Dependências

Adicione a biblioteca de cliente e os crates de LRO ao arquivo Cargo.toml:

cargo add google-cloud-storage google-cloud-lro google-cloud-longrunning anyhow

Adicione tokio para execução assíncrona e timers:

cargo add tokio --features full

Iniciar uma operação de longa duração

Os exemplos neste documento chamam a operação de renomeação de pasta do Cloud Storage, que retorna uma LRO. Para iniciar uma LRO diretamente e receber o recurso Operation inicial, siga estas etapas:

  1. Adicione declarações use para encurtar os caminhos de tipo:

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

  2. Defina uma função async que aceite o ID do bucket, o ID da pasta de origem e o ID da pasta de destino:

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

  3. Inicialize o cliente StorageControl:

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

  4. Crie o builder de solicitações rename_folder:

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

  5. Envie a solicitação e aguarde o recurso Operation inicial, que representa a operação em segundo plano:

    .send()
    .await?;

Depois de iniciar a operação, aguarde até que ela seja concluída para recuperar o resultado final.

Pesquisar automaticamente uma operação de longa duração

Na maioria dos casos de uso, use o método until_done do atributo Poller em vez de chamar send diretamente. O poller inicia a LRO, faz a sondagem de acordo com as políticas de espera e erro do cliente e resolve para a resposta final:

  1. Traga a característica Poller para o escopo:

    use google_cloud_lro::Poller;

  2. Inicialize um cliente StorageControl e configure o builder de solicitações rename_folder:

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

  3. Chame poller e until_done no builder de solicitações para aguardar a conclusão e mostrar o resultado:

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

Código de sondagem automática completo

A função a seguir mostra o exemplo completo de sondagem automática:

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(())
}

Sondar uma operação de longa duração com resultados intermediários

O método until_done retorna apenas o resultado final e omite as atualizações de metadados intermediárias. Se o aplicativo precisar de atualizações de progresso enquanto a LRO é executada, use poller para receber um poller e chame poll em um loop:

  1. Importe Poller e PollingResult:

    use google_cloud_lro::{Poller, PollingResult};

  2. Converta o criador de solicitações em um poller usando poller:

    .poller();

  3. Chame poller.poll().await em um loop para processar os estados 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;
    }

Ao chamar poll diretamente, seu loop controla o atraso entre as tentativas de pesquisa. Escolha um atraso adequado à duração esperada da operação.

Código completo para sondagem com resultados intermediários

A função a seguir mostra o loop 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(())
}

Sondar manualmente uma operação de longa duração

Embora a característica Poller lide com quase todos os casos de uso, também é possível consultar um Operation manualmente usando get_operation:

  1. Depois de iniciar a LRO com send, insira um loop e verifique o campo done:

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

  2. Inspecione operation.result. O campo result é um Option porque algumas operações, como exclusões, são concluídas sem retornar um payload. Para rename_folder, o serviço retorna um recurso Folder:

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

  3. Verifique se a operação foi concluída com um erro. A variante de erro contém uma mensagem Status que o exemplo a seguir formata em um erro ou que pode ser convertida em um erro do cliente usando Error::service:

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

  4. Se a operação for bem-sucedida, descompacte o payload Any no tipo de resposta Folder esperado:

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

  5. Adicione um braço curinga porque os tipos enumerados nas bibliotecas de cliente do Cloud para Rust estão marcados como #[non_exhaustive]:

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

  6. Opcional: enquanto operation.done for false, descompacte operation.metadata para inspecionar as atualizações de progresso:

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

  7. Aguarde antes de fazer uma nova sondagem. Este exemplo é suspenso por 500 ms fixos para fins de brevidade. No código de produção, use a espera exponencial truncada:

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

  8. Chame get_operation com operation.name para atualizar o status de funcionamento:

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

Código completo de sondagem manual

A função a seguir combina todas as etapas de sondagem manual:

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(())
}