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:
Adicione declarações
usepara encurtar os caminhos de tipo:Defina uma função
asyncque aceite o ID do bucket, o ID da pasta de origem e o ID da pasta de destino:Inicialize o cliente
StorageControl:Crie o builder de solicitações
rename_folder:Envie a solicitação e aguarde o recurso
Operationinicial, que representa a operação em segundo plano:
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:
Traga a característica
Pollerpara o escopo:Inicialize um cliente
StorageControle configure o builder de solicitaçõesrename_folder:Chame
pollereuntil_doneno builder de solicitações para aguardar a conclusão e mostrar o resultado:
Código de sondagem automática completo
A função a seguir mostra o exemplo completo de sondagem automática:
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:
Importe
PollerePollingResult:Converta o criador de solicitações em um poller usando
poller:Chame
poller.poll().awaitem um loop para processar os estadosInProgress,PollingErroreCompleted:
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:
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:
Depois de iniciar a LRO com
send, insira um loop e verifique o campodone:Inspecione
operation.result. O camporesulté umOptionporque algumas operações, como exclusões, são concluídas sem retornar um payload. Pararename_folder, o serviço retorna um recursoFolder:Verifique se a operação foi concluída com um erro. A variante de erro contém uma mensagem
Statusque o exemplo a seguir formata em um erro ou que pode ser convertida em um erro do cliente usandoError::service:Se a operação for bem-sucedida, descompacte o payload
Anyno tipo de respostaFolderesperado:Adicione um braço curinga porque os tipos enumerados nas bibliotecas de cliente do Cloud para Rust estão marcados como
#[non_exhaustive]:Opcional: enquanto
operation.doneforfalse, descompacteoperation.metadatapara inspecionar as atualizações de progresso: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:
Chame
get_operationcomoperation.namepara atualizar o status de funcionamento:
Código completo de sondagem manual
A função a seguir combina todas as etapas de sondagem manual: