Errori

Questo capitolo fornisce una panoramica del modello di errore per le API di Google. Inoltre, fornisce indicazioni generali agli sviluppatori su come generare e gestire gli errori.

Le API di Google utilizzano un semplice modello di errore indipendente dal protocollo, che ci consente offrono un’esperienza coerente tra diverse API, diversi protocolli API (ad esempio gRPC o HTTP) e diversi contesti di errore (ad esempio asincroni, batch o del flusso di lavoro).

Modello di errore

Il modello di errore per le API di Google è definito logicamente google.rpc.Status, un'istanza viene restituita al client quando si verifica un errore dell'API. La Il seguente snippet di codice mostra la struttura generale del modello di errore:

package google.rpc;

// The `Status` type defines a logical error model that is suitable for
// different programming environments, including REST APIs and RPC APIs.
message Status {
  // A simple error code that can be easily handled by the client. The
  // actual error code is defined by `google.rpc.Code`.
  int32 code = 1;

  // A developer-facing human-readable error message in English. It should
  // both explain the error and offer an actionable resolution to it.
  string message = 2;

  // Additional error information that the client code can use to handle
  // the error, such as retry info or a help link.
  repeated google.protobuf.Any details = 3;
}

Poiché la maggior parte delle API di Google utilizza una progettazione delle API orientata alle risorse, la gestione degli errori segue lo stesso principio di progettazione utilizzando un piccolo insieme di errori standard con un un numero elevato di risorse. Ad esempio, invece di definire diversi tipi di "non trovato" gli errori, il server utilizza un'istruzione google.rpc.Code.NOT_FOUND standard codice di errore e indica al client quale risorsa specifica non è stata trovata. Lo spazio degli errori più ridotto riduce la complessità della documentazione, consente mappature idiomatiche migliori nelle librerie client e riduce la complessità della logica del client senza limitare l'inclusione di informazioni utili.

Nota: quando utilizzi gRPC, gli errori sono inclusi nelle intestazioni e le intestazioni totali nei le risposte sono limitate a 8 KB (8.192 byte). Assicurati che gli errori non superino Dimensione: 1-2 kB.

Codici di errore

Le API di Google devono utilizzare i codici di errore canonici definiti dalla google.rpc.Code Le singole API devono evitare di definire ulteriori codici di errore, poiché è molto improbabile che gli sviluppatori scrivano logica per gestire un grande numero di errori i codici. Come riferimento, come gestire una media di tre codici di errore per chiamata API significa che la maggior parte della logica dell'applicazione è destinata solo alla gestione degli errori, non saranno una buona esperienza degli sviluppatori.

Messaggi di errore

Il messaggio di errore deve aiutare gli utenti a comprendere e risolvere l'errore dell'API. in modo semplice e rapido. In generale, tieni presente le seguenti linee guida quando scrivi di errore:

