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.

APIs Explorer est un excellent moyen de tester des méthodes dans l'API Monitoring sans avoir à écrire de code. Le widget présente un formulaire affichant les paramètres de chaque méthode. Remplissez le formulaire, cliquez sur le bouton Execute (Exécuter) et affichez 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

La plupart des méthodes ont des paramètres obligatoires et des paramètres facultatifs. Les paramètres obligatoires sont indiqué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 méthode s'affichent dans une zone sous le bouton Exécuter. En règle générale, cette zone comporte un en-tête vert avec le code d'état HTTP 200, indiquant que la requête a abouti. Les résultats de l'appel sont inclus dans la zone :

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

Si l'en-tête est rouge et contient un code d'échec HTTP, la zone 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 affichés dépend de la méthode à laquelle le widget APIs 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 votre ID de projet par [PROJECT_ID], mais indiquez l'autre valeur comme indiqué 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

Cliquez sur ce bouton pour afficher les paramètres de widget supplémentaires. Cliquez sur Hide standard parameters (Masquer les paramètres standards) pour masquer les paramètres standards.

Le plus utile de ces paramètres standards est le paramètre fields, qui permet de sélectionner les champs de la sortie renvoyée que vous souhaitez afficher. Cela est très utile dans le panneau de APIs Explorer, où la sortie est affichée dans une zone. Il y a souvent de nombreux résultats à faire défiler.

Par exemple, si vous répertoriez les descripteurs des métriques se terminant par utilization, vous obtenez toujours un grand nombre d'informations. Si vous êtes seulement intéressé par le nom du type de métrique et sa description, vous pouvez utiliser le champ fields pour ne spécifier que ces champs.

Pour voir la différence, renseignez les champs suivants sur la page metricsDescriptor.list. Remplacez votre ID de projet par [PROJECT_ID], mais indiquez les autres valeurs comme indiqué 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 changer 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 affichée dans la zone de résultat après l'exécution de l'appel. Vous remarquerez peut-être le problème.
  • Vous pouvez fournir une valeur pour le champ pageSize, telle que 2. Cela limite la quantité de données renvoyée lors du débogage de l'appel d'API.

Ajouter des URL aux favoris pour débogage

Une fois la sortie souhaitée obtenue, ajoutez aux favoris l'URL de l'explorateur d'API. Lorsque vous souhaitez réexécuter la méthode, collez l'URL dans votre navigateur. Le formulaire est déjà renseigné avec vos valeurs. Apportez les modifications nécessaires aux paramètres, puis cliquez sur Exécuter pour réexécuter la méthode.

Authentication

La section Authentification s'affiche sur la page de APIs Explorer, au-dessus du bouton Exécuter. En règle générale, vous n'avez rien à modifier.

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

La section Authentification comprend également un bouton Afficher les champs d'application. Elle indique les champs d'application de Compute Engine disponibles. Par défaut, tous les champs d'application disponibles sont activés.

Pour en savoir plus 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.