Recomendaciones de uso de la API

En esta página, se explica cómo ver y administrar recomendaciones en el recomendador con comandos de gcloud o la API de REST.

La siguiente es una interacción de recomendación típica con la API del recomendador:

1. Enumera las recomendaciones para un proyecto específico.

2. Marca una recomendación que deseas aplicar como claimed o marca una recomendación que no deseas aplicar como dismissed.

3. Aplica la recomendación. Puedes hacerlo automáticamente con Active Assist en la consola de Google Cloud o de forma manual con los comandos de Google Cloud CLI, las llamadas a la API de REST o cualquier otra herramienta.

   Cuando aplicas la recomendación de forma manual, los comandos o las llamadas que usas son 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 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, identificas el recurso de destino con el valor del campo resource en el array OperationsGroup en la entidad Recommendation que se muestra. 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

4. Marca la recomendación como succeeded o failed.

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 deGoogle Cloud , consulta la documentación de Active Assist o del recomendador apropiado.

Advertencia:

Antes de aplicar las recomendaciones en la consola de Google Cloud o usar la API, asegúrate de que un revisor de tu organización evalúe los impactos. El revisor debe tener el conocimiento para evaluar los impactos identificados en las recomendaciones, así como de los impactos específicos en tu infraestructura y empresa. La aplicación de recomendaciones sin una evaluación adecuada puede provocar cambios inesperados, como problemas con el rendimiento del sistema, confiabilidad deficiente o la pérdida de permisos obligatorios. Si eliges aplicar recomendaciones sin revisión manual, asegúrate de haber configurado un proceso de reversión antes de realizar cualquier cambio.

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.

• LOCATION_ID es la Google Cloud ubicación en la que se encuentran los recursos asociados con las recomendaciones (por ejemplo, global o us-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 IDs 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.

Nota: Si usas el encabezado x-goog-user-project o el parámetro de cadena de consulta userProject en tu solicitud, debes tener el permiso serviceusage.services.use para el ID del proyecto que especificas, además de los permisos normales de IAM que se necesitan para realizar la solicitud.

Crea una lista de recomendaciones

Como se muestra en la pestaña gcloud beta, puedes enumerar todas las configuraciones sin la necesidad de especificar una ubicación ni un recomendador. Esta función está en vista previa.

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

gcloud Beta

Vista previa

Esta función está sujeta a las “Condiciones de la Oferta de la Fase Previa a la DG” en la sección Condiciones del Servicio Generales de las Condiciones Específicas del Servicio. Las funciones de la fase previa a la DG están disponibles "sin modificaciones" y pueden tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Ingresa 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

Nota: A diferencia del siguiente resultado para las pestañas gcloud y REST que se limita a las recomendaciones para una ubicación y un recomendador, el resultado incluirá todas las recomendaciones del proyecto.

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 a este:

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

Cambia el estado de una recomendación

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 tienes la intención de aplicar los cambios recomendados al recurso asociado o que no quieres seguir viendo la recomendación. Cuando se descarta una recomendación, ya no aparecerá como una recomendación ACTIVA. Es posible que el recomendador siga actualizando la recomendación con contenido más reciente.

Después de aplicar una recomendación, puedes marcarla como exitosa o fallida.

Para cambiar el estado de una recomendación, completa los siguientes pasos:

gcloud

Ingrese 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 cambio que deseas hacer en 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.
  • mark-succeeded para marcar la recomendación como exitosa.
  • mark-failed para marcar la recomendación como con errores.
• 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-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:
  • markClaimed para marcar la recomendación como reclamada.
  • markDismissed para marcar la recomendación como descartada.
  • 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 devuelve la entidad Recommendation en el formato especificado después de que se realiza la operación.

El resultado es similar a este:

{
  "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.