Gérer les champs d'application des métriques à l'aide de l'API

Ce document explique comment utiliser les méthodes de champ d'application des métriques dans l'API Cloud Monitoring pour gérer le champ d'application des métriques d'un projet Google Cloud. Cette page est destinée aux développeurs et aux administrateurs système.

Pour associer un compte AWS au champ d'application des métriques d'un projet Google Cloud, vous devez utiliser Google Cloud Console. Pour en savoir plus, consultez Afficher les métriques pour les comptes AWS.

Avant de commencer

  • Si vous ne connaissez pas le terme champ d'application des métriques ni le champ Champ d'application du champ d'application, consultez la section Champs d'application des métriques.

  • Assurez-vous que votre rôle de gestion de l'authentification et des accès (IAM) sur le projet de champ d'application vous permet de modifier le champ d'application des métriques du projet.

  • Pour chaque projet que vous souhaitez ajouter en tant que projet surveillé, assurez-vous que votre rôle IAM vous permet de modifier le champ d'application des métriques du projet. Pour en savoir plus sur les rôles IAM requis, consultez la section Configurations des champs d'application des métriques.

  • Les méthodes de champ d'application des métriques de l'API Cloud Monitoring qui récupèrent des informations sont synchrones. ces API sont toutefois asynchrones. Pour savoir comment déterminer quand une méthode asynchrone est terminée et comment déterminer son état, consultez la page Méthodes API asynchrones.

Paramètres de commande curl

Vous pouvez appeler directement les API de champs d'application de métriques. Cette page fournit des exemples de commandes utilisant curl. Chaque commande curl inclut un ensemble d'arguments suivi de l'URL d'une ressource API:

curl -H "Authorization: Bearer ${TOKEN}" <other_args> \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/<resource>

Les exemples de cette page s'appuient sur les variables d'environnement suivantes:

  • TOKEN: stocke le jeton d'authentification.
  • SCOPING_PROJECT_ID_OR_NUMBER: stocke l'ID ou le numéro d'un projet de champ d'application de métrique.
  • MONITORED_PROJECT_ID_OR_NUMBER: stocke l'ID ou le numéro d'un projet qui doit être ajouté à un champ d'application de métriques ou supprimé de celui-ci.

Vous devrez peut-être également spécifier d'autres arguments pour définir des éléments tels que le type de la requête HTTP (-X DELETE, par exemple). La requête par défaut est GET. Les exemples ne la spécifient donc pas.

Pour en savoir plus sur la configuration requise pour les exemples, consultez la section Configurer la commande curl.

Obtenir un champ d'application des métriques

Pour obtenir des informations sur un champ d'application des métriques, envoyez une requête GET au point de terminaison locations.global.metricsScopes.get:

curl -H "Authorization: Bearer ${TOKEN}" \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}

Si la requête aboutit, la réponse est un objet MetricsScope.

Cette méthode n'entraîne pas l'écriture d'une entrée dans les journaux d'audit du projet de champ d'application. Pour que ces actions soient enregistrées dans le journal d'audit, activez la lecture de données pour l'API Cloud Resource Manager. Pour en savoir plus, consultez la section Configurer les journaux d'audit pour l'accès aux données.

Répertorier tous les champs d'application de métriques qui incluent un projet

Pour obtenir la liste des champs d'application de métriques pouvant afficher les métriques d'un projet, envoyez une requête GET au point de terminaison locations.global.metricsScopes.listMetricsScopesByMonitoredProject et incluez la requête paramètre qui spécifie le projet.

curl -H "Authorization: Bearer ${TOKEN}" \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes:listMetricsScopesByMonitoredProject?monitored_resource_container=projects/${PROJECT_ID_OR_NUMBER}

Si la requête aboutit, la réponse est un tableau d'objets MetricsScope.

Cette méthode n'entraîne pas l'écriture d'une entrée dans les journaux d'audit du projet de champ d'application. Pour que ces actions soient enregistrées dans le journal d'audit, activez la lecture de données pour l'API Cloud Resource Manager. Pour en savoir plus, consultez la section Configurer les journaux d'audit pour l'accès aux données.

Ajouter un projet à un champ d'application des métriques

Pour ajouter un projet Google Cloud à un champ d'application des métriques, envoyez une requête POST au point de terminaison locations.global.metricsScopes.projects.create. Dans l'exemple suivant, le projet identifié par la variable d'environnement MONITORED_PROJECT_ID_OR_NUMBER est ajouté en tant que projet surveillé:

curl -H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" -X POST \
-d "{'name': 'locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}/projects/${MONITORED_PROJECT_ID_OR_NUMBER}'}" \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}/projects

La réponse de cette méthode asynchrone est un objet Operation.

Les applications qui appellent cette méthode doivent interroger le point de terminaison operation.get jusqu'à ce que la valeur du champ Operation.done soit true. Lorsque le champ Operation.done est défini sur false, cela indique que l'opération est en cours. Pour en savoir plus, consultez la page Commandes API asynchrones.

Voici un exemple de réponse lorsque l'ajout d'un projet surveillé aboutit:

