Esta página se ha traducido con Cloud Translation API.

Usar la API: Recomendaciones

En esta página se explica cómo ver y gestionar recomendaciones en Recommender mediante comandos gcloud o la API REST.

Una interacción típica de recomendación con la API Recommender es la siguiente:

Lista las recomendaciones de un proyecto específico.
Marca como reclamada la recomendación que quieras aplicar o como rechazada la que no quieras aplicar.
Aplica la recomendación mediante gcloudcomandos o llamadas a la API REST específicas del tipo de recurso (por ejemplo, roles de gestión de identidades y accesos o instancias de VM de Compute Engine).
Marca la recomendación como correcta o incorrecta.

Ten en cuenta que solo se puede interactuar con las recomendaciones obtenidas a través de la API mediante la API o BigQuery Export.

Para obtener información sobre cómo cambiar el estado de las recomendaciones en la consola deGoogle Cloud , consulta la documentación de Centro de recomendaciones o del recomendador correspondiente.

Definir el proyecto predeterminado

Si aún no lo has hecho, define el proyecto predeterminado:

gcloud config set project PROJECT_ID

donde PROJECT_ID es el ID de tu proyecto.

Establece variables de entorno:

Define las variables de entorno de las interacciones de Recommender:

PROJECT=TARGET_PROJECT_ID
LOCATION=LOCATION_ID
RECOMMENDER=RECOMMENDER_ID

donde:

TARGET_PROJECT_ID es el proyecto cuyas recomendaciones quieres enumerar. Puede ser un proyecto diferente al actual.
- Para los comandos de gcloud, debes usar el ID de proyecto.
- En las solicitudes a la API, puedes usar el número o el ID del proyecto. Se recomienda indicar el número de proyecto.
El número de proyecto se devuelve en las respuestas de la API y de los comandos gcloud.
LOCATION_ID es la Google Cloud ubicación en la que se encuentran los recursos asociados a las recomendaciones (por ejemplo, global o us-central1-a).
RECOMMENDER_ID es el ID del recomendador completo (por ejemplo, google.compute.instance.MachineTypeRecommender).

Consulta la sección Recomendaciones para ver una tabla con enlaces a información sobre cada recomendación, incluidas las ubicaciones admitidas y los IDs de las recomendaciones.

Definir permisos

Debes tener permisos para acceder a las recomendaciones del proyecto de destino.

Para los solicitantes que incluyan un proyecto de facturación en su solicitud. El proyecto utilizado en la solicitud debe estar en buen estado y el usuario debe tener un rol en el proyecto que contenga el permiso serviceusage.services.use. El rol Consumidor de uso de servicios contiene el permiso necesario.
Cada recomendador requiere permisos específicos. Consulta la sección Recomendadores para ver una tabla con enlaces a información sobre cada recomendador, incluidos los permisos necesarios.

Mostrar recomendaciones

Como se muestra en la pestaña gcloud Beta, puedes enumerar todas las recomendaciones de tu proyecto sin tener que especificar una ubicación ni un recomendador. Esta función está en versión preliminar.

La función de GA requiere que especifiques un proyecto, una ubicación y un recomendador. Para obtener más información, consulta la pestaña gcloud.

gcloud Beta

Introduce lo siguiente:

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

donde FORMAT es un gcloud formato de salida admitido, como json.

Por ejemplo:

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

gcloud

Introduce lo siguiente:

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

donde FORMAT es un gcloud formato de salida admitido (por ejemplo, json).

Por ejemplo:

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

REST

Introduce 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 de tamaño de la instancia de VM actual en el proyecto de destino como una lista de entidades Recommendation en el formato especificado.

El resultado debería ser 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 devueltas incluyen los siguientes campos:

Un campo name con el siguiente formato:
```
projects/PROJECT_ID/locations/LOCATION/recommenders/RECOMMENDER_ID/recommendations/RECOMMENDATION_ID
```
donde RECOMMENDATION_ID identifica de forma única la recomendación.
Un campo etag asociado al estado de la recomendación actual.

