Usar a API: recomendações

Esta página explica como visualizar e gerenciar recomendações no Recommender usando comandos gcloud ou a API REST.

Uma interação de recomendação típica com a API Recommender é:

  1. Liste as recomendações para um projeto específico.

  2. Marque uma recomendação que você pretende aplicar como claimed ou que não pretende aplicar como dismissed.

  3. Aplique a recomendação. Isso pode ser feito automaticamente usando o Active Assist no console Google Cloud ou manualmente usando os comandos da Google Cloud CLI, chamadas da API REST ou outras ferramentas.

    Quando você aplica a recomendação manualmente, os comandos ou as chamadas usados são específicos do tipo de recurso. Por exemplo, para mudar o tamanho de uma instância de VM em resposta a uma recomendação do recomendador de dimensionamento de instâncias de VM, use os comandos gcloud do Compute Engine ou chamadas para a API REST do Compute Engine.

    Ao executar essas operações, você identifica o recurso de destino usando o valor do campo resource na matriz OperationsGroup na entidade Recommendation retornada. Esse campo está no seguinte formato:

    //API_NAME/RESOURCE_PATH

    Exemplo:

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

  4. Marque a recomendação como succeeded ou failed.

Somente as recomendações recuperadas por meio da API podem ser usadas para interagir por meio dela ou do BigQuery Export.

Para informações sobre como mudar o estado das recomendações no console doGoogle Cloud , consulte a documentação do Active Assist ou do recomendador adequado.

Definir o projeto padrão

Defina o projeto padrão, caso ainda não tenha feito isso:

gcloud config set project PROJECT_ID

onde PROJECT_ID é o código de seu projeto.

Definir as variáveis de ambiente

Defina variáveis de ambiente para interações do Recommender:

PROJECT=TARGET_PROJECT_ID
LOCATION=LOCATION_ID
RECOMMENDER=RECOMMENDER_ID

em que:

  • TARGET_PROJECT_ID é o projeto cujas recomendações você quer listar. Pode ser um projeto diferente do atual.

    • Para comandos gcloud, use o código do projeto
    • Para solicitações de API, você pode usar o número ou o ID do projeto. O número do projeto é recomendado.

    O número do projeto é retornado nas respostas dos comandos de API e gcloud.

  • LOCATION_ID é o Google Cloud local em que os recursos associados às recomendações estão localizados (por exemplo, global ou us-central1-a).

  • RECOMMENDER_ID é o ID de recomendação totalmente qualificado (por exemplo, google.compute.instance.MachineTypeRecommender).

Consulte Recomendadores para ver uma tabela de links com informações sobre cada recomendador, incluindo locais compatíveis e códigos de recomendação.

Definir permissões

Você precisa ter permissões para acessar as recomendações no projeto de destino.

  • Solicitantes que incluem um projeto de faturamento na solicitação. O projeto usado na solicitação precisa estar em situação regular, e o usuário precisa ter um papel no projeto que contenha a permissão serviceusage.services.use. O papel Consumidor do Service Usage tem a permissão necessária.
  • Cada recomendador requer permissões específicas. Consulte Recomendadores para ver uma tabela de links com informações sobre cada recomendador, incluindo as permissões necessárias.

Listar recomendações

Conforme mostrado na guia gcloud Beta, é possível listar todas as recomendações do seu projeto sem precisar especificar um local e um recomendador. Esse recurso está em pré-lançamento.

Para usar o recurso de GA, é preciso especificar um projeto, um local e um recomendador. Para mais detalhes, consulte a guia gcloud.

gcloud Beta

Digite o seguinte:

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

em que FORMAT é um formato de saída compatível com gcloud, como json.

Por exemplo:

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

gcloud

Digite o seguinte:

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

em que FORMAT é um formato de saída gcloud compatível (por exemplo, json).

Por exemplo:

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

REST

Digite o seguinte:

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"

Exemplo:

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"

Essa operação gera as recomendações atuais de dimensionamento de instâncias de VM no projeto de destino como uma lista de entidades Recommendation no formato especificado.

O resultado será assim:

[
  {
    "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"
  }
]

Observe que as recomendações retornadas incluem os seguintes campos:

  • Um campo name no seguinte formato:

    projects/PROJECT_ID/locations/LOCATION/recommenders/RECOMMENDER_ID/recommendations/RECOMMENDATION_ID

    em que RECOMMENDATION_ID identifica exclusivamente a recomendação

  • Um campo etag associado ao estado de recomendação atual.

Quando você faz referência a uma recomendação usando comandos Google Cloud CLI ou chamadas de API REST subsequentes, faz referência ao código da recomendação e à etag, o que garante que qualquer operação seja realizada somente se a recomendação não tiver sido modificada desde a última vez em que foi recuperada.

Mudar o estado de uma recomendação

Você pode marcar uma recomendação como reivindicada para indicar que pretende aplicar as alterações recomendadas ao recurso associado. Quando uma recomendação é reivindicada, seu nome de usuário é atribuído como o ator da recomendação, e o Recomendador não atualiza a recomendação com o conteúdo mais recente.

É possível marcar uma recomendação como dispensada para indicar que você não pretende aplicar as mudanças recomendadas ao recurso associado ou que não quer continuar vendo a recomendação. Quando uma recomendação é dispensada, ela não aparece mais como ATIVA. O recomendador pode continuar atualizando a recomendação com conteúdo mais recente.

Depois de aplicar uma recomendação, você poderá marcá-la como concluída ou com falha.

Para mudar o estado de uma recomendação, siga estas etapas:

gcloud

Digite o seguinte:

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

Onde

  • STATE_CHANGE é a alteração que você quer fazer em uma recomendação. Os valores válidos são:
    • mark-claimed para marcar a recomendação como declarada.
    • mark-dismissed para marcar a recomendação como dispensada.
    • mark-succeeded para marcar a recomendação como bem-sucedida.
    • mark-failed para marcar a recomendação como reprovada.
  • RECOMMENDATION_ID é o ID de uma recomendação que você recuperou de uma chamada anterior para listar recomendações.
  • ETAG é a etag retornada que representa o estado da recomendação.
  • STATE_METADATA são metadados opcionais sobre a operação. Especifique os metadados como uma lista separada por vírgulas de pares KEY=VALUE. Essa opção está disponível quando você marca uma recomendação como reivindicada, bem-sucedida ou com falha.

Por exemplo:

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

Digite o seguinte

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

em que:

  • RECOMMENDATION_ID é o ID de uma recomendação que você recuperou de uma chamada anterior para listar recomendações.
  • STATE_CHANGE é a alteração que você quer fazer em uma recomendação. Os valores válidos são:
    • markClaimed para marcar a recomendação como declarada.
    • markDismissed para marcar a recomendação como dispensada.
    • markSucceeded para marcar a recomendação como bem-sucedida.
    • markFailed para marcar a recomendação como reprovada.
  • ETAG é a etag retornada que representa o estado da recomendação.
  • STATE_METADATA é um campo opcional com metadados adicionais sobre a operação. Especifique os metadados como pares de key:value. Esse campo está disponível quando você marca uma recomendação como reivindicada, bem-sucedida ou falha.

Exemplo:

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

Essa operação retorna a entidade Recommendation no formato especificado depois que a operação ocorreu.

O resultado será assim:

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

Observe que o valor do campo state foi alterado para SUCCEEDED.