Le type Status
définit un modèle d'erreur logique adapté à différents environnements de programmation, notamment les API REST et les API RPC. Il est utilisé par gRPC . Le modèle d'erreur est conçu pour être :
- Simple à utiliser et à comprendre pour la plupart des utilisateurs
- Suffisamment flexible pour répondre à des besoins inattendus
Aperçu
Le message Status
contient trois éléments de données : le code d'erreur, le message d'erreur et les détails de l'erreur. Le code d'erreur doit être une valeur énumérée de google.rpc.Code
, mais il peut accepter des codes d'erreur supplémentaires si nécessaire. Le message d'erreur doit être un message en anglais destiné aux développeurs qui aide les développeurs à comprendre et à résoudre l'erreur. Si un message d'erreur localisé destiné à l'utilisateur est nécessaire, placez le message localisé dans les détails de l'erreur ou localisez-le dans le client. Les détails facultatifs de l'erreur peuvent contenir des informations arbitraires sur l'erreur. Il existe un ensemble prédéfini de types de détails d'erreur dans le package google.rpc
qui peut être utilisé pour les conditions d'erreur courantes.
Cartographie linguistique
Le message Status
est la représentation logique du modèle d'erreur, mais il ne s'agit pas nécessairement du format de fil réel. Lorsque le message Status
est exposé dans différentes bibliothèques clientes et différents protocoles filaires, il peut être mappé différemment. Par exemple, il sera probablement mappé à certaines exceptions en Java, mais plus probablement à certains codes d'erreur en C.
Autres utilisations
Le modèle d'erreur et le message Status
peuvent être utilisés dans divers environnements, avec ou sans API, pour offrir une expérience de développeur cohérente dans différents environnements.
Exemples d'utilisation de ce modèle d'erreur :
Erreurs partielles. Si un service doit renvoyer des erreurs partielles au client, il peut intégrer le
Status
dans la réponse normale pour indiquer les erreurs partielles.Erreurs de flux de travail. Un flux de travail typique comporte plusieurs étapes. Chaque étape peut avoir un message
Status
pour le rapport d'erreurs.Opérations par lots. Si un client utilise une demande par lots et une réponse par lots, le message
Status
doit être utilisé directement dans la réponse par lots, un pour chaque sous-réponse d'erreur.Opérations asynchrones. Si un appel d'API intègre une opération asynchrone aboutissant à sa réponse, l'état de ces opérations doit être représenté directement à l'aide du message
Status
.Enregistrement. Si certaines erreurs API sont stockées dans les journaux, le message
Status
pourrait être utilisé directement après toute suppression nécessaire pour des raisons de sécurité/confidentialité.
Représentation JSON | |
---|---|
{ "code": number, "message": string, "details": [ { "@type": string, field1: ..., ... } ] } |
Des champs | |
---|---|
code | Le code d'état, qui doit être une valeur énumérée de |
message | Un message d'erreur destiné aux développeurs, qui doit être en anglais. Tout message d'erreur destiné à l'utilisateur doit être localisé et envoyé dans le champ |
details[] | Une liste de messages contenant les détails de l'erreur. Il existe un ensemble commun de types de messages que les API peuvent utiliser. Un objet contenant des champs d'un type arbitraire. Un champ supplémentaire |