Gestione degli errori

Offri un'esperienza utente più coerente interpretando e rispondendo in modo proattivo agli errori. Sia che tu stia sviluppando workflow cloud automatizzati o interagendo con API remote, le librerie client Rust forniscono modi per gestire gli errori in modo controllato. Questo documento spiega come:

  • Gestisci gli errori: esamina i tipi di errore e crea rami della logica dell'applicazione in base ai codici di stato del servizio, ad esempio creando una risorsa mancante quando si verifica un errore NotFound.
  • Esamina i dettagli degli errori: estrai dettagli completi sugli errori, come violazioni dei campi di richieste non valide o errori di quota, dai servizi Google Cloud per risolvere i problemi delle API e regolare il comportamento di runtime.
  • Risolvi gli errori di associazione: interpreta e risolvi gli errori di associazione HTTP lato client causati da campi di richiesta non validi o mancanti per assicurarti che le tue richieste raggiungano il servizio senza problemi.

Prerequisiti

Questo documento utilizza il servizio Secret Manager e l'API Cloud Natural Language per dimostrare la gestione degli errori. Per eseguire gli esempi, innanzitutto:

  1. Abilita il servizio Secret Manager.
  2. Abilita l'API Cloud Natural Language.
  3. Configura l'autenticazione.

Dipendenze

Utilizza il seguente comando per aggiungere le dipendenze richieste al file Cargo.toml:

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

Gestisci gli errori

Le librerie client Rust ti consentono di rilevare e reagire agli errori. Ad esempio, potresti utilizzare il rilevamento degli errori per creare un ramo del comportamento. Un pattern comune nei servizi cloud è utilizzare una risorsa come se il suo container esistesse e creare il container solo se si verifica un errore. Se il container esiste già, questo approccio è più efficiente rispetto alla verifica dell'esistenza del container prima di effettuare la richiesta.

L'esempio seguente rileva l'errore durante l'aggiornamento di un secret di Secret Manager e lo crea se non esiste.

  1. Prova a creare una nuova versione del secret:

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

  2. Se update_attempt ha esito positivo, stampa il risultato positivo e restituisci:

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

  3. Se update_attempt non va a buon fine, devi disambiguare la causa dell'errore. La richiesta potrebbe non essere andata a buon fine per diversi motivi, ad esempio una connessione interrotta o un errore con i token di autenticazione. I criteri per i nuovi tentativi possono gestire la maggior parte di questi errori. Cerca gli errori restituiti dal servizio:

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

  4. Cerca un errore corrispondente a un secret mancante:

    if status.code == Code::NotFound {

  5. Se hai riscontrato un errore "non trovato" (Code::NotFound), prova a creare il secret:

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

  6. Prova ad aggiungere di nuovo la versione del secret. Questa volta, restituisci un errore se qualcosa non va a buon fine:

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

Esempio di codice: funzione main (sample)

Il codice completo di questo esempio è diviso in tre parti: la funzione di orchestrazione principale (sample), seguita dai suoi due metodi helper (update_attempt e create_secret).

La funzione sample tenta di aggiungere una nuova versione a un secret. Rileva l'errore restituito dal client e controlla se si tratta di un errore Code::NotFound. Se il secret non viene trovato, la funzione crea il secret inizialmente mancante e riprova l'aggiornamento.

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

Esempio di codice: metodo helper (update_attempt)

Il metodo helper update_attempt tenta di aggiungere una versione del secret, calcolando il checksum CRC32c dei dati del 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)
}

Esempio di codice: metodo helper (create_secret)

Il metodo helper create_secret crea un secret mancante e configura una policy di ripetizione personalizzata:

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

Esamina i dettagli dell'errore

Alcuni servizi Google Cloud includono dettagli aggiuntivi sugli errori quando le richieste non vanno a buon fine. Per facilitare la risoluzione dei problemi, le librerie client Rust includono questi dettagli quando formattano gli errori utilizzando std::fmt::Display. Puoi esaminare questi dettagli e modificare il comportamento dell'applicazione di conseguenza.

Solo gli errori restituiti dal servizio contengono informazioni dettagliate. Le librerie client restituiscono un'enumerazione StatusDetails con i diversi tipi di dettagli dell'errore.

Estrai i dettagli dell'errore

