Mit Listenvorgängen arbeiten

Einige Dienste geben möglicherweise große 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 diesem Leitfaden 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 diesem Leitfaden folgen können, müssen Sie den Secret Manager-Dienst aktiviert haben, angemeldet sein und dafür sorgen, dass Ihr Konto die erforderlichen Berechtigungen hat. Eine Anleitung dazu, wie Sie diese Voraussetzungen erfüllen, finden Sie in der Kurzanleitung für Dienste.

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

Abhängigkeiten

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

cargo add google-cloud-secretmanager-v1

Listenmethoden durchlaufen

Damit die Elemente in einer Listenmethode durchlaufen werden können, geben die APIs eine Implementierung des ItemPaginator-Traits zurück. Führen Sie das Merkmal mit einer use-Deklaration 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 Ihren Fortschritt in verschiedenen Prozessen überprü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. Mit by_page können Sie die Seiten durchlaufen: 

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

Arbeiten mit futures::Stream

Möglicherweise möchten Sie diese APIs im größeren Rust-Ökosystem asynchroner Streams wie tokio::Stream verwenden. So gehts:

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

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

  2. In den folgenden Beispielen wird auch das futures::stream::StreamExt-Trait verwendet, das Sie durch Hinzufügen des futures-Crates aktivieren.

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

List-Methoden durch Festlegen des Tokens für die nächste Seite fortsetzen

In einigen Fällen, z. B. bei einem unterbrochenen Listenvorgang, 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 Paginierungs-Helfer verwendet werden?

Die Google Cloud Clientbibliotheken für Rust bieten einen Adapter zum Konvertieren der List-RPCs, wie in AIP-4233 definiert, in Typen, die ItemPaginator und Paginator implementieren, wenn die Google API List-Methode der von AIP-158 definierten Paginierungsrichtlinie entspricht. Kurz gesagt: Gemäß dieser Richtlinie muss bei jedem Aufruf einer List-Methode eine Seite mit Ressourcen (z. B. Secrets) zusammen mit einem Token zurückgegeben werden, 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.