Bekerja dengan operasi yang berjalan lama

Beberapa metode API Google Cloud memerlukan waktu yang cukup lama untuk diselesaikan. Alih-alih memblokir hingga pekerjaan selesai, metode ini menampilkan resource Operation yang mewakili operasi yang sedang berlangsung sehingga aplikasi Anda dapat melakukan polling untuk status dan hasil akhirnya.

Library Klien Cloud untuk Rust menyediakan helper untuk menangani operasi yang berjalan lama (LRO) ini. Dokumen ini menunjukkan cara memulai LRO, melakukan polling secara otomatis hingga selesai, memeriksa update progres menengah, dan melakukan polling secara manual.

Sebelum memulai

Dokumen ini menggunakan Cloud Storage untuk membuat contoh kode tetap konkret, meskipun konsep yang sama berlaku untuk layanan Google Cloud apa pun yang menggunakan LRO.

Sebelum menjalankan kode dalam dokumen ini, selesaikan prasyarat berikut:

  • Buat atau pilih projectGoogle Cloud dengan penagihan diaktifkan.
  • Ikuti Memulai Rust untuk menyiapkan lingkungan pengembangan dan kredensial Anda.
  • Buat bucket Cloud Storage dengan namespace hierarkis diaktifkan, dan buat folder sumber untuk diganti namanya.
  • Beri akun utama Anda peran Identity and Access Management (IAM) dengan izin untuk mengelola folder, seperti Storage Admin (roles/storage.admin).

Dependensi

Tambahkan library klien dan crate LRO ke file Cargo.toml Anda:

cargo add google-cloud-storage google-cloud-lro google-cloud-longrunning anyhow

Tambahkan tokio untuk eksekusi asinkron dan timer:

cargo add tokio --features full

Memulai operasi yang berjalan lama