{
  "name": "operations/6915efde-1915-400a-ad49-7b62041d9bd2",
  "metadata": {
    "@type": "type.googleapis.com/google.monitoring.metricsscope.v1.OperationMetadata",
    "state": "DONE",
    ...
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.monitoring.metricsscope.v1.MonitoredProject",
    "name": "locations/global/metricsScopes/012012012012/projects/678678678678",
    "provider": "GCP",
    "providerAccountId": "...",
    ...
  }
}

Dans la réponse précédente, le champ Operation.done est défini sur true. Cette valeur indique que la commande est terminée. Comme la commande a bien été exécutée, le champ Operation.response est défini et sa valeur est un objet MonitoredProject. Le champ response.name inclut l'identifiant du projet de champ d'application et du projet surveillé. Le champ providerAccountId répertorie le nom du projet surveillé.

L'appel de cette méthode génère une entrée dans les journaux d'audit du projet de champ d'application. Si vous utilisez Cloud Console pour ajouter un projet à un champ d'application de métriques, cette action n'est pas enregistrée dans les journaux d'audit. Cloud Console n'appelle pas cette méthode API.

Supprimer un projet du champ d'application des métriques

Pour supprimer un projet Google Cloud d'un champ d'application de métriques, envoyez une requête DELETE au point de terminaison locations.global.metricsScopes.projects.delete:

curl -H "Authorization: Bearer ${TOKEN}" -X DELETE \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}/projects/${MONITORED_PROJECT_ID_OR_NUMBER}

La réponse à cette méthode asynchrone est un objet Operation.

Les applications qui appellent cette méthode doivent interroger le point de terminaison operation.get jusqu'à ce que la valeur du champ Operation.done soit true. Lorsque le champ Operation.done est défini sur false, cela indique que l'opération est en cours. Pour en savoir plus, consultez la page Commandes API asynchrones.

Voici un exemple de réponse lorsque la suppression d'un projet surveillé aboutit:

{
  "name": "operations/4367ff34-0ff0-4767-b8d3-0638e30f077c",
  "metadata": {
    "@type": "type.googleapis.com/google.monitoring.metricsscope.v1.OperationMetadata",
    "state": "DONE",
    ...
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.protobuf.Empty"
  }
}

Dans la réponse précédente, le champ Operation.done est défini sur true. Cette valeur indique que la commande est terminée. Comme la commande a bien été exécutée, le champ Operation.response est défini et contient un champ @type.

L'appel de cette méthode génère une entrée dans les journaux d'audit du projet de champ d'application. Si vous utilisez Cloud Console pour supprimer un projet du champ d'application des métriques, cette action n'est pas enregistrée dans les journaux d'audit. Cloud Console n'appelle pas cette méthode API.

Méthodes API asynchrones

Toutes les méthodes de champ d'application de métriques de l'API Cloud Monitoring qui modifient l'état du système, par exemple la commande pour ajouter un projet surveillé, sont des méthodes asynchrones. Pour ces commandes, la réponse à la commande est un objet Operation.

Les applications qui appellent une méthode d'API asynchrone doivent interroger le point de terminaison operation.get jusqu'à ce que la valeur du champ Operation.done soit true:

  • Lorsque done est défini sur false, l'opération est en cours.

    Pour actualiser les informations d'état, envoyez une requête GET au point de terminaison operation.get:

    curl -H "Authorization: Bearer ${TOKEN}" \
    https://monitoring.googleapis.com/v1/${OPERATION_NAME}
    

    Dans la commande précédente, OPERATION_NAME est une variable d'environnement qui stocke la valeur du champ Operation.name.

  • Lorsque done est défini sur true, l'opération est terminée et le champ error ou response est défini:

    • error: si cet élément est défini, l'opération asynchrone a échoué. La valeur de ce champ est un objet Status contenant un code d'erreur gRPC et un message d'erreur.
    • response: si ce paramètre est défini, l'opération asynchrone a réussi et la valeur reflète le résultat.

Configuration de la commande curl

Cette section décrit la configuration utilisée pour créer les commandes curl dans ce document.

Définissez ces variables d'environnement pour simplifier la création des commandes curl:

  1. Créez la variable d'environnement pour stocker l'ID ou le numéro du projet de champ d'application:

    SCOPING_PROJECT_ID_OR_NUMBER=a-sample-project
    
  2. Facultatif. Si vous envisagez d'ajouter ou de supprimer des projets surveillés, configurez la variable d'environnement avec l'ID ou le numéro du projet surveillé:

    MONITORED_PROJECT_ID_OR_NUMBER=a-monitored-project
    
  3. Authentifiez-vous au SDK Cloud :

    gcloud auth login
    
  4. Facultatif. Pour éviter d'avoir à spécifier votre ID de projet avec chaque commande gcloud, définissez votre ID de projet par défaut à l'aide du SDK Cloud :

    gcloud config set project ${SCOPING_PROJECT_ID_OR_NUMBER}
    
  5. Créez un jeton d'autorisation et placez-le dans une variable d'environnement:

    TOKEN=`gcloud auth print-access-token`
    

    La durée de validité des jetons est limitée dans le temps. Si des commandes auparavant fonctionnelles indiquent soudainement que vous n'êtes pas authentifié, exécutez à nouveau cette commande.

  6. Pour vérifier que vous disposez bien d'un jeton d'accès, renvoyez la variable TOKEN :

    echo ${TOKEN}
    ya29.GluiBj8o....