Bekerja dengan operasi daftar

Beberapa layanan menampilkan daftar item yang berpotensi besar, seperti baris atau deskripsi resource. Untuk menjaga penggunaan CPU dan penggunaan memori tetap terkendali, layanan menampilkan resource ini dalam pages: subset item yang lebih kecil dengan token kelanjutan untuk meminta subset berikutnya.

Melakukan iterasi item menurut halaman bisa membosankan. Library klien menyediakan adapter untuk mengonversi halaman menjadi iterator asinkron. Panduan ini menunjukkan cara menggunakan adapter ini.

Prasyarat

Panduan ini menggunakan layanan Secret Manager untuk mendemonstrasikan operasi daftar. Konsep yang disertakan dalam panduan ini juga berlaku untuk layanan lainnya.

Untuk mengikuti panduan ini, Anda harus mengaktifkan layanan Secret Manager, login, dan memastikan akun Anda memiliki izin yang diperlukan. Untuk panduan tentang cara memenuhi prasyarat ini, ikuti panduan memulai layanan.

Untuk petunjuk penyiapan lengkap untuk library Rust, lihat Menyiapkan lingkungan pengembangan.

Dependensi

Tambahkan library Secret Manager ke file Cargo.toml:

cargo add google-cloud-secretmanager-v1

Metode daftar iterasi

Untuk membantu melakukan iterasi item dalam metode daftar, API menampilkan implementasi trait ItemPaginator. Perkenalkan trait ke dalam cakupan menggunakan deklarasi use:

use google_cloud_gax::paginator::ItemPaginator as _;

Untuk melakukan iterasi item, gunakan metode 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)
}

Dalam kasus yang jarang terjadi, halaman mungkin berisi informasi tambahan yang perlu Anda akses, atau Anda mungkin perlu membuat checkpoint progres di seluruh proses. Jika diperlukan, Anda dapat melakukan iterasi halaman lengkap, bukan item individual.

  1. Perkenalkan Paginator ke dalam cakupan menggunakan deklarasi use: 

    use google_cloud_gax::paginator::Paginator as _;

  2. Lakukan iterasi halaman menggunakan 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));
}

Menggunakan futures::Stream

Anda mungkin ingin menggunakan API ini dalam ekosistem Rust yang lebih besar dari aliran asinkron, seperti tokio::Stream. Hal ini dapat dicapai sebagai berikut:

  1. Aktifkan fitur unstable-streams di crate google_cloud_gax. Nama fitur ini berfungsi sebagai pemberitahuan bahwa API ini tidak stabil. Anda hanya boleh menggunakannya jika siap menangani gangguan yang diakibatkan oleh perubahan yang tidak kompatibel pada trait futures::Stream.

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

  2. Contoh berikut juga menggunakan trait futures::stream::StreamExt, yang Anda aktifkan dengan menambahkan crate futures.

    cargo add futures

  3. Tambahkan deklarasi use yang diperlukan: 

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

  4. Gunakan fungsi into_stream untuk mengonversi ItemPaginator menjadi 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?;

Demikian pula, Anda dapat menggunakan fungsi into_stream untuk mengonversi Paginator menjadi 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?;

Melanjutkan metode daftar dengan menetapkan token halaman berikutnya

Dalam beberapa kasus, seperti operasi daftar yang terganggu, Anda dapat menetapkan token halaman berikutnya untuk melanjutkan penomoran halaman dari halaman tertentu.

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

Kapan harus menggunakan helper paginator

Google Cloud Library Klien untuk Rust menyediakan adapter untuk mengonversi RPC daftar seperti yang ditentukan oleh AIP-4233 menjadi jenis yang mengimplementasikan ItemPaginator dan Paginator jika metode Daftar Google API mengikuti panduan penomoran halaman yang ditentukan oleh AIP-158. Singkatnya, panduan ini mengharuskan setiap panggilan ke metode List menampilkan halaman item resource (misalnya, rahasia) beserta token yang dapat Anda teruskan ke metode List untuk mengambil halaman berikutnya.

Sebagian besar Google Cloud layanan mengikuti panduan ini. Jika tidak, Anda harus menerapkan adapter sendiri untuk melakukan iterasi hasil.