Utiliser l'API Explorer

Ce guide explique comment utiliser l'API Explorer pour tester les méthodes de l'API Monitoring. L'API Explorer est un widget associé à la page de référence de l'API REST pour une méthode. Il prend la forme d'un panneau intitulé Try this API (Essayer cette API). La capture d'écran suivante montre l'affichage du panneau pour une méthode avec un seul paramètre, name :

Le widget API Explorer.

L'API Explorer est un excellent moyen d'essayer des méthodes dans l'API Monitoring sans écrire de code. Le widget présente un formulaire indiquant les paramètres de chaque méthode. Remplissez le formulaire, cliquez sur le bouton Execute (Exécuter), puis consultez les résultats.

Vous pouvez également masquer le widget en cliquant sur le bouton  en haut du panneau ou le développer en mode plein écran en cliquant sur le bouton .

Boutons Essayer

Dans la documentation, vous verrez des boutons Essayer comme dans l'exemple suivant :

Essayer

Cliquer sur le bouton permet d'afficher l'API Explorer sur la page de référence appropriée et de remplir les champs en fonction de l'exemple. Vous devez modifier certains des champs pour qu'ils correspondent à votre propre projet. Par exemple, vous devez modifier la valeur de [PROJECT_ID].

Consultez la section Conseils pour savoir comment éviter et corriger les erreurs.

Accéder à API Explorer

L'API Explorer est associé à la page de référence pour chaque méthode d'API REST. Pour trouver le widget, accédez à la page de référence d'une méthode, par exemple la page de référence de monitoring.projects.metricDescriptors.list.

Exécuter une requête minimale

Pour la plupart des méthodes, certains paramètres sont obligatoires et d'autres sont facultatifs. Les paramètres obligatoires sont signalés par une barre rouge jusqu'à ce qu'ils soient remplis. Vous pouvez exécuter une requête minimale en ne fournissant que les arguments requis.

La méthode metricDescriptors.list renvoie des descripteurs pour tous les types de métriques disponibles dans un projet. Le seul champ obligatoire est le champ name. Pour récupérer cette liste pour votre projet, indiquez le nom de votre projet dans le champ name, au format projects/[PROJECT_ID].

Cliquez sur le bouton ci-dessous pour l'essayer, mais avant de cliquer sur le bouton Execute (Exécuter) du formulaire, vous devez remplacer [PROJECT_ID] par l'identifiant de votre projet :

Essayer

Les résultats de l'appel de la méthode apparaissent dans une zone sous le bouton Execute (Exécuter). En règle générale, la zone contient un en-tête vert avec le code d'état HTTP 200, indiquant ainsi que la requête a abouti. Les résultats de l'appel sont affichés dans la zone :

Résultat d'un appel de méthode réussi.

Si l'en-tête est rouge et contient un code d'échec HTTP, la zone d'affichage contient le message d'erreur. Consultez la section Conseils pour obtenir des conseils sur la résolution des erreurs.

Fournir des paramètres supplémentaires

La liste des paramètres qui s'affiche dépend de la méthode à laquelle le widget de l'API Explorer est associé. La méthode metricDescriptors.list ne contient pas que le paramètre name, mais name est le seul paramètre obligatoire.

Lorsque vous ne fournissez que le nom du projet, vous obtenez tous les descripteurs de métriques disponibles dans votre projet. Notez qu'ils sont nombreux. Vous pouvez utiliser le paramètre facultatif filter (filtre) pour limiter la récupération à un ensemble plus petit.

Par exemple, remplissez les champs suivants sur la page metricsDescriptor.list. Remplacez l'ID de votre projet par [PROJECT_ID], mais indiquez l'autre valeur comme ci-dessous :

  • name : projects/[PROJECT_ID]
  • filter : metric.type=ends_with("utilization")

L'exécution de cette requête ne renvoie que les descripteurs des types de métriques dont le nom se termine par utilization.

Essayer

Utiliser des champs pour limiter davantage la sortie

