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 que você usa 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.

Observe que 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 recomendadores.

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á o seguinte:

[
  {
    "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á o seguinte:

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