Status

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

number

Le code d'état, qui doit être une valeur énumérée de google.rpc.Code .

message

string

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 google.rpc.Status.details , ou localisé par le client.

details[]

object

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 "@type" contient un URI identifiant le type. Exemple : { "id": 1234, "@type": "types.example.com/standard/id" } .