Ressource REST : projects.locations.operations

Ressource : Operation

Cette ressource représente une opération de longue durée résultant d'un appel d'API réseau.

Représentation JSON

{
  "name": string,
  "metadata": {
    "@type": string,
    field1: ...,
    ...
  },
  "done": boolean,

  // Union field result can be only one of the following:
  "error": {
    object(Status)
  },
  "response": {
    "@type": string,
    field1: ...,
    ...
  }
  // End of list of possible types for union field result.
}
Champs
name

string

Nom attribué par le serveur. Unique au sein du service qui le renvoie initialement. Si vous utilisez le mappage HTTP par défaut, le champ name doit être au format operations/some/unique/name.

metadata

object

Métadonnées spécifiques au service associées à l'opération. Ce champ contient généralement des informations de progression et des métadonnées courantes telles que la date de création. Certains services peuvent ne pas fournir ce genre de métadonnées. Toute méthode renvoyant une opération de longue durée doit indiquer le type de métadonnées, le cas échéant.

Objet contenant des champs d'un type arbitraire. Le champ supplémentaire "@type" contient un URI identifiant le type. Exemple : { "id": 1234, "@type": "types.example.com/standard/id" }.

done

boolean

Si la valeur est définie sur false, cela signifie que l'opération est toujours en cours. Si elle est définie sur true, l'opération est terminée et un message error ou response est disponible.

Valeur result du champ d'union. Le résultat de l'opération, qui peut être un message error ou response valide. Si done correspond à false, aucun message error ni response n'est défini. Si done correspond à true, exactement un message error ou response est défini. Le champ result ne peut être que l'un des éléments suivants :
error

object(Status)

Résultat d'erreur de l'opération en cas d'échec ou d'annulation.

response

object

Réponse normale de l'opération lorsqu'elle aboutit. Si la méthode d'origine ne renvoie aucune donnée en cas de réussite (telle que Delete), la réponse est google.protobuf.Empty. Si la méthode d'origine est un message standard Get/Create/Update, la réponse doit être la ressource. Pour les autres méthodes, la réponse doit comporter le type XxxResponse, où Xxx correspond au nom de la méthode d'origine. Par exemple, si le nom de la méthode d'origine est TakeSnapshot(), le type de la réponse supposée est TakeSnapshotResponse.

Objet contenant des champs d'un type arbitraire. Le champ supplémentaire "@type" contient un URI identifiant le type. Exemple : { "id": 1234, "@type": "types.example.com/standard/id" }.

É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.

Aperçu

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 de google.rpc.Code, mais des codes d'erreur supplémentaires peuvent également être acceptés en cas de 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. Un ensemble prédéfini de types de détails d'erreur est disponible dans le package google.rpc. Celui-ci 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 correspond pas nécessairement au format physique réel. Lorsque le message Status est exposé dans différentes bibliothèques clientes et diverses couches physiques, 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, de façon à fournir une expérience de développement cohérente quel que soit l'environnement.

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 une opération asynchrone dans sa réponse, l'état de cette opération 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

Le 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é à l'utilisateur 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. Le champ supplémentaire "@type" contient un URI identifiant le type. Exemple : { "id": 1234, "@type": "types.example.com/standard/id" }.

Méthodes

cancel

Démarre l'annulation asynchrone sur une opération de longue durée.

delete

Supprime une opération de longue durée.

get

Récupère le dernier état d'une opération de longue durée.

list

Répertorie les opérations qui correspondent au filtre spécifié dans la requête.

wait

Attend que l'opération de longue durée spécifiée soit terminée ou qu'elle ait atteint un délai d'expiration spécifié en renvoyant l'état le plus récent.