Configurer un champ d'application des métriques à l'aide de l'API

Ce document explique comment utiliser la Google Cloud CLI ou l'API Cloud Monitoring pour configurer 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.

Les commandes de cette page font référence à un "conteneur de ressources". Bien qu'un conteneur de ressources puisse être une organisation, un dossier ou un projet, les commandes décrites sur cette page ne sont compatibles qu'avec les projets Google Cloud.

Avant de commencer

Si vous ne connaissez pas les termes champ d'application des métriques et projet de champ d'application, consultez la section champs d'application des métriques.
Assurez-vous que vos rôles Identity and Access Management (IAM) sur le projet effectuant une surveillance et sur chaque projet que vous souhaitez ajouter en tant que projet surveillé incluent toutes les autorisations du rôle "Administrateur Monitoring" (roles/monitoring.admin). Pour en savoir plus, consultez Configurations du champ 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. Cependant, ces API qui changent d'état sont asynchrones. Les commandes Google Cloud CLI sont bloquées jusqu'à la fin de l'opération asynchrone. Pour savoir comment déterminer quand une méthode API asynchrone est terminée et comment déterminer son état, consultez la section Méthodes d'API asynchrones.
Si vous envisagez d'appeler l'API Cloud Monitoring à l'aide de curl ou si vous souhaitez utiliser les exemples de cette page, suivez la procédure de configuration de la commande curl.

Répertorier tous les champs d'application des métriques incluant un projet

gcloud

Pour obtenir la liste des champs d'application des métriques pouvant afficher les métriques d'un conteneur de ressources, tel qu'un projet Google Cloud, exécutez la commande gcloud beta monitoring metrics-scopes list:

gcloud beta monitoring metrics-scopes list MONITORED_RESOURCE_CONTAINER_NAME

Avant d'exécuter la commande, saisissez l'identifiant du conteneur de ressources dans la variable MONITORED_RESOURCE_CONTAINER_NAME. Lorsque le conteneur de ressources est un projet Google Cloud, saisissez projects/PROJECT_ID_OR_NUMBER.

Par exemple, pour répertorier les champs d'application des métriques qui incluent le projet my-project, exécutez la commande suivante:

gcloud beta monitoring metrics-scopes list projects/my-project

La réponse suivante indique que le projet my-project est inclus dans deux champs d'application des métriques:

metricsScopes:
- createTime: '2018-08-06T17:13:42Z'
  name: locations/global/metricsScopes/012345012345
  updateTime: '2018-08-18T16:20:37.032928Z'
- createTime: '2021-04-13T15:37:26.869Z'
  name: locations/global/metricsScopes/9876543210
  updateTime: '2021-04-13T15:37:27.284239Z'

Pour obtenir des informations détaillées sur un champ d'application de métriques, exécutez la commande gcloud beta monitoring metrics-scopes describe.

curl

Pour obtenir la liste des champs d'application des 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 le paramètre de requête spécifiant 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 ne génère 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 page Configurer les journaux d'audit pour l'accès aux données.

Obtenir des détails sur un champ d'application de métriques

gcloud

Pour obtenir des informations détaillées sur un champ d'application de métriques, exécutez la commande gcloud beta monitoring metrics-scopes describe:

gcloud beta monitoring metrics-scopes describe METRICS_SCOPE_ID

Avant d'exécuter la commande, saisissez le nom complet d'un champ d'application de métriques dans la variable METRICS_SCOPE_ID. Voici un exemple de nom complet:

locations/global/metricsScopes/012345012345

Voici un exemple de réponse. Dans cet exemple, le champ d'application des métriques contient un projet, et l'ID du champ d'application des métriques et du projet sont identiques:

createTime: '2018-08-06T17:13:42Z'
monitoredProjects:
- createTime: '2018-08-06T17:13:42Z'
  name: locations/global/metricsScopes/012345012345/projects/012345012345
name: locations/global/metricsScopes/012345012345
updateTime: '2018-08-18T16:20:37.032928Z'

Pour identifier le projet Google Cloud à partir de son ID, exécutez la commande gcloud projects list et filtrez les données en fonction de l'ID du projet. Par exemple, pour obtenir le nom du projet 012345012345, exécutez la commande suivante:

gcloud projects list --filter="012345012345" -format="value(NAME)"

curl

Pour obtenir des informations sur le 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 l'opération réussit, la réponse est un objet MetricsScope.

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

gcloud

Pour ajouter un conteneur de ressources, tel qu'un projet Google Cloud, à un champ d'application des métriques, exécutez la commande gcloud beta monitoring metrics-scopes create:

gcloud beta monitoring metrics-scopes create MONITORED_RESOURCE_CONTAINER_NAME --project=SCOPING_PROJECT_ID_OR_NUMBER

Avant d'exécuter la commande précédente, procédez comme suit:

Saisissez le nom ou l'ID du projet Google Cloud dont le champ d'application des métriques doit être modifié dans la variable SCOPING_PROJECT_ID_OR_NUMBER.
Saisissez l'identifiant de votre conteneur de ressources dans la variable MONITORED_RESOURCE_CONTAINER_NAME. Lorsque le conteneur de ressources est un projet Google Cloud, saisissez projects/PROJECT_ID_OR_NUMBER.

