リスト オペレーションの操作

一部のサービスは、行やリソースの説明など、アイテムの大きなリストを返す可能性があります。CPU とメモリ使用量を制御するために、サービスはこれらのリソースを pages で返します。これは、次のサブセットをリクエストするための継続トークンを含むアイテムの小さなサブセットです。

ページごとに項目を反復処理するのは面倒な場合があります。クライアント ライブラリには、ページを非同期イテレータに変換するアダプターが用意されています。このガイドでは、これらのアダプタの使用方法について説明します。

前提条件

このガイドでは、Secret Manager サービスを使用してリスト オペレーションのデモを行います。このガイドに含まれるコンセプトは、他のサービスにも適用されます。

このガイドに沿って操作するには、Secret Manager サービスを有効にしてログインし、アカウントに必要な権限が付与されていることを確認する必要があります。これらの前提条件を満たす方法については、サービスのクイックスタートをご覧ください。

Rust ライブラリの完全な設定手順については、開発環境の設定をご覧ください。

依存関係

Secret Manager ライブラリを Cargo.toml ファイルに追加します。

cargo add google-cloud-secretmanager-v1

リストメソッドの反復処理

リスト メソッドのアイテムを反復処理するために、API は ItemPaginator トレイトの実装を返します。use 宣言を使用して、トレイトをスコープに導入します。

use google_cloud_gax::paginator::ItemPaginator as _;

アイテムを反復処理するには、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)
}

まれに、アクセスする必要がある追加情報がページに含まれている場合や、プロセス全体で進捗状況をチェックポイントする必要がある場合があります。必要に応じて、個々のアイテムではなく、ページ全体を反復処理できます。

  1. use 宣言を使用して、Paginator をスコープに導入します。

    use google_cloud_gax::paginator::Paginator as _;

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

futures::Stream の操作

これらの API は、tokio::Stream などの非同期ストリームのより大きな Rust エコシステムで使用できます。これは次のように実現できます。

  1. google_cloud_gax クレートで unstable-streams 機能を有効にします。この機能の名前は、これらの API が不安定であることを示す通知として機能します。futures::Stream トレイトの互換性のない変更によって生じる中断に対処する準備ができている場合にのみ使用してください。

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

  2. 次の例では、futures クレートを追加することで有効になる futures::stream::StreamExt トレイトも使用します。

    cargo add futures

  3. 必要な use 宣言を追加します。 

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

  4. into_stream 関数を使用して、ItemPaginator を 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?;

同様に、into_stream 関数を使用して Paginator を 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?;

次のページトークンを設定してリストメソッドを再開する

リスト オペレーションが中断された場合など、特定のページからページネーションを再開するように次のページトークンを設定できます。

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

ページネータ ヘルパーを使用するタイミング

Google Cloud Client Libraries for Rust は、AIP-4233 で定義されているリスト RPC を、Google API List メソッドが AIP-158 で定義されているページネーション ガイドラインに準拠している場合に、ItemPaginator と Paginator を実装する型に変換するアダプターを提供します。簡単に言うと、このガイドラインでは、List メソッドの各呼び出しで、リソース アイテム（シークレットなど）のページと、次のページを取得するために List メソッドに渡すことができるトークンを返す必要があります。

ほとんどの Google Cloud サービスは、これらのガイドラインに準拠しています。そうでない場合は、独自のアダプタを実装して結果を反復処理する必要があります。