Utiliser l'API – Recommandations

Cette page explique comment afficher et gérer les recommandations dans l'outil de recommandation à l'aide des commandes gcloud ou de l'API REST.

Les interactions types avec une recommandation à l'aide de l'API Recommender sont :

  • Répertorier les recommandations actuellement disponibles pour un outil de recommandation spécifique
  • Marquer une recommandation que vous souhaitez appliquer comme revendiquée ou marquer une recommandation que vous ne souhaitez pas appliquer comme ignorée
  • Appliquer la recommandation à l'aide des commandes gcloud ou des appels d'API REST spécifiques au type de ressource (par exemple, les rôles IAM ou les instances de VM Compute Engine)
  • Marquer la recommandation comme ayant réussi ou échoué

Notez que seules les recommandations récupérées via l'API peuvent interagir avec l'API ou BigQuery Export.

Pour en savoir plus sur la modification de l'état des recommandations dans la console Google Cloud, consultez la documentation du Centre de recommandations ou de l'outil de recommandation approprié.

Définir le projet par défaut

Définissez le projet par défaut si vous ne l'avez pas déjà fait :

gcloud config set project PROJECT_ID

où PROJECT_ID correspond à l'ID de votre projet.

Définir des variables d'environnement

Définissez les variables d'environnement pour les interactions avec l'outil de recommandation :

PROJECT=TARGET_PROJECT_ID
LOCATION=LOCATION_ID
RECOMMENDER=RECOMMENDER_ID

où :

  • TARGET_PROJECT_ID correspond au projet dont vous souhaitez répertorier les recommandations. Il peut s'agir d'un projet différent de votre projet actuel.

    • Pour les commandes gcloud, vous devez utiliser l'ID de projet.
    • Pour les requêtes API, vous pouvez utiliser le numéro ou l'ID du projet. Il est recommandé d'utiliser le numéro de projet.

    Le numéro de projet est renvoyé dans les réponses des commandes gcloud et de l'API.

  • LOCATION_ID correspond à l'emplacement Google Cloud dans lequel se trouvent les ressources associées aux recommandations (par exemple, global ou us-central1-a).

  • RECOMMENDER_ID correspond à l'ID de recommandation complet (par exemple, google.compute.instance.MachineTypeRecommender).

Consultez la page Outils de recommandations pour obtenir un tableau des liens vers des informations sur chaque outil de recommandation, y compris les emplacements et les ID de recommandations compatibles.

Définir des autorisations

Vous devez disposer des autorisations nécessaires pour accéder aux recommandations du projet cible.

  • Pour les demandeurs qui spécifient un projet de facturation dans leur requête : le projet inclus dans la requête doit être en règle, et l'utilisateur doit détenir un rôle contenant l'autorisation serviceusage.services.use pour le projet. Le rôle Consommateur Service Usage comprend l'autorisation requise.
  • Chaque outil de recommandation nécessite des autorisations spécifiques. Consultez la page Outils de recommandations pour consulter un tableau listant des liens vers des informations sur chaque outil de recommandation, y compris les autorisations requises.

Répertorier les recommandations

Pour répertorier les recommandations dans le projet cible, procédez comme suit :

gcloud

Saisissez les chaînes suivantes :

gcloud recommender recommendations list \
    --project=${PROJECT} \
    --location=${LOCATION} \
    --recommender=${RECOMMENDER} \
    --format=FORMAT

où FORMAT correspond au format de sortie gcloud accepté (par exemple, json).

Exemple :

gcloud recommender recommendations list \
    --project=example-project \
    --location=us-central1-a \
    --recommender=google.compute.instance.MachineTypeRecommender \
    --format=json

REST

Saisissez les chaînes suivantes :

curl \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
    -H "x-goog-user-project: ${PROJECT}" \
    "https://recommender.googleapis.com/v1/projects/${PROJECT}/locations/${LOCATION}/recommenders/${RECOMMENDER}/recommendations"

Exemple :

curl \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
    -H "x-goog-user-project: example-project" \
    "https://recommender.googleapis.com/v1/projects/example-project/locations/us-central1-a/recommenders/google.compute.instance.MachineTypeRecommender/recommendations"

