Bonnes pratiques pour l'API Compute Engine

Ce document décrit les bonnes pratiques recommandées pour l'utilisation de l'API Compute Engine. Il est destiné aux utilisateurs qui la connaissent déjà. Si vous débutez, renseignez-vous sur les conditions préalables et l'utilisation de l'API Compute Engine.

Ces bonnes pratiques peuvent vous aider à gagner du temps, à éviter les erreurs et à atténuer les effets des quotas de débit.

Utiliser des bibliothèques clientes

Les bibliothèques clientes sont recommandées pour accéder par programmation à l'API Compute Engine. Les bibliothèques clientes fournissent le code pour accéder à l'API via des langages de programmation courants, ce qui vous permet de gagner du temps et d'améliorer les performances de votre code.

En savoir plus sur les bibliothèques clientes Compute Engine et les bonnes pratiques concernant les bibliothèques clientes.

Générer des requêtes REST à l'aide de Cloud Console

Lors de la création d'une ressource, générez la requête REST à l'aide des pages de création de ressources ou des pages d'informations de Google Cloud Console. L'utilisation d'une requête REST générée permet de gagner du temps et d'éviter les erreurs de syntaxe.

Découvrez comment générer des requêtes REST.

Attendre la fin des opérations

Ne partez pas du principe qu'une opération (toute requête API modifiant une ressource) est terminée ou réussie. Utilisez plutôt une méthode wait pour la ressource Operation afin de vérifier que l'opération est terminée. (Vous n'avez pas besoin de valider une requête qui ne modifie pas les ressources, par exemple une requête de lecture utilisant un verbe HTTP GET, car la réponse de l'API indique déjà si la requête a abouti. Par conséquent, l'API Compute Engine ne renvoie pas de ressources Operation pour ces requêtes.)

Chaque fois qu'une requête API a été lancée, elle renvoie un code d'état HTTP 200. Bien que la réception d'un code d'état 200 indique que le serveur a bien reçu votre requête API, il n'indique pas si l'opération demandée a abouti ou non. Par exemple, vous pouvez recevoir un code d'état 200, mais l'opération n'est peut-être pas encore terminée ou a échoué.

Toute requête de création, de mise à jour ou de suppression d'une opération de longue durée renvoie une ressource Operation, qui capture l'état de cette requête. Une opération est terminée lorsque le champ status de la ressource Operation indique DONE. Pour vérifier l'état, utilisez la méthode wait qui correspond au champ d'application de la ressource Operation renvoyée :

La méthode wait renvoie une réponse lorsque l'opération est terminée ou lorsque la requête approche du délai de deux minutes. Lorsque vous utilisez la méthode wait, évitez l'attente active de courte durée car vos clients adressent continuellement des requêtes au serveur sans attendre de réponse. Utilisez la méthode wait dans une boucle de nouvelle tentative dotée d'un intervalle exponentiel entre les tentatives pour vérifier l'état de votre requête, au lieu d'utiliser la méthode get avec l'interrogation courte pour la ressource Operation, ceci afin de préserver vos quotas de débit et réduire la latence.

Pour en savoir plus sur la méthode wait et obtenir des exemples, consultez la page Gérer les réponses d'API.

Pour vérifier l'état d'une opération demandée, consultez la section Vérifier l'état de l'opération.

En attendant la fin d'une opération, tenez compte de la période de conservation minimale des opérations, car les opérations terminées peuvent être supprimées de la base de données après cette période.

Paginer les résultats d'une liste

Lorsque vous utilisez une méthode de listage (telle qu'une méthode *.list, *.aggregatedList ou toute autre méthode renvoyant une liste), paginez les résultats autant que possible pour vous assurer de lire l'intégralité de la réponse. Si vous ne paginez pas, vous ne pouvez recevoir que les 500 premiers éléments, comme défini par le paramètre de requête maxResults.

Pour plus d'informations sur la pagination sur Google Cloud, consultez la page Pagination de liste. Pour obtenir des informations spécifiques et des exemples, consultez la documentation de référence sur la méthode de listage que vous souhaitez utiliser, telle que instances.list.

Vous pouvez également utiliser les bibliothèques clientes Cloud pour gérer la pagination.

Utiliser des filtres de liste côté client pour éviter les erreurs de quota

Lorsque vous utilisez des filtres avec les méthodes *.list ou *.aggregatedList, des frais de quota supplémentaires s'appliquent si les requêtes renvoies plus de 10 000 ressources filtrées. Pour en savoir plus, consultez la section filtered_list_cost_overhead dans Quotas de débit.

Si votre projet dépasse ce quota de débit, vous recevez une erreur 403 avec le motif suivant : rateLimitExceeded. Pour éviter cette erreur, utilisez des filtres côté client pour les requêtes de liste.

S'appuyer sur des codes d'erreur, et non sur des messages d'erreur

Les API Google doivent utiliser les codes d'erreur canoniques définis par google.rpc.Code, mais les messages d'erreur peuvent être modifiés sans préavis. Les messages d'erreur sont généralement destinés aux développeurs et non aux programmes.

En savoir plus sur les erreurs d'API.

Réduire les tentatives côté client pour conserver les quotas de débit

Réduisez le nombre de nouvelles tentatives côté client pour qu'un projet évite les erreurs rateLimitExceeded et optimise l'utilisation de vos quotas de débit. Les pratiques suivantes peuvent vous aider à préserver les quotas de débit de vos projets :

  • Évitez de recourir à l'attente active de courte durée.
  • Ne recourez à l'utilisation intensive qu'avec parcimonie et de manière sélective.
  • Effectuez toujours vos appels dans une boucle de nouvelle tentative dotée d'un intervalle exponentiel entre les tentatives.
  • Utilisez un limiteur de débit côté client.
  • Répartissez vos applications sur plusieurs projets.

Éviter de recourir à l'attente active de courte durée

Évitez de recourir à l'attente active de courte durée, car en ce cas vos clients adressent continuellement des requêtes au serveur sans attendre de réponse. Si vous utilisez l'attente active de courte durée, il est plus difficile d'intercepter les requêtes incorrectes, lesquelles sont prises en compte dans votre quota même si elles ne renvoient pas de données utiles.

Au lieu d'une attente active de courte durée, vous devez attendre que les opérations soient terminées.

Recourir à l'utilisation intensive avec parcimonie et de manière sélective

Ne recourez à l'utilisation intensive qu'avec parcimonie et de manière sélective. L'utilisation intensive permet à un client spécifique d'effectuer de nombreuses requêtes API en très peu de temps. En général, l'utilisation intensive est employée en réponse à des scénarios exceptionnels, par exemple lorsque votre application doit gérer plus de trafic qu'à l'accoutumée. Ce mode d'exécution atteint plus rapidement votre quota de débit. Nous vous recommandons donc de ne l'utiliser que lorsque cela est absolument nécessaire.

Lorsque l'utilisation intensive est requise, utilisez des API par lot dédiées lorsque cela est possible (API d'instance groupée ou groupes d'instances gérés).

En savoir plus sur les requêtes par lot.

Effectuer toujours vos appels dans une boucle de nouvelle tentative dotée d'un intervalle exponentiel entre les tentatives

Utilisez un intervalle exponentiel entre les tentatives afin d'espacer progressivement les requêtes lorsqu'elles expirent ou lorsque vous atteignez votre quota de débit.

Toute boucle de nouvelle tentative doit disposer d'un intervalle exponentiel entre les tentatives qui garantit que des tentatives trop fréquentes ne surchargent pas votre application et ne dépassent pas les quotas de débit. Sans cela, vous risquez de nuire à tous les autres systèmes du même projet.

Si vous avez besoin d'une boucle de nouvelle tentative pour une opération qui a échoué parce que vous avez atteint le quota de débit, votre stratégie d'intervalle exponentiel entre les tentatives doit laisser suffisamment de temps entre les tentatives pour que le bucket de quota soit rempli (généralement toutes les minutes).

Par ailleurs, si vous avez besoin d'une boucle de nouvelle tentative lorsque l'attente d'une opération atteint le délai avant expiration, l'intervalle maximal de votre stratégie d'intervalle exponentiel entre les tentatives ne doit pas dépasser la période de conservation minimale de l'opération. Sinon, vous risquez de recevoir une erreur Not Found d'opération.

Pour obtenir un exemple de mise en œuvre de l'intervalle exponentiel entre les tentatives, consultez l'algorithme d'intervalle exponentiel entre les tentatives pour l'API Identity and Access Management.

Utiliser un limiteur de débit côté client

Utilisez un limiteur de débit côté client. Un limiteur de débit côté client définit une limite artificielle empêchant le client concerné de dépasser un certain quota, ce qui empêche un même client de consommer l'intégralité de votre quota.

Répartir vos applications sur plusieurs projets

La répartition de vos applications sur plusieurs projets peut contribuer à réduire le nombre de requêtes pour vos buckets de quota. Étant donné que les quotas sont appliqués au niveau de chaque projet, vous pouvez répartir vos applications sur différents projets pour que chacune d'entre elles dispose d'un bucket de quotas.

Checklist

La checklist suivante récapitule les bonnes pratiques d'utilisation de l'API Compute Engine.

Étape suivante