Bekerja dengan operasi daftar

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

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

Prasyarat

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

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

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

Dependensi

Tambahkan library Secret Manager ke file Cargo.toml Anda:

cargo add google-cloud-secretmanager-v1

Metode daftar iterasi

Untuk membantu mengulangi item dalam metode daftar, API menampilkan penerapan trait ItemPaginator. Perkenalkan trait ke dalam cakupan menggunakan deklarasi use:

use google_cloud_gax::paginator::ItemPaginator as _;

Untuk melakukan iterasi pada 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 menandai progres di seluruh proses. Jika diperlukan, Anda dapat melakukan iterasi pada halaman lengkap, bukan item individual.

  1. Memperkenalkan Paginator ke dalam cakupan menggunakan deklarasi use: 

    use google_cloud_gax::paginator::Paginator as _;

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

Bekerja dengan futures::Stream

Anda mungkin ingin menggunakan API ini dalam ekosistem Rust yang lebih besar untuk aliran asinkron, seperti tokio::Stream. Hal ini dapat dilakukan 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 Anda siap menangani gangguan apa pun yang diakibatkan oleh perubahan yang tidak kompatibel pada karakteristik 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 menyetel 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 penomoran halaman

Google Cloud Client Libraries for Rust menyediakan adaptor untuk mengonversi RPC daftar seperti yang ditentukan oleh AIP-4233 menjadi jenis yang menerapkan ItemPaginator dan Paginator jika metode Google API List mengikuti panduan penomoran halaman yang ditentukan oleh AIP-158. Singkatnya, panduan ini mewajibkan setiap panggilan ke metode List menampilkan halaman item resource (misalnya, secret) 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 mengimplementasikan adaptor Anda sendiri untuk melakukan iterasi pada hasilnya.