Méthodes personnalisées

Ce chapitre explique comment utiliser des méthodes personnalisées pour les conceptions d'API.

Les méthodes personnalisées font référence aux méthodes API en plus des cinq méthodes standards. Elles ne doivent être utilisées que pour des fonctionnalités difficiles à exprimer via des méthodes standards. En règle générale et dès que possible, les concepteurs d'API doivent choisir des méthodes standards plutôt que des méthodes personnalisées. Les méthodes standards ont une sémantique clairement définie et plus simple que la plupart des développeurs connaissent bien. Elles sont donc plus faciles à utiliser et moins sujettes aux erreurs. Un autre avantage des méthodes standards est que la plate-forme d'API offre une meilleure compréhension et une compatibilité améliorée avec les méthodes standards, telles que la facturation, la gestion des erreurs, la journalisation et la surveillance.

Une méthode personnalisée peut être associée à une ressource, une collection ou un service. Elle peut utiliser une requête arbitraire et renvoyer une réponse arbitraire. Elle est également compatible avec l'utilisation de requêtes et de réponses en streaming.

Les noms de méthodes personnalisées doivent respecter les conventions d'attribution de noms des méthodes.

Mise en correspondance HTTP

Pour les méthodes personnalisées, la mise en correspondance HTTP générique suivante doit être utilisée :

https://service.name/v1/some/resource/name:customVerb

Le choix de : plutôt que / pour séparer le verbe personnalisé et le nom de la ressource est dû à la compatibilité avec les chemins d'accès arbitraires. Par exemple, l'annulation de la suppression d’un fichier permet de mapper vers POST /files/a/long/file/name:undelete.

Les directives suivantes doivent être appliquées lors du choix de mise en correspondance HTTP :

Les méthodes personnalisées doivent utiliser le verbe POST HTTP étant donné qu'il possède la sémantique la plus flexible, à l'exception des méthodes servant d'alternative à "get" ou "list", qui peuvent quant à elles utiliser GET lorsque cela est possible. (Reportez-vous au troisième point de la liste pour plus de détails.)
Les méthodes personnalisées ne doivent pas utiliser le verbe PATCH HTTP, mais peuvent employer d'autres verbes HTTP. Dans ce cas, les méthodes doivent respecter la sémantique HTTP standard pour ce verbe.
En particulier, les méthodes personnalisées utilisant le verbe GET HTTP doivent être idempotentes et sans effets secondaires. Par exemple, les méthodes personnalisées qui mettent en œuvre des vues spéciales sur la ressource doivent utiliser le verbe GET HTTP.
Le ou les champs du message de requête recevant le nom de la ressource ou de la collection à laquelle la méthode personnalisée est associée doivent être mappés sur le chemin d'accès de l'URL.
Le chemin d'accès de l'URL doit se terminer par un suffixe composé de deux-points suivis du verbe personnalisé.
Si le verbe HTTP utilisé pour la méthode personnalisée accepte un corps de requête HTTP (cela s'applique à POST, PUT, PATCH ou un verbe HTTP personnalisé), la configuration HTTP de cette méthode personnalisée doit utiliser la clause body: "*" et tous les champs de message de requête restants correspondront au corps de la requête HTTP.
Si le verbe HTTP utilisé pour la méthode personnalisée n'accepte pas de corps de requête HTTP (GET, DELETE), la configuration HTTP de cette méthode ne doit pas du tout utiliser la clause body et tous les champs de message de requête restants correspondront aux paramètres de requête d'URL.

AVERTISSEMENT : Si un service met en œuvre plusieurs API, le générateur d'API doit soigneusement créer la configuration de service pour éviter les conflits de verbes personnalisés entre les API.

// This is a service level custom method.
rpc Watch(WatchRequest) returns (WatchResponse) {
  // Custom method maps to HTTP POST. All request parameters go into body.
  option (google.api.http) = {
    post: "/v1:watch"
    body: "*"
  };
}

// This is a collection level custom method.
rpc ClearEvents(ClearEventsRequest) returns (ClearEventsResponse) {
  option (google.api.http) = {
    post: "/v3/events:clear"
    body: "*"
  };
}

// This is a resource level custom method.
rpc CancelEvent(CancelEventRequest) returns (CancelEventResponse) {
  option (google.api.http) = {
    post: "/v3/{name=events/*}:cancel"
    body: "*"
  };
}

// This is a batch get custom method.
rpc BatchGetEvents(BatchGetEventsRequest) returns (BatchGetEventsResponse) {
  // The batch get method maps to HTTP GET verb.
  option (google.api.http) = {
    get: "/v3/events:batchGet"
  };
}

Cas d'utilisation

Voici quelques scénarios supplémentaires dans lesquels les méthodes personnalisées peuvent constituer le bon choix :

Redémarrage d'une machine virtuelle. Les alternatives de conception pourraient être "créer une ressource de redémarrage dans une collection de redémarrages" qui semble excessivement complexe, ou "la machine virtuelle a un état modifiable que le client peut mettre à jour de EN COURS D'EXÉCUTION à REDÉMARRAGE EN COURS", ce qui poserait des questions sur les transitions d'état possibles. De plus, le redémarrage est un concept bien connu qui peut se traduire par une méthode personnalisée répondant intuitivement aux attentes des développeurs.
Envoi de message. La création d’un message électronique ne doit pas nécessairement l’envoyer (brouillon). Par rapport à la variante de conception (déplacer un message dans une collection "Boîte d'envoi"), la méthode personnalisée présente l'avantage d'être plus facilement détectable par l'utilisateur de l'API et de modéliser le concept plus directement.
Promouvoir un employé. S'il est mis en œuvre en tant qu'élément update standard, le client doit répliquer les règles d'entreprise régissant le processus de promotion pour s'assurer que la promotion se passe au niveau approprié, dans la même échelle de carrière, etc.
Méthodes par lots. Pour les méthodes critiques en termes de performances, il peut être utile de fournir des méthodes de traitement par lots personnalisées afin de réduire les frais généraux par requête. Par exemple, accounts.locations.batchGet.

Voici quelques exemples où une méthode standard convient mieux qu'une méthode personnalisée :

Les ressources de requête avec des paramètres de requête différents (utilisez la méthode list standard avec un filtrage de liste standard).
La modification de propriété de ressource simple (utilisez la méthode update standard avec masque de champ).
Le fait d'ignorer une notification (utilisez la méthode delete standard).

Méthodes personnalisées courantes

La liste organisée de noms de méthodes personnalisées utiles ou couramment utilisés est présentée ci-dessous. Les concepteurs d'API doivent envisager ces noms avant d'introduire les leurs afin de faciliter la cohérence entre les API.

Nom de la méthode	Verbe personnalisé	Verbe HTTP	Note
`Cancel`	`:cancel`	`POST`	Annule une opération en attente, telle que `operations.cancel`.
`BatchGet`	`:batchGet`	`GET`	Récupère par lots des ressources multiples. Pour plus de détails, consultez la description de la méthode List.
`Move`	`:move`	`POST`	Déplace une ressource d'un parent à un autre, comme `folders.move`.
`Search`	`:search`	`GET`	Propose une alternative à la méthode List pour récupérer des données qui ne respectent pas la sémantique de List, telle que `services.search`.
`Undelete`	`:undelete`	`POST`	Restaure une ressource précédemment supprimée, comme `services.undelete`. La période de conservation recommandée est de 30 jours.

Méthodes standards

Champs standards