Questo esempio invia intenzionalmente una richiesta non valida all'API Cloud Natural Language ed esamina l'errore risultante.

  1. Crea un client:

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

  2. Invia una richiesta (in questo esempio manca un campo chiave):

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

  3. Estrai l'errore dal risultato utilizzando le funzioni Rust standard. Il tipo di errore stampa tutti i dettagli dell'errore in un formato leggibile:

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

L'output è simile al seguente:

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: {},
                    },
                ),
            ],
        },
    },
}

Esamina i dettagli degli errori in modo programmatico

A volte potrebbe essere necessario esaminare i dettagli dell'errore in modo programmatico. Questo esempio attraversa la struttura dei dati e stampa i campi più pertinenti.

Solo gli errori restituiti dal servizio contengono informazioni dettagliate, quindi esegui prima una query sull'errore per verificare se contiene il tipo di errore corretto. In questo caso, puoi analizzare alcune informazioni di primo livello sull'errore:

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

Esegui l'iterazione dei dettagli:

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

Le librerie client restituiscono un enum StatusDetails con i diversi tipi di dettagli dell'errore. Questo esempio esamina solo gli errori BadRequest:

StatusDetails::BadRequest(bad) => {

Un BadRequest contiene un elenco di campi in violazione. Puoi eseguire l'iterazione e stampare i dettagli di ciascuno:

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

Queste informazioni possono essere utili durante lo sviluppo. Altri rami di StatusDetails, come QuotaFailure, potrebbero essere utili in fase di runtime per limitare un'applicazione.

Output previsto:

L'output dei dettagli dell'errore è simile al seguente:

  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."

Esempio di codice: esamina i dettagli dell'errore

La funzione sample invia una richiesta intenzionalmente non valida all'API Cloud Natural Language per generare un errore del servizio. Quindi, rileva l'errore ed estrae in modo programmatico StatusDetails per ispezionare e stampare violazioni specifiche del campo BadRequest.

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

Risolvi gli errori di associazione

Quando utilizzi HTTP per inviare richieste ai servizi Google Cloud , la richiesta utilizza un Uniform Resource Identifier (URI) per specificare una risorsa. Alcune RPC corrispondono a più URI e i contenuti della richiesta determinano l'URI utilizzato.

La libreria client prende in considerazione tutti gli URI possibili e restituisce un errore di associazione solo se nessun URI funziona. In genere, questo accade quando un campo è mancante o in un formato non valido.

Se la richiesta non fornisce campi contenenti un formato valido per un URI possibile, potresti riscontrare un errore di associazione:

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/*'

L'errore dell'esempio precedente si è verificato perché l'esempio tenta di recuperare i dettagli di una risorsa senza fornirne il nome. In particolare, il campo name di un GetSecretRequest è obbligatorio, ma l'esempio non lo imposta:

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

Come risolvere il problema degli errori di associazione

Per correggere l'errore, imposta il campo obbligatorio in modo che corrisponda a uno dei modelli mostrati nel messaggio di errore:

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

Entrambi i modelli consentono alla libreria client di inviare una richiesta al server. Ad esempio, il seguente codice corrisponde al primo template:

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

In alternativa, il seguente codice corrisponde al secondo modello:

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

Modelli di interpretariato

Il messaggio di errore per un errore di associazione include stringhe di template che mostrano i possibili valori per i campi della richiesta. La maggior parte delle stringhe dei modelli include * e ** come caratteri jolly per trovare i valori dei campi corrispondenti.

Carattere jolly singolo

Il carattere jolly * da solo indica una stringa non vuota senza /. Può essere considerata come l'espressione regolare [^/]+.

Ecco alcuni esempi:

Modello Input Corrispondenza?
* simple-string-123 true
projects/* projects/p true
projects/*/locations projects/p/locations true
projects/*/locations/* projects/p/locations/l true
* "" (vuoto) false
* string/with/slashes false
projects/* projects/ (vuoto) false
projects/* projects/p/ (barra aggiuntiva) false
projects/* projects/p/locations/l false
projects/*/locations projects/p false
projects/*/locations projects/p/locations/l false

Doppio carattere jolly

Meno comune è il carattere jolly **, che indica qualsiasi stringa. La stringa può essere vuota o contenere un numero qualsiasi di barre (/). Può essere considerata come l'espressione regolare .*.

Quando un modello termina con /**, la barra iniziale è facoltativa.

Modello Input Corrispondenza?
** "" 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

Controlla gli errori di associazione

Se devi ispezionare l'errore in modo programmatico, controlla se si tratta di un errore di associazione ed esegui il downcast a un 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");

Passaggi successivi