Status

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

number

Il codice di stato, che dovrebbe essere un valore enum di google.rpc.Code .

message

string

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 google.rpc.Status.details o localizzato dal client.

details[]

object

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 "@type" contiene un URI che identifica il tipo. Esempio: { "id": 1234, "@type": "types.example.com/standard/id" } .