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 commedismissed
.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 tableauOperationsGroup
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
oufailed
.
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é.
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.- Pour les commandes
LOCATION_ID correspond à l'emplacement Google Cloudoù se trouvent les ressources associées aux recommandations (par exemple,
global
ouus-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
.