État

Le type Status définit un modèle d'erreur logique adapté aux différents environnements de programmation, y compris les API REST et RPC. Il est utilisé par le protocole gRPC. Le modèle d'erreur est conçu pour être :

  • facile à utiliser et à comprendre pour la plupart des utilisateurs ;
  • suffisamment flexible pour répondre à des besoins inattendus.

Présentation

Le message Status contient trois éléments de données : un code d'erreur, un message d'erreur et les détails de l'erreur. Le code d'erreur doit être une valeur d'énumération google.rpc.Code, mais des codes d'erreur supplémentaires peuvent également être acceptés au besoin. Le message d'erreur doit être un message en anglais destiné aux développeurs, les aidant à comprendre et à résoudre l'erreur. Si un message d'erreur localisé destiné à l'utilisateur est nécessaire, vous pouvez le placer dans les détails de l'erreur ou le localiser dans le client. Les détails d'erreur facultatifs 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.

Mappage 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 communication réel. Lorsque le message Status est exposé dans différentes bibliothèques clientes et divers protocoles de communication, il peut être mappé différemment. Par exemple, il sera sans doute mappé à des exceptions en Java, mais plus probablement à des 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 aux développeurs une expérience cohérente.

Voici quelques 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 message Status dans la réponse normale pour les indiquer.

  • Erreurs de flux de travail. Un flux de travail typique comporte plusieurs étapes. Chaque étape peut inclure un message Status signalant les erreurs.

  • Opérations par lot. Si un client emploie des requêtes et des réponses par lot, le message Status doit être utilisé directement dans la réponse par lot pour chaque sous-réponse d'erreur.

  • Opérations asynchrones. Si un appel d'API intègre les résultats d'une opération asynchrone dans la réponse, l'état de ces opérations doit être représenté directement à l'aide du message Status.

  • Journalisation. Si certaines erreurs d'API sont consignées dans des journaux, le message Status peut être utilisé directement après toute suppression requise pour des raisons de sécurité/confidentialité.

Représentation JSON 

{
  "code": number,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ],
}
Champs
code

number

Code d'état, qui doit être une valeur d'énumération de google.rpc.Code.

message

string

Message d'erreur destiné au développeur, qui doit être en anglais. Tout message d'erreur destiné aux utilisateurs doit être localisé et envoyé dans le champ google.rpc.Status.details, ou localisé par le client.

details[]

object

Liste de messages comportant les détails de l'erreur. Il existe un ensemble commun de types de message utilisable par les API.

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" }.