Como trabalhar com operações de lista

Alguns serviços retornam listas potencialmente grandes de itens, como linhas ou descrições de recursos. Para manter o uso da CPU e da memória sob controle, os serviços retornam esses recursos em pages: subconjuntos menores dos itens com um token de continuação para solicitar o próximo subconjunto.

A iteração de itens por página pode ser tediosa. As bibliotecas de cliente fornecem adaptadores para converter as páginas em iteradores assíncronos. Este guia mostra como trabalhar com esses adaptadores.

Pré-requisitos

Este guia usa o serviço do Secret Manager para demonstrar operações de lista. Os conceitos incluídos neste guia também se aplicam a outros serviços.

Para seguir este guia, você precisa ter ativado o serviço do Secret Manager, feito login e garantido que sua conta tenha as permissões necessárias. Para orientações sobre como atender a esses pré-requisitos, siga o início rápido do serviço.

Para instruções completas de configuração das bibliotecas Rust, consulte Como configurar o ambiente de desenvolvimento.

Dependências

Adicione a biblioteca do Secret Manager ao arquivo Cargo.toml:

cargo add google-cloud-secretmanager-v1

Como iterar métodos de lista

Para ajudar a iterar os itens em um método de lista, as APIs retornam uma implementação da característica ItemPaginator. Introduza a característica no escopo usando uma declaração use:

use google_cloud_gax::paginator::ItemPaginator as _;

Para iterar os itens, use o método by_item.

let mut list = client
    .list_secrets()
    .set_parent(format!("projects/{project_id}"))
    .by_item();
while let Some(secret) = list.next().await {
    let secret = secret?;
    println!("  secret={}", secret.name)
}

Em casos raros, as páginas podem conter informações extras a que você precisa acessar ou pode ser necessário verificar o progresso em processos. Se necessário, você pode iterar páginas inteiras em vez de itens individuais.

  1. Introduza Paginator no escopo usando uma declaração use: 

    use google_cloud_gax::paginator::Paginator as _;

  2. Itere as páginas usando by_page: 

    let mut list = client
    .list_secrets()
    .set_parent(format!("projects/{project_id}"))
    .by_page();
while let Some(page) = list.next().await {
    let page = page?;
    println!("  next_page_token={}", page.next_page_token);
    page.secrets
        .into_iter()
        .for_each(|secret| println!("    secret={}", secret.name));
}

Como trabalhar com futures::Stream

Talvez você queira usar essas APIs no ecossistema Rust maior de streams assíncronos, como tokio::Stream. Isso pode ser feito da seguinte maneira:

  1. Ative o recurso unstable-streams no pacote google_cloud_gax. O nome desse recurso serve como aviso de que essas APIs são instáveis. Use-as apenas se você estiver preparado para lidar com interrupções resultantes de mudanças incompatíveis na característica futures::Stream.

    cargo add google-cloud-gax --features unstable-stream

  2. Os exemplos a seguir também usam a futures::stream::StreamExt característica, que você ativa adicionando o futures pacote.

    cargo add futures

  3. Adicione as declarações use necessárias: 

    use futures::stream::StreamExt;
use google_cloud_gax::paginator::ItemPaginator as _;

  4. Use a função into_stream para converter ItemPaginator em um futures::Stream. 

    let list = client
    .list_secrets()
    .set_parent(format!("projects/{project_id}"))
    .by_item()
    .into_stream();
list.map(|secret| -> gax::Result<()> {
    println!("  secret={}", secret?.name);
    Ok(())
})
.fold(Ok(()), async |acc, result| -> gax::Result<()> {
    acc.and(result)
})
.await?;

Da mesma forma, você pode usar a função into_stream para converter Paginator em um futures::Stream.

let list = client
    .list_secrets()
    .set_parent(format!("projects/{project_id}"))
    .by_page()
    .into_stream();
list.enumerate()
    .map(|(index, page)| -> gax::Result<()> {
        println!("page={}, next_page_token={}", index, page?.next_page_token);
        Ok(())
    })
    .fold(Ok(()), async |acc, result| -> gax::Result<()> {
        acc.and(result)
    })
    .await?;

Como retomar métodos de lista definindo o token da próxima página

Em alguns casos, como uma operação de lista interrompida, você pode definir o token da próxima página para retomar a paginação de uma página específica.

let page = client
    .list_secrets()
    .set_parent(format!("projects/{project_id}"))
    .send()
    .await;
let page = page?;
let mut next_page_token = page.next_page_token.clone();
page.secrets
    .into_iter()
    .for_each(|secret| println!("    secret={}", secret.name));

while !next_page_token.is_empty() {
    println!("  next_page_token={next_page_token}");

    let page = client
        .list_secrets()
        .set_parent(format!("projects/{project_id}"))
        .set_page_token(next_page_token)
        .send()
        .await;
    let page = page?;
    next_page_token = page.next_page_token.clone();

    page.secrets
        .into_iter()
        .for_each(|secret| println!("    secret={}", secret.name));
}

Quando usar os auxiliares do paginador

As Google Cloud bibliotecas de cliente para Rust fornecem um adaptador para converter as RPCs de lista definidas por AIP-4233 em tipos que implementam ItemPaginator e Paginator se o método Google API List seguir a diretriz de paginação definida por AIP-158. Em resumo, essa diretriz exige que cada chamada para um método List retorne uma página de itens de recursos (por exemplo, secrets) junto com um token que pode ser transmitido ao método List para recuperar a próxima página.

A maioria dos Google Cloud serviços segue essas diretrizes. Nos casos em que isso não acontece, você precisa implementar seu próprio adaptador para iterar os resultados.