Cuando haces referencia a una recomendación mediante comandos Google Cloud CLI o llamadas a la API REST posteriores, haces referencia tanto al ID de la recomendación como al etag, lo que asegura que las operaciones solo se realicen si la recomendación no se ha modificado desde la última vez que la recuperaste.

Marcar una recomendación como reclamada o rechazada

Puede marcar una recomendación como reclamada para indicar que tiene intención de aplicar los cambios recomendados al recurso asociado. Cuando se reclama una recomendación, tu nombre de usuario se asigna como el actor de la recomendación y Recommender no actualiza la recomendación con contenido más reciente.

Puedes marcar una recomendación como rechazada para indicar que no tienes intención de aplicar los cambios recomendados al recurso asociado o que no quieres seguir viendo la recomendación. Cuando se rechaza una recomendación, deja de aparecer como recomendación ACTIVA. Recommender puede seguir actualizando la recomendación con contenido más reciente.

Para marcar una recomendación como reclamada o rechazada, sigue estos pasos:

gcloud

Introduce lo siguiente:

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

Donde:

STATE_CHANGE es el estado que quiere asignar a una recomendación. Los valores válidos son los siguientes:
- mark-claimed para marcar la recomendación como reclamada.
- mark-dismissed para marcar la recomendación como rechazada.
RECOMMENDATION_ID es el ID de una recomendación que has obtenido de una llamada anterior para enumerar recomendaciones.
etag es el etag devuelto que representa el estado de la recomendación.
STATE_METADATA son metadatos opcionales 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, completada 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

Introduce 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 quiere asignar a una recomendación. Los valores válidos son los siguientes:
- mark-claimed para marcar la recomendación como reclamada.
- mark-dismissed para marcar la recomendación como rechazada.
RECOMMENDATION_ID es el ID de una recomendación que has obtenido de una llamada anterior para enumerar recomendaciones.
etag es el etag devuelto que representa el estado de la 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, completada 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 devuelve la entidad Recommendation en el formato especificado una vez que se ha llevado a cabo.

El resultado debería ser 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 ha cambiado a CLAIMED.

Aplicar recomendaciones

Una vez que hayas marcado una recomendación como reclamada, podrás aplicarla mediante comandos de gcloud o llamadas a la API REST específicos 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 instancias de VM, puedes usar los comandos de gcloud Compute Engine o las llamadas a la API REST de Compute Engine.

Cuando realizas estas operaciones, identificas el recurso de destino mediante el valor del campo resource de la matriz OperationsGroup de la entidad Recommendation devuelta. Este campo tiene el siguiente formato:

//API_NAME/RESOURCE_PATH

Por ejemplo:

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

Cambiar el estado de una recomendación

Una vez que haya aplicado una recomendación, puede marcarla como completada o fallida.

Para marcar una recomendación como completada, sigue estos pasos:

gcloud

Introduce 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

Dónde

STATE_CHANGE es el cambio que quieres hacer en una recomendación. Los valores válidos son los siguientes:
- mark-succeeded para marcar la recomendación como completada.
- mark-failed para marcar la recomendación como fallida.
STATE_METADATA son metadatos opcionales sobre la operación. Especifica los metadatos como una lista de pares KEY=VALUE separados por comas. Esta opción está disponible cuando marcas una recomendación como reclamada, completada 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

Introduce 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 has obtenido de una llamada anterior para enumerar recomendaciones.
STATE_CHANGE es el cambio que quieres hacer en una recomendación. Los valores válidos son los siguientes:
- markSucceeded para marcar la recomendación como completada.
- markFailed para marcar la recomendación como fallida.
etag es el etag devuelto que representa el estado de la 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, completada 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 devuelve la entidad Recommendation en el formato especificado una vez que se ha llevado a cabo.

El resultado debería ser 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 ha cambiado a SUCCEEDED.