Status

Il tipo Status definisce un modello di errore logico adatto a diversi ambienti di programmazione, tra cui API REST e API RPC. È utilizzato da gRPC. Il modello di errore è progettato per essere:

  • Facile da usare e da capire per la maggior parte degli utenti
  • Flessibilità sufficientemente flessibile da soddisfare esigenze impreviste

Panoramica

Il messaggio Status contiene tre dati: codice di errore, messaggio di errore e dettagli dell'errore. Il codice di errore deve essere un valore enum pari a google.rpc.Code, ma, se necessario, può accettare codici di errore aggiuntivi. 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 agli utenti, inseriscilo nei dettagli dell'errore o localizzalo nel client. I dettagli facoltativi dell'errore possono contenere informazioni arbitrarie sull'errore. Nel pacchetto google.rpc è presente un insieme predefinito di tipi di dettagli degli errori che possono essere utilizzati per le condizioni di errore comuni.

Mappatura 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 e protocolli di cavo diversi, può essere mappato in modo diverso. Ad esempio, probabilmente verrà mappato ad alcune eccezioni in Java, ma molto probabilmente ad alcuni codici di errore in C.

Altri utilizzi

Il modello di errore e il messaggio Status possono essere utilizzati in diversi ambienti, con o senza API, per fornire un'esperienza di sviluppo coerente in ambienti diversi.

Esempi di utilizzo di questo modello di errore includono:

  • Errori parziali. Se un servizio deve restituire errori parziali al client, può incorporare Status nella risposta normale per indicare gli errori parziali.

  • Errori del flusso di lavoro. Un flusso di lavoro tipico prevede più passaggi. A ogni passaggio potrebbe essere presente un messaggio Status per la segnalazione degli errori.

  • Operazioni in batch. Se un client utilizza una richiesta e una risposta batch, il messaggio Status deve essere utilizzato direttamente all'interno della risposta batch, uno per ogni risposta secondaria di errore.

  • Operazioni asincrone. Se una chiamata API incorpora un'operazione asincrona e genera la risposta, lo stato di queste operazioni deve essere rappresentato direttamente utilizzando il messaggio Status.

  • Logging. Se alcuni errori dell'API sono archiviati nei log, il messaggio Status potrebbe essere utilizzato direttamente dopo qualsiasi rimozione necessaria per motivi di sicurezza/privacy.

Rappresentazione JSON 
{
  "code": number,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ],
}
Campi
code

number

Il codice di stato, che deve essere un valore enum pari a google.rpc.Code.

message

string

Un messaggio di errore rivolto agli sviluppatori, che deve essere in inglese. Qualsiasi messaggio di errore rivolto agli utenti deve essere localizzato e inviato nel campo google.rpc.Status.details oppure deve essere localizzato dal client.

details[]

object

Un elenco di messaggi con i dettagli dell'errore. Le API possono utilizzare un insieme comune di tipi di messaggi.

Un oggetto che contiene campi di tipo arbitrario. Un campo aggiuntivo "@type" contiene un URI che identifica il tipo. Esempio: { "id": 1234, "@type": "types.example.com/standard/id" }.