Par exemple, la commande suivante ajoute le projet my-monitored-project au champ d'application des métriques du projet nommé my-staging-projects:

gcloud beta monitoring metrics-scopes create projects/my-monitored-project --project=my-staging-projects

La réponse à la commande précédente confirme que la commande a bien été exécutée:

Created monitored project [locations/global/metricsScopes/my-staging-projects/projects/my-monitored-project].

curl

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 appelant 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 signifie que l'opération est en cours. Pour en savoir plus, consultez la page Commandes d'API asynchrones.

Voici un exemple de réponse lorsque le projet surveillé est ajouté:

{
  "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 entraîne une entrée dans les journaux d'audit du projet de champ d'application. La console Google Cloud n'appelle pas cette méthode API. Par conséquent, les modifications apportées à un champ d'application des métriques lors de l'utilisation de la console Google Cloud ne sont pas enregistrées dans les journaux d'audit.

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

gcloud

Pour supprimer un conteneur de ressources, tel qu'un projet Google Cloud, d'un champ d'application des métriques, exécutez la commande gcloud beta monitoring metrics-scopes delete:

gcloud beta monitoring metrics-scopes delete MONITORED_RESOURCE_CONTAINER_NAME --project=SCOPING_PROJECT_ID_OR_NUMBER

Avant d'exécuter la commande précédente, procédez comme suit:

Saisissez le nom ou l'ID du projet Google Cloud dont le champ d'application des métriques doit être modifié dans la variable SCOPING_PROJECT_ID_OR_NUMBER.
Saisissez l'identifiant de votre conteneur de ressources dans la variable MONITORED_RESOURCE_CONTAINER_NAME. Lorsque le conteneur de ressources est un projet Google Cloud, saisissez projects/PROJECT_ID_OR_NUMBER.

Par exemple, la commande suivante supprime le projet my-monitored-project du champ d'application des métriques du projet nommé my-staging-projects:

gcloud beta monitoring metrics-scopes delete projects/my-monitored-project --project=my-staging-projects

La réponse à la commande précédente confirme que la commande a bien été exécutée:

Deleted monitored project [locations/global/metricsScopes/my-staging-projects/projects/my-monitored-project].

L'erreur suivante est signalée lorsque le projet effectuant une surveillance ne surveille pas le projet spécifié par la variable MONITORED_RESOURCE_CONTAINER_NAME:

NOT_FOUND: Requested entity was not found.

curl

Pour supprimer un projet Google Cloud d'un champ d'application des 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.

Voici un exemple de réponse lorsque la suppression d'un projet surveillé est une réussite:

{
  "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"
  }
}

Méthodes d'API asynchrones

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

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

Lorsque l'état 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 défini, l'opération asynchrone a échoué. La valeur de ce champ est un objet Status qui contient un code d'erreur gRPC et un message d'erreur.
- response: si défini, l'opération asynchrone est terminée 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. Chaque commande curl de cette page comprend un ensemble d'arguments suivi de l'URL d'une ressource d'API:

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

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

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=SCOPING_PROJECT_ID_OR_NUMBER
```
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 de projet surveillé :
```
MONITORED_PROJECT_ID_OR_NUMBER=MONITORED_PROJECT_ID_OR_NUMBER
```
Authentifiez-vous sur Google Cloud CLI :
```
gcloud auth login
```
Facultatif. Pour éviter de devoir spécifier votre ID de projet dans chaque commande gcloud, définissez votre ID de projet comme ID par défaut à l'aide de gcloud CLI:
```
gcloud config set project ${SCOPING_PROJECT_ID_OR_NUMBER}
```
Créez un jeton d'autorisation et placez-le dans une variable d'environnement.
```
TOKEN=`gcloud auth print-access-token`
```
Les jetons sont valides pendant une durée limitée. Si des commandes auparavant fonctionnelles indiquent soudainement que vous n'êtes pas authentifié, exécutez à nouveau cette commande.
Pour vérifier que vous disposez bien d'un jeton d'accès, renvoyez la variable TOKEN :
```
echo ${TOKEN}
ya29.GluiBj8o....
```

Vous devrez peut-être également spécifier d'autres arguments, par exemple pour préciser le type de la requête HTTP (par exemple, -X DELETE). La requête par défaut étant GET, elle n'est pas spécifiée dans les exemples.

Étapes suivantes

Pour en savoir plus sur l'utilisation de Google Cloud avec Terraform, consultez les ressources suivantes :

Configurer un champ d'application des métriques à l'aide de l'API

Avant de commencer

Répertorier tous les champs d'application des métriques incluant un projet

gcloud

curl

Obtenir des détails sur un champ d'application de métriques

gcloud

curl

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

gcloud

curl

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

gcloud

curl

Méthodes d'API asynchrones

Configuration de la commande curl

Étapes suivantes

Configuration de la commande `curl`