Utiliser l'explorateur d'API

Ce guide explique comment utiliser APIs Explorer pour tester les méthodes de l'API Cloud Monitoring. APIs 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 le panneau tel qu'il apparaît pour une méthode avec un seul paramètre, name:

Widget APIs Explorer

APIs Explorer est un excellent moyen de tester des méthodes dans l'API Cloud 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 ou l'afficher en plein écran en cliquant sur le bouton .

Boutons Essayer

Dans la documentation, des boutons Essayer peuvent s'afficher, tels que les suivants:

Essayer

Lorsque vous cliquez sur le bouton, APIs Explorer s'ouvre sur la page de référence de la méthode. En règle générale, certains paramètres appropriés pour l'exemple sont renseignés. Toutefois, vous devrez peut-être en modifier pour qu'ils correspondent à votre propre projet, tels que la valeur de [PROJECT_ID].

Pour en savoir plus sur la façon d'éviter et de corriger les erreurs, consultez la page Résoudre les problèmes.

Accéder à APIs Explorer

APIs Explorer est associé à la page de référence de chaque méthode de l'API REST. Pour trouver le widget, consultez la page de référence d'une méthode. Par exemple, consultez metricDescriptors.list.

Exécuter une requête

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 après avoir fourni les valeurs de tous les arguments requis.

La méthode metricDescriptors.list renvoie des descripteurs pour tous les types de métriques disponibles dans un projet. Le seul paramètre requis est le paramètre name.

Pour exécuter la méthode metricDescriptors.list, procédez comme suit:

  1. Cliquez sur Essayer.
  2. Dans le paramètre name (nom), saisissez l'ID de votre projet au format projects/[PROJECT_ID]. Veillez à remplacer [PROJECT_ID] par l'ID de votre projet.
  3. Cliquez sur Exécuter. Pour exécuter la commande, APIs Explorer requiert l'accès à votre compte. Lorsque vous y êtes invité, sélectionnez un compte, puis cliquez sur Autoriser. L'accès est limité pendant une durée limitée à la méthode API que vous exécutez.

Les résultats de l'appel de méthode s'affichent dans un cadre avec un en-tête vert ou rouge. Lorsque la requête aboutit, la zone comporte un en-tête vert contenant le code d'état HTTP 200. Les résultats de l'appel se trouvent dans la zone:

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

Lorsque l'en-tête est rouge, il contient un code d'échec HTTP et le cadre contient le message d'erreur. Pour en savoir plus sur la résolution des erreurs, consultez la page Résoudre des problèmes.

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é. Par exemple, la méthode metricDescriptors.list comporte plus que le paramètre name, mais name est le seul paramètre requis.

Lorsque vous ne fournissez que le nom du projet, vous obtenez tous les descripteurs de métriques disponibles dans votre projet, et il en existe un grand nombre. Pour limiter la récupération à un ensemble plus petit, utilisez le paramètre de filtre.

Par exemple, pour répertorier uniquement les types de métriques dont le nom se termine par utilization, procédez comme suit:

  1. Cliquez sur Essayer.

  2. Dans le paramètre name (nom), saisissez l'ID de votre projet au format projects/[PROJECT_ID]. Veillez à remplacer [PROJECT_ID] par l'ID de votre projet.

  3. Assurez-vous que le paramètre filter a la valeur metric.type=ends_with("utilization")

  4. Cliquez sur Exécuter et terminez les boîtes de dialogue d'autorisation.

Paramètres standards

Par défaut, l'ensemble de paramètres affiché par APIs Explorer correspond aux paramètres de la méthode associée. Toutefois, le widget APIs Explorer comporte également un ensemble de paramètres supplémentaires qui ne font pas partie de la méthode. Pour afficher les paramètres supplémentaires, cliquez sur Show standard parameters (Afficher les paramètres standards) :

Activer/Désactiver "Afficher les paramètres standards".

Pour masquer les paramètres supplémentaires à l'écran, cliquez sur Masquer les paramètres standards.

Le paramètre standard le plus utile est celui du champ fields. Ce paramètre vous permet de sélectionner les champs que vous souhaitez voir dans le résultat renvoyé.

Par exemple, si vous répertoriez les descripteurs pour les métriques se terminant par utilization, vous obtenez toujours de nombreux résultats. Si vous souhaitez uniquement connaître le nom du type de métrique et sa description, vous pouvez spécifier cette restriction à l'aide du paramètre fields.

Pour afficher le résultat du paramètre fields, procédez comme suit:

  1. Cliquez sur Essayer.

  2. Dans le paramètre name (nom), saisissez l'ID de votre projet au format projects/[PROJECT_ID]. Veillez à remplacer [PROJECT_ID] par l'ID de votre projet.

  3. Assurez-vous que le paramètre filter a la valeur metric.type=ends_with("utilization")

  4. Cliquez sur Afficher les paramètres standards, et vérifiez que le paramètre fields a la valeur metricDescriptors.type,metricDescriptors.description.

  5. Cliquez sur Exécuter et terminez les boîtes de dialogue d'autorisation.

L'exécution de cette requête ne renvoie que le type (nom court) de chaque métrique et sa description.

Résoudre les problèmes

Cette section décrit les problèmes courants liés à l'utilisation d'APIs Explorer.

Pour en savoir plus sur l'utilisation de l'API Cloud Monitoring, consultez la page Résoudre les problèmes liés à l'API Cloud Monitoring.

Identifiant de projet non valide

Si l'identifiant du projet n'est pas valide, la requête API échoue avec une erreur HTTP de 400.

Pour résoudre cette condition, vérifiez que le texte [PROJECT_ID] a été remplacé par l'ID de votre projet.

Valeurs de formulaire non valides

Si votre requête API échoue ou renvoie des valeurs inattendues, vérifiez tous les paramètres du formulaire.

Les paramètres d'APIs Explorer nécessitent une mise en forme spécifique. Les erreurs de mise en forme peuvent entraîner des erreurs, ou être acceptées, mais traitées comme des erreurs d'orthographe dans la méthode API:

  • N'utilisez pas de guillemets autour des valeurs de paramètre, quel que soit leur type.
  • N'utilisez pas de barres obliques inverses, sauf lorsque vous devez protéger une sous-chaîne.

    Par exemple, l'exemple suivant concerne une méthode d'API où vous saisissez le contenu au format JSON, au lieu de saisir les paramètres du formulaire individuellement. Comme la valeur de filter est une chaîne, la sous-chaîne k8s_cluster est protégée par des barres obliques inverses:

    {
      "resourceNames": [...],
      "filter": "resource.type = \"k8s_cluster\""
    }
  • N'utilisez pas l'encodage des URL dans le formulaire. Si une méthode API nécessite un encodage des URL, le widget effectue la conversion lorsque vous exécutez la méthode.

Trop de données sont renvoyées

Pour limiter le nombre de résultats renvoyés, saisissez une valeur (par exemple, 2) dans le paramètre pageSize. Le paramètre pageSize définit le nombre maximal de résultats renvoyés et est disponible pour la plupart des méthodes d'API.

Pour sélectionner des champs spécifiques à renvoyer, utilisez le paramètre fields. Pour en savoir plus, consultez la section Paramètres standards.

Authentification

Une section Identifiants figure sur la page APIs Explorer. Nous vous recommandons de conserver les valeurs par défaut de ces champs. Le mécanisme d'authentification par défaut est Google OAuth 2.0.

Pour connaître les champs d'application d'API requis pour la méthode, cliquez sur Afficher les champs d'application. Par défaut, tous les champs d'application nécessaires sont accordés.

Pour en savoir plus sur ces concepts, consultez la page Contrôle des accès.