Utiliser les opérations de liste

Certains services renvoient des listes d'éléments potentiellement volumineuses, telles que des lignes ou des descriptions de ressources. Pour maîtriser l'utilisation du processeur et de la mémoire, les services renvoient ces ressources dans des pages : des sous-ensembles plus petits d'éléments avec un jeton de continuation pour demander le sous-ensemble suivant.

Parcourir les éléments par page peut être fastidieux. Les bibliothèques clientes fournissent des adaptateurs pour convertir les pages en itérateurs asynchrones. Ce guide vous explique comment utiliser ces adaptateurs.

Prérequis

Ce guide utilise le service Secret Manager pour illustrer les opérations de liste. Les concepts inclus dans ce guide s'appliquent également à d'autres services.

Pour suivre ce guide, vous devez avoir activé le service Secret Manager, vous être connecté et vous assurer que votre compte dispose des autorisations nécessaires. Pour savoir comment répondre à ces prérequis, suivez le démarrage rapide du service.

Pour obtenir des instructions de configuration complètes pour les bibliothèques Rust, consultez la page Configurer votre environnement de développement.

Dépendances

Ajoutez la bibliothèque Secret Manager à votre fichier Cargo.toml :

cargo add google-cloud-secretmanager-v1

Itération des méthodes de liste

Pour faciliter l'itération des éléments dans une méthode de liste, les API renvoient une implémentation du trait ItemPaginator. Introduisez le trait dans le champ d'application à l'aide d'une déclaration use :

use google_cloud_gax::paginator::ItemPaginator as _;

Pour parcourir les éléments, utilisez la méthode 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)
}

Dans de rares cas, les pages peuvent contenir des informations supplémentaires auxquelles vous devez accéder, ou vous devrez peut-être vérifier votre progression entre les processus. Si nécessaire, vous pouvez parcourir des pages entières au lieu d'éléments individuels.

  1. Introduisez Paginator dans le champ d'application à l'aide d'une déclaration use : 

    use google_cloud_gax::paginator::Paginator as _;

  2. Parcourez les pages à l'aide de 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));
}

Utiliser futures::Stream

Vous pouvez utiliser ces API dans l'écosystème Rust plus vaste de flux asynchrones, tels que tokio::Stream. Pour ce faire, procédez comme suit :

  1. Activez la fonctionnalité unstable-streams dans le crate google_cloud_gax. Le nom de cette fonctionnalité indique que ces API sont instables. Vous ne devez les utiliser que si vous êtes prêt à gérer les interruptions résultant de modifications incompatibles du futures::Stream trait.

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

  2. Les exemples suivants utilisent également le futures::stream::StreamExt trait, que vous activez en ajoutant le futures crate.

    cargo add futures

  3. Ajoutez les déclarations use requises : 

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

  4. Utilisez la fonction into_stream pour convertir ItemPaginator en 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?;

De même, vous pouvez utiliser la fonction into_stream pour convertir Paginator en 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?;

Reprendre les méthodes de liste en définissant le jeton de page suivante

Dans certains cas, comme une opération de liste interrompue, vous pouvez définir le jeton de page suivante pour reprendre la pagination à partir d'une page spécifique.

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

Quand utiliser les assistants de pagination

Google Cloud Les bibliothèques clientes pour Rust fournissent un adaptateur permettant de convertir les RPC de liste, tels que définis par AIP-4233, en types implémentant ItemPaginator et Paginator si la méthode de liste de l'API Google suit les consignes de pagination définies par AIP-158. En bref, cette consigne exige que chaque appel à une méthode List renvoie une page d'éléments de ressource (par exemple, des secrets) ainsi qu'un jeton que vous pouvez transmettre à la méthode List pour récupérer la page suivante.

La plupart des Google Cloud services suivent ces consignes. Dans le cas contraire, vous devez implémenter votre propre adaptateur pour parcourir les résultats.