Utiliser des opérations de liste

Certains services renvoient des listes d'éléments potentiellement volumineuses, telles que 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 des pages : des sous-ensembles plus petits d'éléments avec un jeton de continuation pour demander le sous-ensemble suivant.

L'itération sur les éléments par page peut être fastidieuse. 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 être assuré 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 les 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 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 créer un point de contrôle de votre progression dans les processus. Si nécessaire, vous pouvez effectuer une itération sur des pages complètes plutôt que sur des é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. Effectuez une itération 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));
}

Utiliser futures::Stream

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

  1. Activez la fonctionnalité unstable-streams dans la caisse google_cloud_gax. Le nom de cette fonctionnalité sert d'avertissement quant à l'instabilité de ces API. Vous ne devez les utiliser que si vous êtes prêt à gérer les interruptions 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 la caractéristique futures::stream::StreamExt, que vous activez en ajoutant la 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, par exemple lors d'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

Les bibliothèques clientes Google Cloud pour Rust fournissent un adaptateur permettant de convertir les RPC de liste 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, cette consigne 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. Si ce n'est pas le cas, vous devez implémenter votre propre adaptateur pour effectuer une itération sur les résultats.