Cette opération génère les recommandations de dimensionnement de l'instance de VM actuelle dans le projet cible sous la forme d'une liste d'entités Recommendation au format spécifié.

Le résultat ressemble à ce qui suit :

[
  {
    "content": {
      "operationGroups": [
        {
          "operations": [
            {
              "action": "test",
              "path": "/machineType",
              "resource": "//compute.googleapis.com/projects/example-project/zones/us-central1-a/instances/instance-1",
              "resourceType": "compute.googleapis.com/Instance",
              "valueMatcher": {
                "matchesPattern": ".*zones/us-central1-a/machineTypes/n1-standard-4"
              }
            },
            {
              "action": "replace",
              "path": "/machineType",
              "resource": "//compute.googleapis.com/projects/example-project/zones/us-central1-a/instances/instance-1",
              "resourceType": "compute.googleapis.com/Instance",
              "value": "zones/us-central1-a/machineTypes/custom-2-5120"
            }
          ]
        }
      ]
    },
    "description": "Save cost by changing machine type from n1-standard-4 to custom-2-5120.",
    "etag": "\"280b34810bba8a1a\"",
    "lastRefreshTime": "2019-06-28T06:49:21Z",
    "name": "projects/32428390823/locations/us-central1-a/recommenders/google.compute.instance.MachineTypeRecommender/recommendations/a523ff7e-ed03-4143-a3a5-5b396b99cba9",
    "primaryImpact": { ... },
    "stateInfo": {
      "state": "ACTIVE"
    },
    "recommenderSubtype": "CHANGE_MACHINE_TYPE"
  }
]

Notez que les recommandations renvoyées comprennent les champs suivants :

  • Un champ name au format suivant :

    projects/PROJECT_ID/locations/LOCATION/recommenders/RECOMMENDER_ID/recommendations/RECOMMENDATION_ID

    où RECOMMENDATION_ID identifie de manière unique la recommandation.

  • Un champ etag associé à l'état de recommandation actuel.

Lorsque vous référencez une recommandation à l'aide des commandes gcloud ou des appels d'API REST, vous référencez à la fois l'ID de recommandation et la valeur eTag, qui garantit que toutes les opérations sont effectuées qu'à condition que la recommandation n'ait pas été modifiée depuis sa dernière récupération.

Marquer une recommandation comme revendiquée ou ignorée

Vous pouvez marquer une recommandation comme revendiquée pour indiquer que vous avez l'intention d'appliquer les modifications proposées à la ressource associée. Lorsque vous revendiquez une recommandation, votre nom d'utilisateur est attribué en tant qu'acteur de cette recommandation. Dans ce cas, l'outil de recommandation ne met pas à jour la recommandation avec du contenu plus récent.

Vous pouvez marquer une recommandation comme ignorée pour indiquer que vous ne souhaitez pas appliquer les modifications recommandées à la ressource associée ou que vous ne souhaitez pas continuer à la voir. Lorsqu'une recommandation est ignorée, elle n'apparaît plus comme une recommandation ACTIVE. L'outil de recommandation peut continuer à mettre à jour la recommandation avec du contenu plus récent.

Pour marquer une recommandation comme revendiquée ou ignorée, procédez comme suit :

gcloud

Saisissez ce qui suit :

gcloud recommender recommendations STATE_CHANGE \
    RECOMMENDATION_ID \
    --project=${PROJECT} \
    --location=${LOCATION} \
    --recommender=${RECOMMENDER} \
    --etag=etag \
    --state-metadata=STATE_METADATA
    --format=FORMAT

Où :

  • STATE_CHANGE est l'état que vous souhaitez marquer comme recommandation. Les valeurs possibles sont :
    • mark-claimed pour marquer la recommandation comme revendiquée.
    • mark-dismissed pour marquer la recommandation comme ignorée.
  • RECOMMENDATION_ID correspond à l'ID d'une recommandation que vous avez récupérée à partir d'un appel précédent pour répertorier les recommandations.
  • etag correspond à l'eTag renvoyé qui représente l'état de la recommandation.
  • STATE_METADATA correspond à une métadonnée facultative concernant l'opération. Spécifiez les métadonnées sous forme de liste de paires KEY=VALUE séparées par une virgule. Cette option est disponible lorsque vous marquez une recommandation comme revendiquée, ayant réussi ou échoué.

