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 :

Pour en savoir plus sur la modification de l'état des recommandations dans Google Cloud Console, 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

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. Ces autorisations varient en fonction des recommandations. Consultez la page Outils de recommandations pour obtenir un tableau 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

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

    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

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.

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

gcloud

Saisissez les chaînes suivantes :

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

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.
  • 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:markClaimed \
<< 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.
  • 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.
  • 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é.

Les valeurs possibles sont les suivantes :

  • mark-succeeded pour marquer la recommandation comme ayant réussi.
  • mark-failed pour marquer la recommandation comme ayant é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:markSucceeded \
<< 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.