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:
- Abilita il servizio Secret Manager.
- Abilita l'API Cloud Natural Language.
- 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.
Prova a creare una nuova versione del secret:
Se
update_attemptha esito positivo, stampa il risultato positivo e restituisci:Se
update_attemptnon 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:Cerca un errore corrispondente a un secret mancante:
Se hai riscontrato un errore "non trovato" (
Code::NotFound), prova a creare il secret:Prova ad aggiungere di nuovo la versione del secret. Questa volta, restituisci un errore se qualcosa non va a buon fine:
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.
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:
Esempio di codice: metodo helper (create_secret)
Il metodo helper create_secret crea un secret mancante e configura una policy di ripetizione personalizzata:
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.
Crea un client:
Invia una richiesta (in questo esempio manca un campo chiave):
Estrai l'errore dal risultato utilizzando le funzioni Rust standard. Il tipo di errore stampa tutti i dettagli dell'errore in un formato leggibile:
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:
Esegui l'iterazione dei dettagli:
Le librerie client restituiscono un enum StatusDetails con i diversi tipi di dettagli dell'errore. Questo esempio esamina solo gli errori BadRequest:
Un BadRequest contiene un elenco di campi in violazione. Puoi eseguire l'iterazione e stampare i dettagli di ciascuno:
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.
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:
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:
In alternativa, il seguente codice corrisponde al secondo modello:
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:
Passaggi successivi
- Scopri di più sulla configurazione delle policy di ripetizione.