• Non dare per scontato che l'utente sia un utente esperto dell'API. Gli utenti potrebbero essere clienti sviluppatori, addetti alle operazioni, personale IT o utenti finali delle app.
• Non dare per scontato che l'utente sappia qualcosa sull'implementazione del servizio conosce il contesto degli errori (come l'analisi dei log).
• Ove possibile, i messaggi di errore devono essere creati in modo tale che (ma non necessariamente uno sviluppatore dell'API) può rispondere all'errore. e correggilo.
• Mantieni breve il messaggio di errore. Se necessario, fornisci un link nel caso in cui lettore può porre domande, fornire feedback o ottenere ulteriori informazioni che non rientra perfettamente in un messaggio di errore. Altrimenti, utilizza il campo dei dettagli per espandere.

Avviso: i messaggi di errore non fanno parte della piattaforma API. Sono soggetti a modifiche senza preavviso. Il codice dell'applicazione non deve avere una dipendenza rigida sui messaggi di errore.

Dettagli errore

Le API di Google definiscono un insieme di payload di errori standard per i dettagli degli errori, che puoi trovare in google/rpc/error_details.proto. che coprono le esigenze più comuni di errori delle API, come errori di quota e parametri non validi. Come per i codici di errore, gli sviluppatori devono utilizzare questi payload standard ove possibile.

Ulteriori tipi di dettagli degli errori devono essere introdotti solo se possono essere utili del codice dell'applicazione per gestire gli errori. Se le informazioni sull'errore possono essere gestite da persone, fare affidamento sui contenuti dei messaggi di errore e lasciare che gli sviluppatori gestiscano manualmente anziché introdurre altri tipi di dettagli degli errori.

Ecco alcuni esempi di payload error_details:

• ErrorInfo: fornisce informazioni sugli errori strutturati che sono stabili e estendibili.
• RetryInfo: Descrive quando i client possono riprovare una richiesta non riuscita (può essere un tentativo non riuscito) restituito in data Code.UNAVAILABLE o Code.ABORTED
• QuotaFailure: descrive in che modo un controllo della quota non è riuscito, può essere restituito il Code.RESOURCE_EXHAUSTED
• BadRequest: descrive le violazioni in una richiesta del client, può essere restituito su Code.INVALID_ARGUMENT

Informazioni sull'errore

ErrorInfo è un tipo speciale di payload di errore. Offre funzionalità stabili e estensibili, da cui possono dipendere sia gli esseri umani che le applicazioni. Ogni ErrorInfo contiene tre informazioni: un dominio di errore, un motivo di errore e un insieme di metadati di errore, come in questo esempio. Per ulteriori informazioni, consulta la definizione di ErrorInfo.

Per le API di Google, il dominio di errore principale è googleapis.com e i motivi di errore corrispondenti sono definiti dall'enum google.api.ErrorReason. Per ulteriori informazioni, consulta google.api.ErrorReason definizione di Kubernetes.

Localizzazione degli errori

Il campo message in google.rpc.Status è rivolto agli sviluppatori e deve essere in inglese.

Se è necessario un messaggio di errore rivolto all'utente, utilizza google.rpc.LocalizedMessage come campo dei dettagli. Mentre il campo del messaggio google.rpc.LocalizedMessage possono essere localizzati, assicurati che il campo del messaggio google.rpc.Status è in inglese.

Per impostazione predefinita, il servizio API deve utilizzare le impostazioni internazionali o HTTP dell'utente autenticato l'intestazione Accept-Language o il parametro language_code nella richiesta a determinare la lingua per la localizzazione.

Mappatura degli errori

Le API di Google sono accessibili in diversi ambienti di programmazione. Ciascuna in genere utilizza un proprio modo di gestione degli errori. Le seguenti spiegano come viene mappato il modello di errore negli ambienti di uso comune.

Mappatura HTTP

Sebbene i messaggi proto3 abbiano una codifica JSON nativa, la piattaforma API di Google utilizza uno schema di errori diverso per le API HTTP JSON di Google per motivi di compatibilità con le versioni precedenti.

Schema:

// This message defines the error schema for Google's JSON HTTP APIs.
message Error {
  // Deprecated. This message is only used by error format v1.
  message ErrorProto {}
  // This message has the same semantics as `google.rpc.Status`. It uses HTTP
  // status code instead of gRPC status code. It has extra fields `status` and
  // `errors` for backward compatibility with [Google API Client
  // Libraries](https://developers.google.com/api-client-library).
  message Status {
    // The HTTP status code that corresponds to `google.rpc.Status.code`.
    int32 code = 1;
    // This corresponds to `google.rpc.Status.message`.
    string message = 2;
    // Deprecated. This field is only used by error format v1.
    repeated ErrorProto errors = 3;
    // This is the enum version for `google.rpc.Status.code`.
    google.rpc.Code status = 4;
    // This corresponds to `google.rpc.Status.details`.
    repeated google.protobuf.Any details = 5;
  }
  // The actual error payload. The nested message structure is for backward
  // compatibility with [Google API Client
  // Libraries](https://developers.google.com/api-client-library). It also
  // makes the error more readable to developers.
  Status error = 1;
}

Esempio (link):

{
  "error": {
    "code": 400,
    "message": "API key not valid. Please pass a valid API key.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "API_KEY_INVALID",
        "domain": "googleapis.com",
        "metadata": {
          "service": "translate.googleapis.com"
        }
      }
    ]
  }
}

Mappatura gRPC

Protocolli RPC diversi mappano il modello di errore in modo diverso. Per gRPC, il modello di errore è supportato in modo nativo dal modulo e la libreria di runtime in ogni linguaggio supportato. Puoi scoprire di più nella documentazione dell'API di gRPC. Ad esempio, vedi la documentazione di gRPC Java io.grpc.Status

Mappatura della libreria client

Le librerie client di Google possono scegliere di visualizzare gli errori in modo diverso in base alla lingua per coerente con le espressioni idiomatiche consolidate. Ad esempio, la libreria google-cloud-go restituirà un errore che implementa la stessa interfaccia di google.rpc.Status, mentre google-cloud-java solleverà un'eccezione.