Par défaut, l'ensemble de paramètres affiché par l'API Explorer correspond aux paramètres de la méthode associée. Toutefois, le widget de l'API Explorer comporte également un ensemble de champs supplémentaires qui ne sont pas disponibles via la méthode elle-même.

Ces paramètres sont masqués sous le bouton Afficher les paramètres standards, situé au-dessus de la section Authentification :

Activer/Désactiver

Activez cette option pour afficher les paramètres supplémentaires du widget. Cliquez sur Masquer les paramètres standards pour les masquer.

Le paramètre fields (champs) est le plus utile. Il vous permet de sélectionner les champs que vous souhaitez afficher dans la sortie renvoyée. Cela est très utile dans le panneau de l'API Explorer, où le résultat est affiché dans une zone. Il y a souvent beaucoup de résultats à faire défiler.

Par exemple, la liste des descripteurs des métriques se terminant par utilization renvoie toujours beaucoup d'informations. Si vous êtes uniquement intéressé par le nom du type de métrique et sa description, vous pouvez utiliser le champ fields pour spécifier ces champs uniquement.

Pour voir la différence, remplissez les champs suivants sur la page metricsDescriptor.list. Remplacez l'ID de votre projet par [PROJECT_ID], mais indiquez les autres valeurs comme ci-dessous :

  • name, comme précédemment : projects/[PROJECT_ID]
  • filter, comme précédemment : metric.type=ends_with("utilization")
  • fields : metricDescriptors.type,metricDescriptors.description

L'exécution de cette requête ne renvoie que le type (nom court) de chaque métrique et sa description. Les éléments suivants font partie du résultat :

Essayer

Astuces

Penser à modifier [PROJECT_ID]

N'oubliez pas de remplacer [PROJECT_ID] par l'ID de votre projet. En cas d'oubli, vous obtenez le résultat suivant :

Message d'erreur lorsque vous oubliez de modifier PROJECT_ID.

Problèmes liés aux valeurs

Voici quelques problèmes à surveiller lors de l'utilisation des formulaires de l'API Explorer. Des valeurs incorrectes peuvent entraîner des erreurs. Elles peuvent aussi être acceptées, mais être traitées comme des fautes d'orthographe dans la méthode API :

  • N'utilisez pas de guillemets autour des valeurs des champs, quel que soit leur type.
  • Veillez à citer les chaînes qui apparaissent dans les filtres. Utilisez des guillemets doubles (") et non des apostrophes ('). Consultez la section Fournir des paramètres supplémentaires pour obtenir un exemple.
  • N'utilisez pas de barre oblique inverse ni d'URL encodées dans les champs de formulaire. Si nécessaire, l'encodage d'URL doit être effectué sur les valeurs de champ lorsque vous exécutez la méthode.
  • Examinez la valeur dans la zone de résultats après avoir exécuté l'appel. Vous remarquerez peut-être le problème.
  • Vous pouvez indiquer une valeur pour le champ pageSize (par exemple, 2). Cela limite la quantité de données renvoyées lorsque vous déboguez votre appel d'API.

Ajouter des URL aux favoris pour le débogage

Une fois la sortie souhaitée obtenue, ajoutez aux favoris l'URL de l'API Explorer. Lorsque vous souhaitez réexécuter la méthode, collez l'URL dans votre navigateur. Vos valeurs sont déjà insérées dans le formulaire qui s'affiche. Apportez les modifications nécessaires aux paramètres, puis cliquez sur Execute (Exécuter) pour exécuter à nouveau la méthode.

Authentication

La section Authentification se trouve sur la page de l'API Explorer, au-dessus du bouton Execute (Exécuter). Vous n'avez généralement rien à modifier ici.

Le mécanisme d'authentification par défaut est Google OAuth 2.0.

Il existe également un bouton Afficher les champs d'application dans la section Authentification. Cette option permet d'afficher ou de masquer les champs d'application Compute Engine disponibles. Par défaut, tous les champs d'application disponibles sont activés.

Pour plus d'informations sur ces concepts, consultez la page Contrôle des accès.

Dépannage

Si le problème persiste, consultez la page Dépannage de l'API Monitoring.