Exemple :

gcloud recommender recommendations mark-claimed \
    a523ff7e-ed03-4143-a3a5-5b396b99cba9 \
    --project=example-project \
    --location=us-central1-a \
    --recommender=google.compute.instance.MachineTypeRecommender \
    --etag='"280b34810bba8a1a"' \
    --state-metadata=priority=high,tracking_number=12345
    --format=json

REST

Saisissez les chaînes suivantes :

curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
    -H "x-goog-user-project: ${PROJECT}" \
    --data-binary @- \
    https://recommender.googleapis.com/v1/projects/${PROJECT}/locations/${LOCATION}/recommenders/${RECOMMENDER}/recommendations/RECOMMENDATION_ID:STATE_CHANGE \
<< EOM
{
  "etag": "etag",
  "stateMetadata": STATE_METADATA
}
EOM

où :

  • STATE_CHANGE est l'état que vous souhaitez marquer comme recommandation. Les valeurs possibles sont :
    • mark-claimed pour marquer la recommandation comme revendiquée.
    • mark-dismissed pour marquer la recommandation comme ignorée.
  • RECOMMENDATION_ID correspond à l'ID d'une recommandation que vous avez récupérée à partir d'un appel précédent pour répertorier les recommandations.
  • etag correspond à l'ETag renvoyé qui représente l'état de la recommandation.
  • STATE_METADATA est un champ facultatif contenant des métadonnées supplémentaires sur l'opération. Spécifiez les métadonnées sous forme de paires key:value. Ce champ est disponible lorsque vous marquez une recommandation comme revendiquée, ayant réussi ou ayant échoué.

Exemple :

curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
    -H "x-goog-user-project: example-project" \
    --data-binary @- \
    https://recommender.googleapis.com/v1/projects/example-project/locations/us-central1-a/recommenders/google.compute.instance.MachineTypeRecommender/recommendations/8f20d509-83d2-45d2-8152-1b8d5d7d5831:markClaimed \
<< EOM
{
  "etag": "\"280b34810bba8a1a\""
  "stateMetadata": {
    "priority" : "high",
    "tracking_number": "12345"
  }
}
EOM

Cette opération renvoie l'entité Recommendation au format spécifié une fois l'opération terminée.

Le résultat ressemble à ce qui suit :

{
  "content": {
    "operationGroups": [ ... ]
  },
  "description": "Save cost by changing machine type from n1-standard-4 to custom-2-5120.",
  "etag": "\"5e3a63cccf1e0964\"",
  "lastRefreshTime": "2019-06-28T06:49:21Z",
  "name": "projects/32428390823/locations/us-central1-a/recommenders/google.compute.instance.MachineTypeRecommender/recommendations/a523ff7e-ed03-4143-a3a5-5b396b99cba9",
  "primaryImpact": { ... },
  "stateInfo": {
    "state": "CLAIMED"
  }
}

Notez que la valeur du champ state est remplacée par CLAIMED.

Appliquer des recommandations

Après avoir marqué une recommandation comme revendiquée, vous pouvez l'appliquer à l'aide des commandes gcloud ou des appels d'API REST spécifiques au type de ressource.

Par exemple, pour modifier la taille d'une instance de VM en réponse à une recommandation de l'outil de recommandation de dimensionnement d'instance de VM, vous utilisez les commandes gcloud de Compute Engine ou des appels à l'API REST de Compute Engine.

Lorsque vous effectuez ces opérations, vous identifiez la ressource cible à l'aide de la valeur du champ resource du tableau OperationsGroup de l'entité Recommendation renvoyée. Ce champ est au format suivant :

//API_NAME/RESOURCE_PATH

Exemple :

//compute.googleapis.com/projects/example-project/zones/us-central1-a/instances/instance-1"

Modifier l'état d'une recommandation