Contoh dalam dokumen ini memanggil operasi ganti nama folder Cloud Storage, yang menampilkan LRO. Untuk memulai LRO secara langsung dan mendapatkan resource Operation awal, selesaikan langkah-langkah berikut:

  1. Tambahkan deklarasi use untuk mempersingkat jalur jenis:

    use anyhow::anyhow;
    use google_cloud_longrunning as longrunning;
    use google_cloud_storage::client::StorageControl;

  2. Tentukan fungsi async yang menerima ID bucket, ID folder sumber, dan ID folder tujuan:

    pub async fn manual(bucket: &str, folder: &str, dest: &str) -> anyhow::Result<()> {

  3. Lakukan inisialisasi klien StorageControl:

    let client = StorageControl::builder().build().await?;

  4. Buat builder permintaan rename_folder:

    let operation = client
        .rename_folder()
        .set_name(format!("projects/_/buckets/{bucket}/folders/{folder}"))
        .set_destination_folder_id(dest)

  5. Kirim permintaan dan tunggu resource Operation awal, yang mewakili operasi latar belakang:

    .send()
    .await?;

Setelah memulai operasi, tunggu hingga operasi selesai untuk mengambil hasil akhirnya.

Melakukan polling otomatis pada operasi yang berjalan lama

Untuk sebagian besar kasus penggunaan, gunakan metode until_done dari karakteristik Poller, bukan memanggil send secara langsung. Poller memulai LRO, melakukan polling sesuai dengan kebijakan backoff dan error klien, serta me-resolve ke respons akhir:

  1. Masukkan trait Poller ke dalam cakupan:

    use google_cloud_lro::Poller;

  2. Lakukan inisialisasi klien StorageControl dan konfigurasi builder permintaan rename_folder:

    let response = client
        .rename_folder()
        .set_name(format!("projects/_/buckets/{bucket}/folders/{folder}"))
        .set_destination_folder_id(dest)

  3. Panggil poller dan until_done pada builder permintaan untuk menunggu penyelesaian dan mencetak hasilnya:

        .poller()
        .until_done()
        .await?;
    
    println!("LRO completed, response={response:?}");

Menyelesaikan kode polling otomatis

Fungsi berikut menunjukkan contoh polling otomatis yang lengkap:

pub async fn automatic(bucket: &str, folder: &str, dest: &str) -> anyhow::Result<()> {
    use google_cloud_lro::Poller;

    let client = StorageControl::builder().build().await?;

    let response = client
        .rename_folder()
        .set_name(format!("projects/_/buckets/{bucket}/folders/{folder}"))
        .set_destination_folder_id(dest)
        .poller()
        .until_done()
        .await?;

    println!("LRO completed, response={response:?}");

    Ok(())
}

Melakukan polling operasi yang berjalan lama dengan hasil sementara

Metode until_done hanya menampilkan hasil akhir dan menghilangkan update metadata perantara. Jika aplikasi Anda memerlukan update progres saat LRO berjalan, dapatkan poller dengan poller dan panggil poll dalam loop:

  1. Impor Poller dan PollingResult:

    use google_cloud_lro::{Poller, PollingResult};

  2. Konversikan builder permintaan menjadi poller menggunakan poller:

    .poller();

  3. Panggil poller.poll().await dalam loop untuk memproses status InProgress, PollingError, dan Completed:

    while let Some(p) = poller.poll().await {
        match p {
            PollingResult::Completed(r) => {
                println!("LRO completed, response={r:?}");
            }
            PollingResult::InProgress(m) => {
                println!("LRO in progress, metadata={m:?}");
            }
            PollingResult::PollingError(e) => {
                println!("Transient error polling the LRO: {e}");
            }
        }
        tokio::time::sleep(std::time::Duration::from_millis(500)).await;
    }

Saat memanggil poll secara langsung, loop Anda mengontrol penundaan antara upaya polling. Pilih penundaan yang sesuai dengan durasi operasi yang diharapkan.

Kode lengkap untuk polling dengan hasil menengah

Fungsi berikut menunjukkan loop poll lengkap:

pub async fn polling(bucket: &str, folder: &str, dest: &str) -> anyhow::Result<()> {
    use google_cloud_lro::{Poller, PollingResult};

    let client = StorageControl::builder().build().await?;

    let mut poller = client
        .rename_folder()
        .set_name(format!("projects/_/buckets/{bucket}/folders/{folder}"))
        .set_destination_folder_id(dest)
        .poller();

    while let Some(p) = poller.poll().await {
        match p {
            PollingResult::Completed(r) => {
                println!("LRO completed, response={r:?}");
            }
            PollingResult::InProgress(m) => {
                println!("LRO in progress, metadata={m:?}");
            }
            PollingResult::PollingError(e) => {
                println!("Transient error polling the LRO: {e}");
            }
        }
        tokio::time::sleep(std::time::Duration::from_millis(500)).await;
    }

    Ok(())
}

Melakukan polling operasi yang berjalan lama secara manual

Meskipun karakteristik Poller menangani hampir semua kasus penggunaan, Anda juga dapat melakukan polling Operation secara manual menggunakan get_operation:

  1. Setelah memulai LRO dengan send, masukkan loop dan periksa kolom done:

    let response: anyhow::Result<Folder> = loop {
        if operation.done {

  2. Periksa operation.result. Kolom result adalah Option karena beberapa operasi, seperti penghapusan, selesai tanpa menampilkan payload. Untuk rename_folder, layanan akan menampilkan resource Folder:

    match &operation.result {
        None => {
            break Err(anyhow!("missing result for finished operation"));
        }

  3. Periksa apakah operasi selesai dengan error. Varian error berisi pesan Status yang diformat oleh contoh berikut menjadi error, atau yang dapat Anda konversi menjadi error klien menggunakan Error::service:

    Some(r) => {
        break match r {
            longrunning::model::operation::Result::Error(s) => {
                Err(anyhow!("operation completed with error {s:?}"))
            }

  4. Jika operasi berhasil, ekstrak payload Any ke jenis respons Folder yang diharapkan:

    longrunning::model::operation::Result::Response(any) => {
        let response = any.to_msg::<Folder>()?;
        Ok(response)
    }

  5. Tambahkan arm karakter pengganti karena enum di Library Klien Cloud untuk Rust ditandai #[non_exhaustive]:

    _ => Err(anyhow!("unexpected result branch {r:?}")),

  6. Opsional: Saat operation.done adalah false, ekstrak operation.metadata untuk memeriksa update progres:

    if let Some(any) = &operation.metadata {
        let metadata = any.to_msg::<RenameFolderMetadata>()?;
        println!("LRO in progress, metadata={metadata:?}");
    }

  7. Tunggu sebelum melakukan polling lagi. Contoh ini tidur selama 500 md tetap untuk singkatnya; dalam kode produksi, gunakan backoff eksponensial yang dipotong:

    tokio::time::sleep(std::time::Duration::from_millis(500)).await;

  8. Panggil get_operation dengan operation.name untuk memuat ulang status operasi:

    if let Ok(attempt) = client
        .get_operation()
        .set_name(&operation.name)
        .send()
        .await
    {
        operation = attempt;
    }

Kode polling manual lengkap

Fungsi berikut menggabungkan semua langkah polling manual:

pub async fn manual(bucket: &str, folder: &str, dest: &str) -> anyhow::Result<()> {
    use google_cloud_storage::model::Folder;
    use google_cloud_storage::model::RenameFolderMetadata;

    let client = StorageControl::builder().build().await?;

    let operation = client
        .rename_folder()
        .set_name(format!("projects/_/buckets/{bucket}/folders/{folder}"))
        .set_destination_folder_id(dest)
        .send()
        .await?;
    println!("LRO started, response={operation:?}");

    let mut operation = operation;
    let response: anyhow::Result<Folder> = loop {
        if operation.done {
            match &operation.result {
                None => {
                    break Err(anyhow!("missing result for finished operation"));
                }
                Some(r) => {
                    break match r {
                        longrunning::model::operation::Result::Error(s) => {
                            Err(anyhow!("operation completed with error {s:?}"))
                        }
                        longrunning::model::operation::Result::Response(any) => {
                            let response = any.to_msg::<Folder>()?;
                            Ok(response)
                        }
                        _ => Err(anyhow!("unexpected result branch {r:?}")),
                    };
                }
            }
        }
        if let Some(any) = &operation.metadata {
            let metadata = any.to_msg::<RenameFolderMetadata>()?;
            println!("LRO in progress, metadata={metadata:?}");
        }
        tokio::time::sleep(std::time::Duration::from_millis(500)).await;
        if let Ok(attempt) = client
            .get_operation()
            .set_name(&operation.name)
            .send()
            .await
        {
            operation = attempt;
        }
    };
    println!("LRO completed, response={response:?}");

    Ok(())
}