Penanganan error

Berikan pengalaman pengguna yang lebih konsisten dengan menafsirkan dan merespons error secara proaktif. Baik Anda mengembangkan alur kerja cloud otomatis atau berinteraksi dengan API jarak jauh, library klien Rust menyediakan cara untuk menangani error dengan baik. Dokumen ini menjelaskan cara:

  • Menangani error: Periksa jenis error dan buat cabang logika aplikasi Anda berdasarkan kode status layanan, seperti membuat resource yang tidak ada saat mengalami error NotFound.
  • Memeriksa detail error: Ekstrak detail error yang lengkap—seperti pelanggaran kolom permintaan buruk atau kegagalan kuota—dari layanan Google Cloud untuk memecahkan masalah API dan menyesuaikan perilaku runtime.
  • Menyelesaikan error binding: Menafsirkan dan menyelesaikan error binding HTTP sisi klien yang disebabkan oleh kolom permintaan yang tidak valid atau tidak ada untuk memastikan permintaan Anda mencapai layanan dengan lancar.

Prasyarat

Dokumen ini menggunakan layanan Secret Manager dan Cloud Natural Language API untuk menunjukkan penanganan error. Untuk menjalankan contoh, pertama-tama:

  1. Aktifkan layanan Secret Manager.
  2. Aktifkan Cloud Natural Language API.
  3. Siapkan autentikasi.

Dependensi

Gunakan perintah berikut untuk menambahkan dependensi yang diperlukan ke file Cargo.toml Anda:

cargo add google-cloud-secretmanager-v1 google-cloud-gax crc32c google-cloud-language-v2

Menangani error

Library klien Rust memungkinkan Anda menampilkan dan bereaksi terhadap error. Misalnya, Anda dapat menggunakan penemuan error untuk membuat cabang perilaku. Pola umum dalam layanan cloud adalah menggunakan resource seolah-olah container-nya ada, dan membuat container hanya jika Anda mengalami error. Jika container biasanya ada, pendekatan ini lebih efisien daripada memeriksa apakah container ada sebelum membuat permintaan.