Après avoir appliqué une recommandation, vous pouvez la marquer comme ayant réussi ou échoué.

Pour marquer une recommandation comme ayant réussi, procédez comme suit :

gcloud

Saisissez les chaînes suivantes :

gcloud recommender recommendations STATE_CHANGE \
    RECOMMENDATION_ID \
    --project=${PROJECT} \
    --location=${LOCATION} \
    --recommender=${RECOMMENDER} \
    --etag=etag \
    --state-metadata=priority=high,tracking_number=12345
    --format=FORMAT

Où :

  • STATE_CHANGE correspond à la modification que vous souhaitez apporter à une recommandation. Les valeurs possibles sont :
    • mark-succeeded pour marquer la recommandation comme ayant réussi.
    • mark-failed pour marquer la recommandation comme ayant échoué.
  • STATE_METADATA correspond aux métadonnées facultatives associées à l'opération. Spécifiez les métadonnées sous forme de liste de paires KEY=VALUE séparées par une virgule. Cette option est disponible lorsque vous marquez une recommandation comme revendiquée, ayant réussi ou échoué.

Exemple :

gcloud recommender recommendations mark-succeeded \
    a523ff7e-ed03-4143-a3a5-5b396b99cba9 \
    --project=example-project \
    --location=us-central1-a \
    --recommender=google.compute.instance.MachineTypeRecommender \
    --etag='"5e3a63cccf1e0964"' \
    --state-metadata=priority=high,tracking_number=12345
    --format=json

REST

Saisissez les chaînes suivantes :

curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
    -H "x-goog-user-project: ${PROJECT}" \
    --data-binary @- \
    https://recommender.googleapis.com/v1/projects/${PROJECT}/locations/${LOCATION}/recommenders/${RECOMMENDER}/recommendations/RECOMMENDATION_ID:STATE_CHANGE \
<< EOM
{
  "etag": "etag"
  "stateMetadata": STATE_METADATA
}
EOM

où :

  • RECOMMENDATION_ID correspond à l'ID d'une recommandation que vous avez récupérée à partir d'un appel précédent pour répertorier les recommandations.
  • STATE_CHANGE correspond à la modification que vous souhaitez apporter à une recommandation. Les valeurs possibles sont :
    • markSucceeded pour marquer la recommandation comme ayant réussi.
    • markFailed pour marquer la recommandation comme ayant échoué.
  • etag correspond à l'eTag renvoyé qui représente l'état de la recommandation.
  • STATE_METADATA est un champ facultatif contenant des métadonnées supplémentaires sur l'opération. Spécifiez les métadonnées sous forme de paires key:value. Ce champ est disponible lorsque vous marquez une recommandation comme revendiquée, ayant réussi ou ayant échoué.

Exemple :

curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
    -H "x-goog-user-project: example-project" \
    --data-binary @- \
    https://recommender.googleapis.com/v1/projects/example-project/locations/us-central1-a/recommenders/google.compute.instance.MachineTypeRecommender/recommendations/8f20d509-83d2-45d2-8152-1b8d5d7d5831:markSucceeded \
<< EOM
{
  "etag": "\"280b34810bba8a1a\""
  "stateMetadata": {
    "priority" : "high",
    "tracking_number": "12345"
  }
}
EOM

Cette opération renvoie l'entité Recommendation au format spécifié une fois l'opération terminée.

Le résultat ressemble à ce qui suit :

{
  "content": {
    "operationGroups": [ ... ]
  },
  "description": "Save cost by changing machine type from n1-standard-4 to custom-2-5120.",
  "etag": "\"5e3a63cccf1e053c\"",
  "lastRefreshTime": "2019-06-28T06:49:21Z",
  "name": "projects/32428390823/locations/us-central1-a/recommenders/google.compute.instance.MachineTypeRecommender/recommendations/a523ff7e-ed03-4143-a3a5-5b396b99cba9",
  "primaryImpact": { ... },
  "stateInfo": {
    "state": "SUCCEEDED",
    "stateMetadata": {
      "priority" : "high",
      "tracking_number": "12345"
    }
  }
}

Notez que la valeur du champ state est remplacée par SUCCEEDED.