Gestione degli errori

Di seguito è riportata una tabella contenente tutti i codici di errore gRPC definiti in google.rpc.Code e una breve descrizione della relativa causa. Per gestire un errore, puoi controllare per il codice di stato restituito e modifica la chiamata di conseguenza.

HTTP	gRPC	Descrizione
200	OK	Nessun errore.
400	INVALID_ARGUMENT	Il client ha specificato un argomento non valido. Per ulteriori informazioni, consulta il messaggio e i dettagli dell'errore.
400	FAILED_PRECONDITION	La richiesta non può essere eseguita nello stato di sistema attuale, ad esempio eliminando una directory non vuota.
400	OUT_OF_RANGE	Il client ha specificato un intervallo non valido.
401	UNAUTHENTICATED	La mancata autenticazione della richiesta è dovuta a un token OAuth mancante, non valido o scaduto.
403	PERMISSION_DENIED	Il client non dispone di autorizzazioni sufficienti. Questo può accadere perché il token OAuth non ha gli ambiti corretti, il client non dispone dell'autorizzazione o l'API non è stata abilitata.
404	NOT_FOUND	La risorsa specificata non è stata trovata.
409	ABORTED	Conflitto di contemporaneità, ad esempio conflitto di lettura, modifica e scrittura.
409	ALREADY_EXISTS	La risorsa che un client ha cercato di creare esiste già.
429	RESOURCE_EXHAUSTED	Quota di risorse esaurita o vicina alla limitazione della frequenza. Per ulteriori informazioni, il client deve cercare i dettagli dell'errore google.rpc.QuotaFailure.
499	CANCELLED	La richiesta è stata annullata dal client.
500	DATA_LOSS	Perdita di dati non recuperabili o danneggiamento dei dati. Il cliente deve segnalare l'errore all'utente.
500	UNKNOWN	Errore sconosciuto del server. In genere si tratta di un bug del server.
500	INTERNAL	Errore interno del server. In genere si tratta di un bug del server.
501	NOT_IMPLEMENTED	Metodo API non implementato dal server.
502	N/D	Si è verificato un errore di rete prima di raggiungere il server. Generalmente si tratta di un'interruzione di rete o di una configurazione errata.
503	UNAVAILABLE	Servizio non disponibile. In genere il server non è attivo.
504	DEADLINE_EXCEEDED	Scadenza richiesta superata. Ciò si verifica solo se chi chiama imposta una scadenza più breve di quella predefinita del metodo (ovvero la scadenza richiesta non è sufficiente per l'elaborazione della richiesta da parte del server) e la richiesta non è stata completata entro la scadenza.

Avviso: le API di Google potrebbero verificare contemporaneamente più prerequisiti per una richiesta API. La restituzione di un codice di errore non implica che altre precondizioni siano soddisfatto. Il codice dell'applicazione non deve dipendere dall'ordine della condizione preliminare controlli.

Nuovo tentativo per gli errori

I client possono riprovare in caso di errori 503 UNAVAILABLE con backoff esponenziale. Il ritardo minimo deve essere di 1 secondo, a meno che non sia documentato diversamente. Il valore predefinito la ripetizione dovrebbe essere una volta, a meno che non sia documentato diversamente.

Per gli errori 429 RESOURCE_EXHAUSTED, il client può riprovare a un livello superiore con un ritardo minimo di 30 secondi. Questi nuovi tentativi sono utili solo per le esecuzioni di lunga durata job in background.

Per tutti gli altri errori, la ripetizione potrebbe non essere applicabile. Innanzitutto, assicurati che la tua richiesta è idempotente e vediamo google.rpc.RetryInfo per assistenza.

Propagazione degli errori

Se il tuo servizio API dipende da altri servizi, non dovresti propagare alla cieca da questi servizi ai tuoi clienti. Per la traduzione degli errori, le seguenti:

• Nascondi dettagli di implementazione e informazioni riservate.
• Modifica la parte responsabile dell'errore. Ad esempio, un server riceve un errore INVALID_ARGUMENT da un altro servizio dovrebbe propagarsi INTERNAL al proprio chiamante.

Riprodurre gli errori

Se non riesci a risolvere gli errori tramite l'analisi dei log e il monitoraggio, provare a riprodurre gli errori con un test semplice e ripetibile. Puoi utilizzare lo per raccogliere ulteriori informazioni per la risoluzione dei problemi, che puoi fornire quando contatti l'assistenza tecnica.

Ti consigliamo di utilizzare curl -v e Parametri di sistema con cui riprodurre gli errori API di Google. Insieme possono riprodurre quasi tutte le richieste API di Google, e fornirti informazioni di debug dettagliate. Per ulteriori informazioni, consulta rispettive pagine della documentazione per l'API che stai chiamando.

Errori di generazione

Se sei uno sviluppatore di server, dovresti generare errori con un numero di informazioni per aiutare gli sviluppatori dei clienti a comprendere e risolvere il problema. Allo stesso tempo, devi essere consapevole della sicurezza e della privacy dei dati utente ed evitare di divulgare informazioni sensibili nel messaggio di errore e nei dettagli dell'errore, poiché gli errori vengono spesso registrati e potrebbero essere accessibili ad altri. Ad esempio, un un messaggio di errore del tipo "L'indirizzo IP del client non è incluso nella lista consentita 128.0.0.0/8" espone informazioni sul criterio lato server, che potrebbe non essere accessibile che ha accesso ai log.

Per generare gli errori corretti, devi prima conoscere google.rpc.Code per scegliere il codice di errore più adatto a ogni condizione di errore. Un server l'applicazione può controllare più condizioni di errore in parallelo e restituire il il primo.

Nella tabella seguente sono elencati tutti i codici di errore e un esempio di errore corretto. per creare un nuovo messaggio email.

HTTP	gRPC	Messaggio di errore di esempio
400	INVALID_ARGUMENT	Il campo di richiesta x.y.z è xxx, previsto uno tra [yyy, zzz].
400	FAILED_PRECONDITION	La risorsa xxx è una directory non vuota, pertanto non può essere eliminata.
400	OUT_OF_RANGE	Parametro "age" è al di fuori dell'intervallo [0, 125].
401	UNAUTHENTICATED	Credenziali di autenticazione non valide.
403	PERMISSION_DENIED	Autorizzazione "xxx" negata per la risorsa "yyy".
404	NOT_FOUND	Risorsa "xxx" non trovato.
409	ABORTED	Impossibile acquisire il blocco sulla risorsa "xxx".
409	ALREADY_EXISTS	Risorsa "xxx" esiste già.
429	RESOURCE_EXHAUSTED	Limite quota "xxx" superato.
499	CANCELLED	La richiesta è stata annullata dal client.
500	DATA_LOSS	Vedi nota.
500	UNKNOWN	Vedi nota.
500	INTERNAL	Vedi nota.
501	NOT_IMPLEMENTED	Metodo "xxx" non implementato.
503	UNAVAILABLE	Vedi nota.
504	DEADLINE_EXCEEDED	Vedi nota.

Nota: poiché il client non è in grado di correggere l'errore del server, non è utile generano ulteriori dettagli sull'errore. Per evitare la divulgazione di informazioni sensibili condizioni di errore, è consigliabile non generare messaggi di errore e genera dettagli errore google.rpc.DebugInfo. DebugInfo è un regalo speciale progettato solo per il logging lato server e non deve essere inviato al client.

Payload di errore

Il pacchetto google.rpc definisce un insieme di payload di errore standard, che sono preferiti ai payload di errore personalizzati. La tabella seguente elenca ogni codice di errore e il relativo payload di errore standard corrispondente, se applicabile. Ti consigliamo un livello avanzato le applicazioni cercano questi payload di errore in google.rpc.Status quando e gestire gli errori.

HTTP	gRPC	Dettaglio errore consigliato
400	INVALID_ARGUMENT	google.rpc.BadRequest
400	FAILED_PRECONDITION	google.rpc.PreconditionFailure
400	OUT_OF_RANGE	google.rpc.BadRequest
401	UNAUTHENTICATED	google.rpc.ErrorInfo
403	PERMISSION_DENIED	google.rpc.ErrorInfo
404	NOT_FOUND	google.rpc.ResourceInfo
409	ABORTED	google.rpc.ErrorInfo
409	ALREADY_EXISTS	google.rpc.ResourceInfo
429	RESOURCE_EXHAUSTED	google.rpc.QuotaFailure
499	CANCELLED
500	DATA_LOSS	google.rpc.DebugInfo
500	UNKNOWN	google.rpc.DebugInfo
500	INTERNAL	google.rpc.DebugInfo
501	NOT_IMPLEMENTED
503	UNAVAILABLE	google.rpc.DebugInfo
504	DEADLINE_EXCEEDED	google.rpc.DebugInfo