Package google.rpc

Indice

• Code (enum)
• Status (messaggio)

Codice

I codici di errore canonici per le API gRPC.

A volte possono essere applicati più codici di errore. I servizi devono restituire il codice di errore più specifico applicabile. Ad esempio, preferisci OUT_OF_RANGE a FAILED_PRECONDITION se entrambi i codici sono applicabili. Allo stesso modo, preferisci NOT_FOUND o ALREADY_EXISTS a FAILED_PRECONDITION.

Enum
OK	Non è un errore; restituito in caso di esito positivo Mappatura HTTP: 200 OK
CANCELLED	L'operazione è stata annullata, in genere dal chiamante. Mapping HTTP: 499 Client Closed Request
UNKNOWN	Errore sconosciuto. Ad esempio, questo errore può essere restituito quando un valore Status ricevuto da un altro spazio degli indirizzi appartiene a uno spazio di errore sconosciuto in questo spazio degli indirizzi. Anche gli errori generati dalle API che non restituiscono informazioni sufficienti sugli errori possono essere convertiti in questo errore. Mapping HTTP: 500 Internal Server Error
INVALID_ARGUMENT	Il client ha specificato un argomento non valido. Tieni presente che questo valore è diverso da FAILED_PRECONDITION. INVALID_ARGUMENT indica argomenti problematici indipendentemente dallo stato del sistema (ad es. un nome file non valido). Mapping HTTP: 400 Bad Request
DEADLINE_EXCEEDED	La scadenza è terminata prima che l'operazione potesse essere completata. Per le operazioni che modificano lo stato del sistema, questo errore può essere restituito anche se l'operazione è stata completata correttamente. Ad esempio, una risposta corretta da un server potrebbe essere stata ritardata abbastanza a lungo da far scadere il termine. Mappatura HTTP: 504 Gateway Timeout
NOT_FOUND	Impossibile trovare alcune entità richieste (ad es. file o directory). Nota per gli sviluppatori di server: se una richiesta viene negata per un'intera classe di utenti, ad esempio il lancio graduale di funzionalità o una lista consentita non documentata, è possibile utilizzare NOT_FOUND. Se una richiesta viene negata per alcuni utenti all'interno di una classe di utenti, ad esempio il controllo dell'accesso basato sull'utente, è necessario utilizzare PERMISSION_DENIED. Mappatura HTTP: 404 - Non trovato
ALREADY_EXISTS	L'entità che un client ha tentato di creare (ad es. file o directory) esiste già. Mapping HTTP: 409 Conflict
PERMISSION_DENIED	Il chiamante non dispone dell'autorizzazione per eseguire l'operazione specificata. PERMISSION_DENIED non deve essere utilizzato per i rifiuti causati dall'esaurimento di alcune risorse (utilizza RESOURCE_EXHAUSTED per questi errori). PERMISSION_DENIED non deve essere utilizzato se il chiamante non può essere identificato (utilizza UNAUTHENTICATED per questi errori). Questo codice di errore non implica che la richiesta sia valida o che l'entità richiesta esista o soddisfi altre precondizioni. Mappatura HTTP: 403 - Non consentito
UNAUTHENTICATED	La richiesta non ha credenziali di autenticazione valide per l'operazione. Mappatura HTTP: 401 - Non autorizzato
RESOURCE_EXHAUSTED	Alcune risorse sono esaurite, ad esempio una quota per utente o l'intero file system è esaurito. Mapping HTTP: 429 Too Many Requests
FAILED_PRECONDITION	L'operazione è stata rifiutata perché il sistema non è nello stato richiesto per l'esecuzione dell'operazione. Ad esempio, la directory da eliminare non è vuota, un'operazione rmdir viene applicata a un elemento che non è una directory e così via. Gli implementatori di servizi possono utilizzare le seguenti linee guida per decidere tra FAILED_PRECONDITION, ABORTED e UNAVAILABLE: (a) Utilizza UNAVAILABLE se il client può riprovare solo la chiamata non riuscita. (b) Utilizza ABORTED se il client deve riprovare a un livello superiore (ad es. quando un test e un'impostazione specificati dal client non vanno a buon fine, il che indica che il client deve riavviare una sequenza di lettura-modifica-scrittura). (c) Utilizza FAILED_PRECONDITION se il client non deve riprovare finché lo stato del sistema non è stato corretto in modo esplicito. Ad esempio, se un comando "rmdir" non va a buon fine perché la directory non è vuota, deve essere restituito FAILED_PRECONDITION, poiché il client non deve riprovare a meno che i file non vengano eliminati dalla directory. Mapping HTTP: 400 Bad Request
ABORTED	L'operazione è stata interrotta, in genere a causa di un problema di concorrenza, ad esempio un controllo del sequencer non riuscito o un'interruzione della transazione. Consulta le linee guida riportate sopra per decidere tra FAILED_PRECONDITION, ABORTED e UNAVAILABLE. Mapping HTTP: 409 Conflict
OUT_OF_RANGE	L'operazione è stata tentata oltre l'intervallo valido. Ad esempio, cercare o leggere la fine del file. A differenza di INVALID_ARGUMENT, questo errore indica un problema che potrebbe essere risolto se lo stato del sistema cambia. Ad esempio, un file system a 32 bit genererà INVALID_ARGUMENT se gli viene chiesto di leggere a un offset non compreso nell'intervallo [0,2^32-1], ma genererà OUT_OF_RANGE se gli viene chiesto di leggere da un offset successivo alla dimensione corrente del file. Esiste una sovrapposizione piuttosto ampia tra FAILED_PRECONDITION e OUT_OF_RANGE. Ti consigliamo di utilizzare OUT_OF_RANGE (l'errore più specifico) quando si applica, in modo che i chiamanti che scorrono uno spazio possano cercare facilmente un errore OUT_OF_RANGE per rilevare quando hanno terminato. Mapping HTTP: 400 Bad Request
UNIMPLEMENTED	L'operazione non è implementata o non è supportata/abilitata in questo servizio. Mappatura HTTP: 501 Not Implemented
INTERNAL	Errori interni. Ciò significa che alcuni invarianti previsti dal sistema sottostante sono stati violati. Questo codice di errore è riservato agli errori gravi. Mapping HTTP: 500 Internal Server Error
UNAVAILABLE	Il servizio non è al momento disponibile. Si tratta molto probabilmente di una condizione temporanea, che può essere corretta riprovando con un backoff. Consulta le linee guida riportate sopra per decidere tra FAILED_PRECONDITION, ABORTED e UNAVAILABLE. Mappatura HTTP: 503 Servizio non disponibile
DATA_LOSS	Perdita o danneggiamento dei dati non recuperabili. Mapping HTTP: 500 Internal Server Error

Stato

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.

Campi
code	int32 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[]	Any Un elenco di messaggi contenenti i dettagli dell'errore. Esiste un insieme comune di tipi di messaggi da utilizzare per le API.