Cette page a été traduite par l'API Cloud Translation.

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épertoriez les recommandations pour un projet spécifique.
Marquez une recommandation que vous souhaitez appliquer comme claimed ou une recommandation que vous ne souhaitez pas appliquer comme dismissed.
Appliquez la recommandation. Vous pouvez le faire automatiquement à l'aide d'Active Assist dans la console Google Cloud , ou manuellement à l'aide des commandes Google Cloud CLI, des appels d'API REST ou d'autres outils.

Lorsque vous appliquez manuellement la recommandation, les commandes ou les appels que vous utilisez sont 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
```
Marquez la recommandation comme succeeded ou failed.

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 consoleGoogle Cloud , consultez la documentation d'Active Assist ou de l'outil de recommandation approprié.

Avertissement :

Avant d'appliquer des recommandations dans la console Google Cloud ou d'utiliser l'API, assurez-vous que les impacts sont évalués par un évaluateur de votre organisation. Cet évaluateur doivent avoir les connaissances nécessaires pour évaluer les effets des modifications identifiées dans les recommandations, ainsi que les effets spécifiques à votre infrastructure et à votre entreprise. L'application de recommandations sans évaluation appropriée peut entraîner des modifications inattendues, par exemple des problèmes de performances du système, de fiabilité ou la perte des autorisations requises. Si vous choisissez d'appliquer des recommandations sans procéder à un examen manuel, assurez-vous de configurer un processus de rollback avant d'effectuer toute modification.

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 Cloudoù 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 obtenir un tableau des liens vers des informations sur chaque outil de recommandation, y compris les autorisations requises.

Répertorier les recommandations

Comme indiqué dans l'onglet gcloud Beta, vous pouvez répertorier toutes les recommandations de votre projet sans avoir à spécifier d'emplacement ni d'outil de recommandation. Cette fonctionnalité est disponible en version bêta.

La fonctionnalité en disponibilité générale nécessite la spécification d'un projet, d'un emplacement et d'un outil de recommandation. Pour plus d'informations, consultez l'onglet gcloud.

gcloud Beta

Saisissez ce qui suit :

gcloud beta recommender recommendations list \
    --project=${PROJECT} \
    --format=FORMAT

où FORMAT correspond au format de sortie gcloud accepté, tel que json.

Exemple :

gcloud beta recommender recommendations list \
    --project=example-project \
    --format=json

gcloud

Saisissez ce qui suit :

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

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

Par exemple :

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

REST

Saisissez ce qui suit :

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 Google Cloud CLI 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.

Modifier l'état d'une recommandation

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 n'avez pas l'intention d'appliquer les modifications recommandées à la ressource associée ou que vous ne souhaitez plus voir la recommandation. Lorsqu'une recommandation est ignorée, elle n'apparaît plus comme une recommandation ACTIVE. Il se peut que l'outil de recommandation continue à mettre à jour la recommandation avec du contenu plus récent.

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

Pour modifier l'état d'une recommandation, 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

Lieu

STATE_CHANGE correspond à la modification que vous souhaitez apporter à une recommandation. Les valeurs possibles sont :
- mark-claimed pour marquer la recommandation comme revendiquée.
- mark-dismissed pour marquer la recommandation comme ignorée.
- mark-succeeded pour marquer la recommandation comme ayant réussi.
- mark-failed pour marquer la recommandation comme ayant échoué.
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 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é.

Par 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 :
- markClaimed pour marquer la recommandation comme revendiquée.
- markDismissed pour marquer la recommandation comme ignorée.
- 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.