Mit Listenvorgängen arbeiten

Einige Dienste geben potenziell lange Listen von Elementen zurück, z. B. Zeilen oder Ressourcenbeschreibungen. Um die CPU- und Arbeitsspeichernutzung unter Kontrolle zu halten, geben Dienste diese Ressourcen in pages zurück: kleinere Teilmengen der Elemente mit einem Fortsetzungstoken, um die nächste Teilmenge anzufordern.

Das Durchlaufen von Elementen nach Seite kann mühsam sein. Die Clientbibliotheken bieten Adapter, um die Seiten in asynchrone Iteratoren zu konvertieren. In dieser Anleitung erfahren Sie, wie Sie mit diesen Adaptern arbeiten.

Vorbereitung

In dieser Anleitung wird der Secret Manager-Dienst verwendet, um Listenoperationen zu veranschaulichen. Die in dieser Anleitung enthaltenen Konzepte gelten auch für andere Dienste.

Damit Sie dieser Anleitung folgen können, müssen Sie den Secret Manager-Dienst aktiviert, sich angemeldet und dafür gesorgt haben, dass Ihr Konto die erforderlichen Berechtigungen hat. Eine Anleitung zum Erfüllen dieser Voraussetzungen finden Sie in der Schnellstartanleitung für den Dienst. Folgen Sie der Schnellstartanleitung für den Dienst.

Eine vollständige Einrichtungsanleitung für die Rust-Bibliotheken finden Sie unter Entwicklungsumgebung einrichten.

Abhängigkeiten

Fügen Sie die Secret Manager-Bibliothek Ihrer Datei Cargo.toml hinzu:

cargo add google-cloud-secretmanager-v1

Listenmethoden durchlaufen

Um das Durchlaufen der Elemente in einer Listenmethode zu erleichtern, geben die APIs eine Implementierung des Traits ItemPaginator zurück. Führen Sie den Trait mit einer use-Deklaration in den Bereich ein:

use google_cloud_gax::paginator::ItemPaginator as _;

Verwenden Sie die Methode by_item, um die Elemente zu durchlaufen.

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 seltenen Fällen enthalten Seiten möglicherweise zusätzliche Informationen, auf die Sie zugreifen müssen, oder Sie müssen den Fortschritt über mehrere Prozesse hinweg prüfen. Bei Bedarf können Sie vollständige Seiten anstelle einzelner Elemente durchlaufen.

  1. Führen Sie Paginator mit einer use-Deklaration in den Bereich ein: 

    use google_cloud_gax::paginator::Paginator as _;

  2. Durchlaufen Sie die Seiten mit 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));
}

Mit futures::Stream arbeiten

Möglicherweise möchten Sie diese APIs im größeren Rust-Ökosystem asynchroner Streams verwenden, z. B. tokio::Stream. Das geht so:

  1. Aktivieren Sie das Feature unstable-streams im Crate google_cloud_gax. Der Name dieses Features weist darauf hin, dass diese APIs instabil sind. Sie sollten sie nur verwenden, wenn Sie bereit sind, mit allen Unterbrechungen umzugehen, die durch inkompatible Änderungen am futures::Stream Trait entstehen.

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

  2. In den folgenden Beispielen wird auch der futures::stream::StreamExt Trait verwendet, den Sie aktivieren, indem Sie das futures Crate hinzufügen.

    cargo add futures

  3. Fügen Sie die erforderlichen use-Deklarationen hinzu: 

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

  4. Verwenden Sie die Funktion into_stream, um ItemPaginator in einen futures::Stream zu konvertieren. 

    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?;

Ebenso können Sie die Funktion into_stream verwenden, um Paginator in einen futures::Stream zu konvertieren.

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?;

Listenmethoden fortsetzen, indem Sie das Token für die nächste Seite festlegen

In einigen Fällen, z. B. bei einer unterbrochenen Listenoperation, können Sie das Token für die nächste Seite festlegen, um die Paginierung ab einer bestimmten Seite fortzusetzen.

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

Wann sollten die Paginator-Helfer verwendet werden?

Die Google Cloud Clientbibliotheken für Rust bieten einen Adapter, um die in AIP-4233 definierten Listen-RPCs in Typen zu konvertieren, die ItemPaginator und Paginator implementieren, wenn die Google API-Listenmethode der in AIP-158 definierten Paginierungsrichtlinie folgt. Kurz gesagt, diese Richtlinie erfordert, dass jeder Aufruf einer List-Methode eine Seite mit Ressourcenelementen (z. B. Secrets) zusammen mit einem Token zurückgibt, das Sie an die List-Methode übergeben können, um die nächste Seite abzurufen.

Die meisten Google Cloud Dienste folgen diesen Richtlinien. In den Fällen, in denen dies nicht der Fall ist, müssen Sie einen eigenen Adapter implementieren, um die Ergebnisse zu durchlaufen.