Utiliser les opérations de liste

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

Il peut être fastidieux d'itérer sur les éléments par page. 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 remplir ces conditions préalables, suivez le guide de démarrage rapide du service.

Pour obtenir des instructions de configuration complètes pour les bibliothèques Rust, consultez 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érer des méthodes de liste

Pour faciliter l'itération des éléments d'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 itérer sur 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 dans les processus. Si nécessaire, vous pouvez itérer sur 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. Itérez sur 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));
}

Travailler avec futures::Stream

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

  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 problèmes résultant de modifications incompatibles apportées au trait futures::Stream.

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

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

    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 helpers de pagination

Les bibliothèques clientes Google Cloud 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 Google API List suit les consignes de pagination définies par AIP-158. En bref, ce guide exige que chaque appel à une méthode List renvoie une page d'éléments de ressources (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 services Google Cloud suivent ces consignes. Dans le cas contraire, vous devez implémenter votre propre adaptateur pour parcourir les résultats.