Status

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

  • Semplice da usare e da capire per la maggior parte degli utenti
  • Flessibilità sufficiente 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 deve essere un valore enum di google.rpc.Code, ma potrebbe accettare codici di errore aggiuntivi, se necessario. Il messaggio di errore deve essere in inglese e rivolto agli sviluppatori, in modo da aiutarli a comprendere e risolvere l'errore. Se è necessario un messaggio di errore localizzato rivolto all'utente, inseriscilo nei dettagli dell'errore o localizzalo nel client. I dettagli facoltativi dell'errore potrebbero 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.

Mapping delle lingue

Il messaggio Status è la rappresentazione logica del modello di errore, ma non è necessariamente il formato di trasmissione effettivo. Quando il messaggio Status viene esposto in diverse librerie client e diversi protocolli di trasferimento, può essere mappato in modo diverso. Ad esempio, è probabile che venga mappato ad alcune eccezioni in Java, ma più probabilmente ad alcuni codici di errore in C.

Altri usi

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

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. 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 ogni risposta secondaria di errore.

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

  • Logging. Se alcuni errori API vengono archiviati nei log, il messaggio Status può 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 di 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 o localizzato dal client.

details[]

object

Un elenco di messaggi contenenti i dettagli dell'errore. Esiste un insieme comune di tipi di messaggi da utilizzare per le API.

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