Utilizzo delle operazioni di elenco

Alcuni servizi restituiscono elenchi di elementi potenzialmente di grandi dimensioni, come righe o descrizioni delle risorse. Per mantenere sotto controllo l'utilizzo di CPU e memoria utilizzata, i servizi restituiscono queste risorse in pages: sottoinsiemi più piccoli degli elementi con un token di continuazione per richiedere il sottoinsieme successivo.

L'iterazione degli elementi per pagina può essere noiosa. Le librerie client forniscono adattatori per convertire le pagine in iteratori asincroni. Questa guida mostra come utilizzare questi adattatori.

Prerequisiti

Questa guida utilizza il servizio Secret Manager per mostrare le operazioni di elenco. I concetti inclusi in questa guida si applicano anche ad altri servizi.

Per seguire questa guida, devi aver abilitato il servizio Secret Manager, aver eseguito l'accesso e assicurarti che il tuo account disponga delle autorizzazioni necessarie. Per indicazioni su come soddisfare questi prerequisiti, segui la guida rapida del servizio .

Per istruzioni complete sulla configurazione delle librerie Rust, consulta la sezione Configurare l'ambiente di sviluppo.

Dipendenze

Aggiungi la libreria Secret Manager al file Cargo.toml:

cargo add google-cloud-secretmanager-v1

Iterazione dei metodi di elenco

Per facilitare l'iterazione degli elementi in un metodo di elenco, le API restituiscono un'implementazione del trait ItemPaginator. Introduci il tratto nell'ambito utilizzando una dichiarazione use:

use google_cloud_gax::paginator::ItemPaginator as _;

Per eseguire l'iterazione degli elementi, utilizza il metodo 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)
}

In rari casi, le pagine potrebbero contenere informazioni aggiuntive a cui devi accedere oppure potresti dover controllare lo stato di avanzamento dei processi. Se necessario, puoi eseguire l'iterazione delle pagine complete anziché dei singoli elementi.

  1. Introduci Paginator nell'ambito utilizzando una dichiarazione use: 

    use google_cloud_gax::paginator::Paginator as _;

  2. Esegui l'iterazione delle pagine utilizzando 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));
}

Utilizzo di futures::Stream

Potresti voler utilizzare queste API nell'ecosistema Rust più ampio di flussi asincroni, come tokio::Stream. Puoi farlo nel seguente modo:

  1. Abilita la funzionalità unstable-streams nella crate google_cloud_gax. Il nome di questa funzionalità indica che queste API sono instabili. Dovresti utilizzarle solo se sei pronto a gestire eventuali interruzioni derivanti da modifiche incompatibili al futures::Stream tratto.

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

  2. Gli esempi seguenti utilizzano anche il futures::stream::StreamExt tratto, che puoi abilitare aggiungendo la futures crate.

    cargo add futures

  3. Aggiungi le dichiarazioni use richieste: 

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

  4. Utilizza la funzione into_stream per convertire ItemPaginator in 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?;

Allo stesso modo, puoi utilizzare la funzione into_stream per convertire Paginator in 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?;

Riprendere i metodi di elenco impostando il token della pagina successiva

In alcuni casi, ad esempio un'operazione di elenco interrotta, puoi impostare il token della pagina successiva per riprendere la paginazione da una pagina specifica.

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 utilizzare gli helper del paginatore

Le Google Cloud Librerie client per Rust forniscono un adattatore per convertire le RPC di elenco come definito da AIP-4233 in tipi che implementano ItemPaginator e Paginator se il metodo Google API List segue le linee guida per la paginazione definite da AIP-158. In breve, queste linee guida richiedono che ogni chiamata a un metodo List restituisca una pagina di elementi risorsa (ad esempio, secret) insieme a un token che puoi passare al metodo List per recuperare la pagina successiva.

La maggior parte dei Google Cloud servizi segue queste linee guida. Nei casi in cui non lo fanno, devi implementare il tuo adattatore per eseguire l'iterazione dei risultati.