Contoh berikut menangkap error saat mengupdate secret Secret Manager dan membuat secret jika belum ada.

  1. Coba buat versi secret baru:

    match update_attempt(&client, project_id, secret_id, data.clone()).await {

  2. Jika update_attempt berhasil, cetak hasil yang berhasil dan tampilkan:

    Ok(version) => {
        println!("new version is {}", version.name);
        Ok(version)
    }

  3. Jika update_attempt gagal, Anda harus memperjelas penyebab kegagalan tersebut. Permintaan mungkin gagal karena berbagai alasan, seperti koneksi terputus atau error pada token autentikasi. Kebijakan percobaan ulang dapat menangani sebagian besar error ini. Cari error yang ditampilkan oleh layanan:

    Err(e) => {
        if let Some(status) = e.downcast_ref::<Error>().and_then(|e| e.status()) {

  4. Cari error yang sesuai dengan secret yang tidak ada:

    if status.code == Code::NotFound {

  5. Jika Anda mengalami error "not found" (Code::NotFound), coba buat secret:

    let _ = create_secret(&client, project_id, secret_id).await?;

  6. Coba tambahkan versi secret lagi. Kali ini, tampilkan error jika ada yang gagal:

    let version = update_attempt(&client, project_id, secret_id, data).await?;
    println!("new version is {}", version.name);
    return Ok(version);

Contoh kode: fungsi utama (sample)

Kode lengkap untuk contoh ini dibagi menjadi tiga bagian: fungsi orkestrasi utama (sample), diikuti dengan dua metode helper-nya (update_attempt dan create_secret).

Fungsi sample mencoba menambahkan versi baru ke secret. Fungsi ini menangkap error yang ditampilkan oleh klien dan memeriksa apakah error tersebut adalah error Code::NotFound. Jika secret tidak ditemukan, fungsi akan membuat secret yang awalnya tidak ada dan mencoba kembali update.

use google_cloud_gax::error::Error;
use google_cloud_gax::error::rpc::Code;
use google_cloud_secretmanager_v1::client::SecretManagerService;
use google_cloud_secretmanager_v1::model::SecretVersion;

pub async fn sample(
    project_id: &str,
    secret_id: &str,
    data: Vec<u8>,
) -> anyhow::Result<SecretVersion> {
    let client = SecretManagerService::builder().build().await?;

    match update_attempt(&client, project_id, secret_id, data.clone()).await {
        Ok(version) => {
            println!("new version is {}", version.name);
            Ok(version)
        }
        Err(e) => {
            if let Some(status) = e.downcast_ref::<Error>().and_then(|e| e.status()) {
                if status.code == Code::NotFound {
                    let _ = create_secret(&client, project_id, secret_id).await?;
                    let version = update_attempt(&client, project_id, secret_id, data).await?;
                    println!("new version is {}", version.name);
                    return Ok(version);
                }
            }
            Err(e)
        }
    }
}

Contoh kode: metode bantuan (update_attempt)

Metode bantuan update_attempt mencoba menambahkan versi secret, dengan menghitung checksum CRC32c dari data payload:

use google_cloud_secretmanager_v1::client::SecretManagerService;
use google_cloud_secretmanager_v1::model::{SecretPayload, SecretVersion};

pub(crate) async fn update_attempt(
    client: &SecretManagerService,
    project_id: &str,
    secret_id: &str,
    data: Vec<u8>,
) -> anyhow::Result<SecretVersion> {
    let checksum = crc32c::crc32c(&data) as i64;
    let version = client
        .add_secret_version()
        .set_parent(format!("projects/{project_id}/secrets/{secret_id}"))
        .set_payload(
            SecretPayload::new()
                .set_data(data)
                .set_data_crc32c(checksum),
        )
        .send()
        .await?;
    Ok(version)
}

Contoh kode: metode bantuan (create_secret)

Metode helper create_secret membuat secret yang tidak ada dan mengonfigurasi kebijakan percobaan ulang yang disesuaikan:

use google_cloud_gax::options::RequestOptionsBuilder;
use google_cloud_gax::retry_policy::AlwaysRetry;
use google_cloud_gax::retry_policy::RetryPolicyExt;
use google_cloud_secretmanager_v1::client::SecretManagerService;
use google_cloud_secretmanager_v1::model::{Replication, Secret, replication};
use std::time::Duration;

pub async fn create_secret(
    client: &SecretManagerService,
    project_id: &str,
    secret_id: &str,
) -> anyhow::Result<Secret> {
    let secret = client
        .create_secret()
        .set_parent(format!("projects/{project_id}"))
        .with_retry_policy(
            AlwaysRetry
                .with_attempt_limit(5)
                .with_time_limit(Duration::from_secs(60)),
        )
        .set_secret_id(secret_id)
        .set_secret(
            Secret::new()
                .set_replication(Replication::new().set_replication(
                    replication::Replication::Automatic(replication::Automatic::new().into()),
                ))
                .set_labels([("integration-test", "true")]),
        )
        .send()
        .await?;
    Ok(secret)
}

Memeriksa detail error

Beberapa layanan Google Cloud menyertakan detail error tambahan saat permintaan gagal. Untuk membantu pemecahan masalah, library klien Rust menyertakan detail ini saat memformat error menggunakan std::fmt::Display. Anda dapat memeriksa detail ini dan mengubah perilaku aplikasi Anda.

Hanya error yang ditampilkan oleh layanan yang berisi informasi mendetail. Library klien menampilkan enum StatusDetails dengan berbagai jenis detail error.

Mengekstrak detail error

Contoh ini sengaja mengirim permintaan yang buruk ke Cloud Natural Language API dan memeriksa error yang dihasilkan.

  1. Membuat klien:

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

  2. Kirim permintaan (dalam contoh ini, kolom kunci tidak ada):

    let result = client
        .analyze_sentiment()
        .set_document(
            Document::new()
                // Missing document contents
                // .set_content("Hello World!")
                .set_type(Type::PlainText),
        )
        .send()
        .await;

  3. Ekstrak error dari hasil menggunakan fungsi Rust standar. Jenis error mencetak semua detail error dalam bentuk yang dapat dibaca manusia:

    let err = result.expect_err("the request should have failed");
    println!("\nrequest failed with error {err:#?}");

Outputnya mirip dengan hal berikut ini:

request failed with error Error {
    kind: Service {
        status_code: Some(
            400,
        ),
        headers: Some(
            {
                "vary": "X-Origin",
                "vary": "Referer",
                "vary": "Origin,Accept-Encoding",
                "content-type": "application/json; charset=UTF-8",
                "date": "Sat, 24 May 2025 17:19:49 GMT",
                "server": "scaffolding on HTTPServer2",
                "x-xss-protection": "0",
                "x-frame-options": "SAMEORIGIN",
                "x-content-type-options": "nosniff",
                "alt-svc": "h3=\":443\"; ma=2592000,h3-29=\":443\"; ma=2592000",
                "accept-ranges": "none",
                "transfer-encoding": "chunked",
            },
        ),
        status: Status {
            code: InvalidArgument,
            message: "One of content, or gcs_content_uri must be set.",
            details: [
                BadRequest(
                    BadRequest {
                        field_violations: [
                            FieldViolation {
                                field: "document.content",
                                description: "Must have some text content to annotate.",
                                reason: "",
                                localized_message: None,
                                _unknown_fields: {},
                            },
                        ],
                        _unknown_fields: {},
                    },
                ),
            ],
        },
    },
}

Memeriksa detail error secara terprogram

Terkadang, Anda mungkin perlu memeriksa detail error secara terprogram. Contoh ini melintasi struktur data dan mencetak kolom yang paling relevan.

Hanya error yang ditampilkan oleh layanan yang berisi informasi mendetail, jadi buat kueri error terlebih dahulu untuk melihat apakah error tersebut berisi jenis error yang benar. Jika ya, Anda dapat menguraikan beberapa informasi tingkat atas tentang error tersebut:

if let Some(status) = err.status() {
    println!(
        "  status.code={}, status.message={}",
        status.code, status.message,
    );

Lakukan iterasi pada detail:

for detail in status.details.iter() {
    match detail {

Library klien menampilkan enum StatusDetails dengan berbagai jenis detail error. Contoh ini hanya memeriksa error BadRequest:

StatusDetails::BadRequest(bad) => {

BadRequest berisi daftar kolom yang melanggar. Anda dapat melakukan iterasi dan mencetak detail untuk setiap:

for f in bad.field_violations.iter() {
    println!(
        "  the request field {} has a problem: \"{}\"",
        f.field, f.description
    );
}

Informasi tersebut dapat berguna selama pengembangan. Cabang StatusDetails lainnya, seperti QuotaFailure, mungkin berguna saat runtime untuk membatasi aplikasi.

Output yang diharapkan

Output dari detail error mirip dengan yang berikut ini:

  status.code=400, status.message=One of content, or gcs_content_uri must be set., status.status=Some("INVALID_ARGUMENT")
  the request field document.content has a problem: "Must have some text content to annotate."

Contoh kode: memeriksa detail error

Fungsi sample mengirimkan permintaan yang sengaja dibuat tidak valid ke Cloud Natural Language API untuk menghasilkan error layanan. Kemudian, kode ini akan menangkap error dan mengekstrak StatusDetails secara terprogram untuk memeriksa dan mencetak pelanggaran kolom BadRequest tertentu.

use google_cloud_gax::error::rpc::StatusDetails;
use google_cloud_language_v2::client::LanguageService;
use google_cloud_language_v2::model::Document;
use google_cloud_language_v2::model::document::Type;

pub async fn sample() -> anyhow::Result<()> {
    let client = LanguageService::builder().build().await?;

    let result = client
        .analyze_sentiment()
        .set_document(
            Document::new()
                // Missing document contents
                // .set_content("Hello World!")
                .set_type(Type::PlainText),
        )
        .send()
        .await;

    let err = result.expect_err("the request should have failed");
    println!("\nrequest failed with error {err:#?}");

    if let Some(status) = err.status() {
        println!(
            "  status.code={}, status.message={}",
            status.code, status.message,
        );
        for detail in status.details.iter() {
            match detail {
                StatusDetails::BadRequest(bad) => {
                    for f in bad.field_violations.iter() {
                        println!(
                            "  the request field {} has a problem: \"{}\"",
                            f.field, f.description
                        );
                    }
                }
                _ => {
                    println!("  additional error details: {detail:?}");
                }
            }
        }
    }

    Ok(())
}

Mengatasi error binding

Saat menggunakan HTTP untuk mengirim permintaan ke layanan Google Cloud , permintaan tersebut menggunakan Uniform Resource Identifier (URI) untuk menentukan resource. Beberapa RPC sesuai dengan beberapa URI, dan konten permintaan menentukan URI yang digunakan.

Library klien mempertimbangkan semua URI yang memungkinkan dan hanya menampilkan error binding jika tidak ada URI yang berfungsi. Biasanya, hal ini terjadi jika kolom tidak ada atau dalam format yang tidak valid.

Jika permintaan Anda gagal memberikan kolom yang berisi format yang valid untuk URI yang mungkin, Anda mungkin akan mengalami error binding:

Error: cannot find a matching binding to send the request: at least one of the
conditions must be met: (1) field `name` needs to be set and match the template:
'projects/*/secrets/*' OR (2) field `name` needs to be set and match the
template: 'projects/*/locations/*/secrets/*'

Error contoh sebelumnya terjadi karena contoh mencoba mengambil detail resource tanpa memberikan namanya. Secara khusus, kolom name pada GetSecretRequest diperlukan, tetapi contoh tidak menetapkannya:

let secret = client
    .get_secret()
    //.set_name("projects/my-project/secrets/my-secret")
    .send()
    .await;

Cara memperbaiki error binding

Untuk memperbaiki error, tetapkan kolom wajib diisi agar cocok dengan salah satu template yang ditampilkan dalam pesan error:

  • 'projects/*/secrets/*'
  • 'projects/*/locations/*/secrets/*'

Kedua template memungkinkan library klien membuat permintaan ke server. Misalnya, kode berikut cocok dengan template pertama:

let secret = client
    .get_secret()
    .set_name("projects/my-project/secrets/my-secret")
    .send()
    .await;

Atau, kode berikut cocok dengan template kedua:

let secret = client
    .get_secret()
    .set_name("projects/my-project/locations/us-central1/secrets/my-secret")
    .send()
    .await;

Menafsirkan template

Pesan error untuk error binding menyertakan string template yang menampilkan kemungkinan nilai untuk kolom permintaan. Sebagian besar string template menyertakan * dan ** sebagai karakter pengganti untuk mencocokkan nilai kolom.

Karakter pengganti tunggal

Karakter pengganti * saja berarti string yang tidak kosong tanpa /. Ini dapat dianggap sebagai ekspresi reguler [^/]+.

Berikut beberapa contohnya:

Template Input Cocok?
* simple-string-123 true
projects/* projects/p true
projects/*/locations projects/p/locations true
projects/*/locations/* projects/p/locations/l true
* "" (kosong) false
* string/with/slashes false
projects/* projects/ (kosong) false
projects/* projects/p/ (garis miring tambahan) false
projects/* projects/p/locations/l false
projects/*/locations projects/p false
projects/*/locations projects/p/locations/l false

Karakter pengganti ganda

Karakter pengganti **, yang berarti string apa pun, lebih jarang digunakan. String dapat berupa string kosong atau berisi sejumlah garis miring (/). String ini dapat dianggap sebagai ekspresi reguler .*.

Jika template diakhiri dengan /**, garis miring awal bersifat opsional.

Template Input Cocok?
** "" true
** simple-string-123 true
** string/with/slashes true
projects/*/** projects/p true
projects/*/** projects/p/locations true
projects/*/** projects/p/locations/l true
projects/*/** locations/l false
projects/*/** projects//locations/l false

Memeriksa error binding

Jika Anda perlu memeriksa error secara terprogram, periksa apakah error tersebut adalah error binding dan downcast ke BindingError:

let secret = client
    .get_secret()
    //.set_name("projects/my-project/secrets/my-secret")
    .send()
    .await;

let e = secret.unwrap_err();
assert!(e.is_binding(), "{e:?}");
assert!(e.source().is_some(), "{e:?}");
let _ = e
    .source()
    .and_then(|e| e.downcast_ref::<BindingError>())
    .expect("should be a BindingError");

Langkah berikutnya