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 l'affichage du panneau pour une méthode avec un seul paramètre, name :

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 close, ou le développer en mode plein écran en cliquant sur le bouton fullscreen.

Boutons Essayer

Dans la documentation, vous pouvez voir des boutons Essayer comme suit:

Lorsque vous cliquez sur ce 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 adaptés à l'exemple sont renseignés. Cependant, vous devrez peut-être modifier certains des paramètres pour qu'ils correspondent à votre propre projet, tels que la valeur de [PROJECT_ID].

Pour savoir comment éviter et 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 pour chaque méthode d'API REST. Pour trouver le widget, consultez la page de référence d'une méthode, par exemple 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 des valeurs pour tous les arguments requis.

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

1. Cliquez sur Essayer.
2. Dans le paramètre nom, saisissez l'ID de votre projet en utilisant le 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 et cliquez sur Autoriser. L'accès est limité dans le temps et se limite à la méthode API que vous exécutez.

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

Lorsque l'en-tête est rouge, il contient un code d'échec HTTP et la zone contient le message d'erreur. Pour en savoir plus sur la résolution des erreurs, consultez la page Résoudre les 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 contient plus que le paramètre nom, mais nom 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. Pour limiter la récupération à un ensemble plus petit, utilisez le paramètre filtre.

Par exemple, pour ne répertorier que 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 nom, saisissez l'ID de votre projet en utilisant le format projects/[PROJECT_ID]. Veillez à remplacer [PROJECT_ID] par l'ID de votre projet.

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

4. Cliquez sur Exécuter et remplissez 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 elle-même. Pour afficher les paramètres supplémentaires, cliquez sur Show standard parameters (Afficher les paramètres standards) :

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

Le paramètre standard le plus utile est le paramètre champs. Ce paramètre vous permet de sélectionner les champs de la sortie renvoyée que vous souhaitez afficher.

Par exemple, si vous répertoriez les descripteurs des métriques se terminant par utilization, vous obtenez toujours un grand nombre de 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 champs.

Pour afficher le résultat de la définition du paramètre champs, procédez comme suit:

1. Cliquez sur Essayer.

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

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

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

5. Cliquez sur Exécuter et remplissez 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.

Syntaxe de filtre incorrecte

Vous copiez une expression multiligne et la collez dans un champ affiché dans APIs Explorer, mais APIs Explorer affiche un message d'erreur.

À faire: assurez-vous que les chaînes se trouvent sur une seule ligne.

"query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count | within 5m"

Ne pas: copier et coller des caractères de continuation de ligne ou de nouvelle ligne.

Par exemple, si vous ajoutez les éléments suivants à la méthode timeSeries.query, APIs Explorer affiche le message d'erreur Select an underlined section to see more details:

"query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count
          | within 5m"

Identifiant de projet non valide

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

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

Valeurs du formulaire incorrectes

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

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

• N'utilisez pas de guillemets autour des valeurs des paramètres de n'importe quel type.

• N'utilisez pas de barre oblique inverse, sauf si vous devez protéger une sous-chaîne.

  L'exemple suivant concerne une méthode d'API dans laquelle vous saisissez le contenu au format JSON, plutôt que de renseigner des paramètres de formulaire individuels. La valeur de filter étant une chaîne, la sous-chaîne k8s_cluster est protégée par des barres obliques inverses:

    {
      "resourceNames": [...],
      "filter": "resource.type = \"k8s_cluster\""
    }

• Chaînes entre guillemets dans les filtres Utilisez des guillemets doubles (") et non des apostrophes ('). Pour obtenir un exemple, consultez la section Fournir des paramètres supplémentaires.

• N'utilisez pas l'encodage d'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 telle que 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 champs. Pour en savoir plus, consultez la section Paramètres standards.

Authentification

Il existe une section Identifiants sur la page APIs Explorer. Nous vous recommandons de conserver ces valeurs par défaut. 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 section Contrôler l'accès avec Identity and Access Management.