Il tipo Status
definisce un modello di errore logico adatto a diversi ambienti di programmazione, incluse le API REST e le API RPC. Viene utilizzato da gRPC . Il modello di errore è progettato per essere:
- Semplice da usare e comprendere per la maggior parte degli utenti
- Abbastanza flessibile per soddisfare esigenze impreviste
Panoramica
Il messaggio Status
contiene tre dati: codice di errore, messaggio di errore e dettagli dell'errore. Il codice di errore dovrebbe essere un valore enum di google.rpc.Code
, ma potrebbe accettare codici di errore aggiuntivi, se necessario. Il messaggio di errore deve essere un messaggio in inglese rivolto agli sviluppatori che aiuti gli sviluppatori a comprendere e risolvere l'errore. Se è necessario un messaggio di errore localizzato rivolto all'utente, inserisci il messaggio localizzato nei dettagli dell'errore o localizzalo nel client. I dettagli facoltativi dell'errore possono contenere informazioni arbitrarie sull'errore. Esiste un insieme predefinito di tipi di dettagli di errore nel pacchetto google.rpc
che può essere utilizzato per condizioni di errore comuni.
Mappatura della lingua
Il messaggio Status
è la rappresentazione logica del modello di errore, ma non è necessariamente il formato effettivo del cavo. Quando il messaggio Status
viene esposto in librerie client diverse e protocolli di collegamento diversi, può essere mappato in modo diverso. Ad esempio, sarà probabilmente mappato su alcune eccezioni in Java, ma più probabilmente su alcuni codici di errore in C.
Altri usi
Il modello di errore e il messaggio Status
possono essere utilizzati in una varietà di ambienti, con o senza API, per fornire un'esperienza di sviluppo coerente in ambienti diversi.
Gli esempi di utilizzo di questo modello di errore includono:
Errori parziali. Se un servizio deve restituire errori parziali al client, può incorporare lo
Status
nella risposta normale per indicare gli errori parziali.Errori del flusso di lavoro. Un tipico flusso di lavoro prevede più passaggi. Ogni passaggio può avere un messaggio
Status
per la segnalazione degli errori.Operazioni batch. Se un client utilizza la richiesta batch e la risposta batch, il messaggio
Status
deve essere utilizzato direttamente all'interno della risposta batch, uno per ciascuna risposta secondaria di errore.Operazioni asincrone. Se una chiamata API incorpora risultati di operazioni asincrone nella sua risposta, lo stato di tali operazioni deve essere rappresentato direttamente utilizzando il messaggio
Status
.Registrazione. Se alcuni errori API vengono archiviati nei log, il messaggio
Status
potrebbe essere utilizzato direttamente dopo qualsiasi eliminazione necessaria per motivi di sicurezza/privacy.
Rappresentazione JSON | |
---|---|
{ "code": number, "message": string, "details": [ { "@type": string, field1: ..., ... } ] } |
Campi | |
---|---|
code | Il codice di stato, che dovrebbe essere un valore enum di |
message | Un messaggio di errore rivolto agli sviluppatori, che dovrebbe essere in inglese. Qualsiasi messaggio di errore rivolto all'utente deve essere localizzato e inviato nel campo |
details[] | Un elenco di messaggi che contengono i dettagli dell'errore. Esiste un set comune di tipi di messaggio che le API possono utilizzare. Un oggetto contenente campi di tipo arbitrario. Un campo aggiuntivo |