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

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

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

前提条件

このガイドでは、Secret Manager サービスを使用してリスト操作を示します。このガイドに含まれるコンセプトは、他のサービスにも適用されます。

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

Rust ライブラリの設定手順については、開発環境をセットアップするをご覧ください。

依存関係

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

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

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

use 宣言を使用して、Paginator をスコープに導入します。
```
use google_cloud_gax::paginator::Paginator as _;
```

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` の使用

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

google_cloud_gax クレートで unstable-streams 機能を有効にします。この機能の名前は、これらの API が不安定であることを示しています。`futures::Stream` トレイトの互換性のない変更によって発生する中断に対処できる場合にのみ使用してください。
```
cargo add google-cloud-gax --features unstable-stream
```
次の例では、futures::stream::StreamExt トレイトも使用します。これは futures クレートを追加することで有効になります。
```
cargo add futures
```

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

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

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 は、Google API の List メソッドが AIP-158 で定義されたページ分割ガイドラインに準拠している場合、AIP-4233 で定義されているリスト RPC を ItemPaginator と Paginator を実装する型に変換するアダプターを提供します。このガイドラインでは、List メソッドの呼び出しごとに、リソースアイテム（シークレットなど）のページと、次のページを取得するために List メソッドに渡すことができるトークンを返す必要があります。

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

リスト オペレーションの操作 コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。