Recomendaciones de uso de la API
En esta página, se explica cómo ver y administrar recomendaciones en el recomendador mediante los comandos de gcloud
o la API de REST.
La siguiente es una interacción de recomendación típica con la API del recomendador:
- Por el momento, las recomendaciones de listas están disponibles para un recomendador específico
- Marque una recomendación que pretende aplicar como reclamada, o marque una recomendación que no pretende aplicar como descartada.
- Aplica la recomendación con comandos
gcloud
o llamadas a la API de REST específicas para el tipo de recurso (por ejemplo, funciones de IAM o instancias de VM de Compute Engine). - Marca la recomendación como funcionó o falló
Ten en cuenta que las recomendaciones recuperadas con la API solo pueden interactuar a través de la API o BigQuery Export.
Para obtener información sobre cómo cambiar el estado de las recomendaciones en la consola de Google Cloud, consulta la documentación del Centro de recomendaciones o el recomendador apropiado.
Configura el proyecto predeterminado
Configura el proyecto predeterminado si aún no lo hiciste:
gcloud config set project PROJECT_ID
En el ejemplo anterior, PROJECT_ID es el ID de tu proyecto.
Configure las variables de entorno
Configura las variables de entorno para las interacciones del Recomendador:
PROJECT=TARGET_PROJECT_ID LOCATION=LOCATION_ID RECOMMENDER=RECOMMENDER_ID
Donde:
TARGET_PROJECT_ID es el proyecto cuyas recomendaciones deseas enumerar. Este puede ser un proyecto diferente del actual.
- Para los comandos de
gcloud
, debes usar el ID del proyecto - Para las solicitudes a la API, puedes usar el número o el ID del proyecto. Se recomienda usar el número del proyecto.
El número de proyecto se muestra en las respuestas de la API y los comandos de
gcloud
.- Para los comandos de
LOCATION_ID es la ubicación de Google Cloud en la que se encuentran los recursos asociados con las recomendaciones (por ejemplo,
global
ous-central1-a
).RECOMMENDER_ID es el ID del recomendador completamente calificado (por ejemplo,
google.compute.instance.MachineTypeRecommender
).
Consulta Recomendadores para obtener una tabla de vínculos a información sobre cada recomendador, incluidas las ubicaciones admitidas y los ID de recomendación.
Configurar permisos
Debes tener permisos para acceder a las recomendaciones del proyecto de destino.
- Para solicitantes que incluyen un proyecto de facturación en su solicitud. El proyecto usado en la solicitud debe estar en regla y el usuario debe tener un rol en el proyecto que contenga el permiso
serviceusage.services.use
. El rol Consumidor de Service Usage contiene el permiso requerido. - Cada recomendador requiere permisos específicos. Consulta Recomendadores para obtener una tabla de vínculos a información sobre cada recomendador, incluidos los permisos necesarios.
Enumerar recomendaciones
Para mostrar una lista de las recomendaciones en el proyecto de destino, haz lo siguiente:
gcloud
Ingrese lo siguiente:
gcloud recommender recommendations list \ --project=${PROJECT} \ --location=${LOCATION} \ --recommender=${RECOMMENDER} \ --format=FORMAT
En el comando anterior, FORMAT es un formato de salida de gcloud
compatible (por ejemplo, json
).
Por ejemplo:
gcloud recommender recommendations list \ --project=example-project \ --location=us-central1-a \ --recommender=google.compute.instance.MachineTypeRecommender \ --format=json
REST
Ingrese lo siguiente:
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"
Por ejemplo:
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"
Esta operación genera las recomendaciones actuales sobre el tamaño de las instancias de VM en el proyecto de destino como una lista de entidades Recommendation
en el formato especificado.
El resultado es similar al siguiente:
[ { "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" } ]
Ten en cuenta que las recomendaciones que se muestran incluyen los siguientes campos:
Un campo
name
en el siguiente formato:projects/PROJECT_ID/locations/LOCATION/recommenders/RECOMMENDER_ID/recommendations/RECOMMENDATION_ID
RECOMMENDATION_ID : Identifica de forma única la recomendación
Un campo
etag
asociado con el estado actual de la recomendación.
Cuando haces referencia a una recomendación mediante comandos de gcloud
posteriores o llamadas a la API de REST, haces referencia al ID de recomendación y al ETag, lo que garantiza que cualquier operación se realice solo si la recomendación no se ha se modificó desde su última recuperación.
Marca una recomendación como reclamada o descartada
Puedes marcar una recomendación como reclamada para indicar que tienes la intención de aplicar los cambios recomendados al recurso asociado. Cuando se reclama una recomendación, tu nombre de usuario se asigna como la persona que actúa para la recomendación y el recomendador no actualiza la recomendación con contenido más reciente.
Puedes marcar una recomendación como descartada para indicar que no deseas aplicar los cambios recomendados al recurso asociado o que no deseas seguir viendo la recomendación. Cuando se descarta una recomendación, ya no aparecerá como ACTIVA. El recomendador puede seguir actualizando la recomendación con contenido más reciente.
Para marcar una recomendación como reclamada o descartada, sigue estos pasos:
gcloud
Ingrese el siguiente comando:
gcloud recommender recommendations STATE_CHANGE \ RECOMMENDATION_ID \ --project=${PROJECT} \ --location=${LOCATION} \ --recommender=${RECOMMENDER} \ --etag=etag \ --state-metadata=STATE_METADATA --format=FORMAT
Aquí:
- STATE_CHANGE es el estado que deseas marcar para una recomendación.
Estos son los valores válidos:
mark-claimed
para marcar la recomendación como reclamada.mark-dismissed
para marcar la recomendación como descartada.
- RECOMMENDATION_ID es el ID de una recomendación que recuperaste de una llamada anterior para hacer una lista de recomendaciones.
- etag es la ETag que se muestra que representa el estado de recomendación
- STATE_METADATA es un metadato opcional sobre la operación. Especifica los metadatos como una lista separada por comas de pares KEY=VALUE. Esta opción está disponible cuando marcas una recomendación como reclamada, exitosa o fallida.
Por ejemplo:
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
Ingrese lo siguiente:
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
Donde:
- STATE_CHANGE es el estado que deseas marcar para una recomendación.
Estos son los valores válidos:
mark-claimed
para marcar la recomendación como reclamada.mark-dismissed
para marcar la recomendación como descartada.
- RECOMMENDATION_ID es el ID de una recomendación que recuperaste de una llamada anterior para hacer una lista de recomendaciones.
- etag es la ETag que se muestra que representa el estado de recomendación.
- STATE_METADATA es un campo opcional con metadatos adicionales sobre la operación. Especifica los metadatos como pares
key:value
. Este campo está disponible cuando marcas una recomendación como reclamada, exitosa o fallida.
Por ejemplo:
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
Esta operación muestra la entidad Recommendation
en el formato especificado después de que se realiza la operación.
El resultado es similar al siguiente:
{ "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" } }
Ten en cuenta que el valor del campo state
cambió a CLAIMED
.
Aplica recomendaciones
Una vez que marcaste una recomendación como reclamada, puedes aplicarla mediante los comandos de gcloud
o las llamadas a la API de REST que son específicas del tipo de recurso.
Por ejemplo, para cambiar el tamaño de una instancia de VM en respuesta a una recomendación del recomendador de tamaño de instancia de VM, usa los comandos gcloud
de Compute Engine o las llamadas a la API de REST de Compute Engine
Cuando realizas estas operaciones, puedes identificar el recurso de destino con el valor del campo resource
en el array OperationsGroup
en la entidad Recommendation
que se muestra. Este campo está en el siguiente formato:
//API_NAME/RESOURCE_PATH
Por ejemplo:
//compute.googleapis.com/projects/example-project/zones/us-central1-a/instances/instance-1"
Cambia el estado de una recomendación
Después de aplicar una recomendación, puedes marcarla como exitosa o fallida.
Para marcar una recomendación como exitosa, sigue estos pasos:
gcloud
Ingrese lo siguiente:
gcloud recommender recommendations STATE_CHANGE \ RECOMMENDATION_ID \ --project=${PROJECT} \ --location=${LOCATION} \ --recommender=${RECOMMENDER} \ --etag=etag \ --state-metadata=priority=high,tracking_number=12345 --format=FORMAT
Donde
- STATE_CHANGE es el cambio que deseas hacer en una recomendación.
Estos son los valores válidos:
mark-succeeded
para marcar la recomendación como exitosa.mark-failed
para marcar la recomendación como con errores.
- STATE_METADATA es un metadato opcional sobre la operación. Especifica los metadatos como una lista separada por comas de pares KEY=VALUE. Esta opción está disponible cuando marcas una recomendación como reclamada, exitosa o fallida.
Por ejemplo:
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
Ingrese lo siguiente
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
Donde:
- RECOMMENDATION_ID es el ID de una recomendación que recuperaste de una llamada anterior para hacer una lista de recomendaciones.
- STATE_CHANGE es el cambio que deseas hacer en una recomendación.
Estos son los valores válidos:
markSucceeded
para marcar la recomendación como exitosa.markFailed
para marcar la recomendación como con errores.
- etag es la ETag que se muestra que representa el estado de recomendación
- STATE_METADATA es un campo opcional con metadatos adicionales sobre la operación. Especifica los metadatos como pares
key:value
. Este campo está disponible cuando marcas una recomendación como reclamada, exitosa o fallida.
Por ejemplo:
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
Esta operación muestra la entidad Recommendation
en el formato especificado después de que se realiza la operación.
El resultado es similar al siguiente:
{ "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" } } }
Ten en cuenta que el valor del campo state
cambió a SUCCEEDED
.