Esta página foi traduzida pela API Cloud Translation.

Use a API – Recomendações

Esta página explica como ver e gerir recomendações no Recommender através de gcloud comandos ou da API REST.

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

Listar as recomendações para um projeto específico.
Marque uma recomendação que pretende aplicar como reivindicada ou marque uma recomendação que não pretende aplicar como ignorada.
Aplique a recomendação através de gcloudcomandos ou chamadas da API REST específicos do tipo de recurso (por exemplo, funções IAM ou instâncias de VM do Compute Engine).
Marque a recomendação como bem-sucedida ou com falha.

Tenha em atenção que só é possível interagir com as recomendações obtidas através da API através da API ou do BigQuery Export.

Para obter informações sobre como alterar o estado das recomendações na Google Cloud consola, consulte a documentação do Recommendation Hub ou do recomendador adequado.

Defina o projeto predefinido

Defina o projeto predefinido, caso ainda não o tenha feito:

gcloud config set project PROJECT_ID

onde PROJECT_ID é o ID do seu projeto.

Defina variáveis de ambiente

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

PROJECT=TARGET_PROJECT_ID
LOCATION=LOCATION_ID
RECOMMENDER=RECOMMENDER_ID

where:

TARGET_PROJECT_ID é o projeto cujas recomendações quer listar. Este pode ser um projeto diferente do seu projeto atual.
- Para comandos gcloud, tem de usar o ID do projeto
- Para pedidos de API, pode usar o número do projeto ou o ID do projeto. Recomendamos que indique o número do projeto.
O número do projeto é devolvido nas respostas da API e dos gcloud comandos.
LOCATION_ID é a Google Cloud localização onde se encontram os recursos associados às recomendações (por exemplo, global ou us-central1-a).
RECOMMENDER_ID é o ID do recomendador totalmente qualificado (por exemplo, google.compute.instance.MachineTypeRecommender).

Consulte o artigo Recomendadores para ver uma tabela de links para informações sobre cada recomendador, incluindo localizações suportadas e IDs de recomendadores.

Defina autorizações

Tem de ter autorizações para aceder às recomendações no projeto de destino.

Para requerentes que incluam um projeto de faturação no respetivo pedido. O projeto usado no pedido tem de estar em conformidade, e o utilizador tem de ter uma função no projeto que contenha a autorização serviceusage.services.use. A função Consumidor de utilização de serviços contém a autorização necessária.
Cada recomendador requer autorizações específicas. Consulte Recomendadores para ver uma tabela de links para informações sobre cada recomendador, incluindo as autorizações necessárias.

userProject

Recomendações de listas

Conforme mostrado no separador gcloud Beta, pode listar todas as recomendações do seu projeto sem ter de especificar uma localização e um recomendador. Esta funcionalidade está em pré-visualização.

A funcionalidade de IA generativa requer que especifique um projeto, uma localização e um motor de recomendações. Para ver detalhes, consulte o separador gcloud.

gcloud Beta

Introduza os seguintes dados:

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

onde FORMAT é um gcloud formato de saída suportado, como json.

Por exemplo:

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

gcloud

Introduza os seguintes dados:

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

onde FORMAT é um gcloud formato de saída suportado (por exemplo, json).

Por exemplo:

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

REST

Introduza os seguintes dados:

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

Esta operação produz as recomendações de dimensionamento da instância de VM atual no projeto de destino como uma lista de entidades Recommendation no formato especificado.

O resultado é semelhante ao 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"
  }
]

Tenha em atenção que as recomendações devolvidas 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 atual da recomendação.

Quando faz referência a uma recomendação através de comandos Google Cloud CLI subsequentes ou chamadas à API REST, faz referência ao ID da recomendação e à etag, o que garante que as operações só são realizadas se a recomendação não tiver sido modificada desde a última vez que a recuperou.

Marque uma recomendação como reivindicada ou ignorada

Pode marcar uma recomendação como reivindicada para indicar que pretende aplicar as alterações recomendadas ao recurso associado. Quando uma recomendação é reivindicada, o seu nome de utilizador é atribuído como o autor da recomendação e o Recommender não atualiza a recomendação com conteúdo mais recente.

Pode marcar uma recomendação como ignorada para indicar que não pretende aplicar as alterações recomendadas ao recurso associado ou que não quer continuar a ver a recomendação. Quando uma recomendação é ignorada, deixa de aparecer como uma recomendação ATIVA. O recomendador pode continuar a atualizar a recomendação com conteúdo mais recente.

Para marcar uma recomendação como reivindicada ou ignorada:

gcloud

Introduza os seguintes dados:

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

Onde:

STATE_CHANGE é o estado que quer atribuir a uma recomendação. Os valores válidos são:
- mark-claimed para marcar a recomendação como reivindicada.
- mark-dismissed para marcar a recomendação como ignorada.
RECOMMENDATION_ID é o ID de uma recomendação que obteve de uma chamada anterior para listar recomendações
etag é a etag devolvida 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. Esta opção está disponível quando marca uma recomendação como reivindicada, bem-sucedida ou com falha.

Por exemplo:

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

Introduza os seguintes dados:

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

where:

STATE_CHANGE é o estado que quer atribuir a uma recomendação. Os valores válidos são:
- mark-claimed para marcar a recomendação como reivindicada.
- mark-dismissed para marcar a recomendação como ignorada.
RECOMMENDATION_ID é o ID de uma recomendação que obteve de uma chamada anterior para listar recomendações
etag é a etag devolvida que representa o estado da recomendação
STATE_METADATA é um campo opcional com metadados adicionais acerca da operação. Especifique os metadados como pares key:value. Este campo está disponível quando marca uma recomendação como reivindicada, com êxito ou com falha.

Por 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:markClaimed \
<< EOM
{
  "etag": "\"280b34810bba8a1a\""
  "stateMetadata": {
    "priority" : "high",
    "tracking_number": "12345"
  }
}
EOM

Esta operação devolve a entidade Recommendation no formato especificado após a operação.

O resultado é semelhante ao seguinte:

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

Tenha em atenção que o valor do campo state foi alterado para CLAIMED.

A aplicar recomendações

Depois de marcar uma recomendação como reivindicada, pode aplicá-la através de comandos gcloud ou chamadas da API REST específicos do tipo de recurso.

Por exemplo, para alterar o tamanho de uma instância de VM em resposta a uma recomendação do recomendador de dimensionamento de instâncias de VM, usa os gcloudcomandos do Compute Engine ou as chamadas à API REST do Compute Engine.

Quando realiza estas operações, identifica o recurso de destino através do valor do campo resource na matriz OperationsGroup na entidade Recommendation devolvida. Este campo está no seguinte formato:

//API_NAME/RESOURCE_PATH

Por exemplo:

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

Alterar o estado de uma recomendação

Depois de aplicar uma recomendação, pode marcá-la como bem-sucedida ou com falhas.

Para marcar uma recomendação como bem-sucedida:

gcloud

Introduza os seguintes dados:

gcloud recommender recommendations STATE_CHANGE \
    RECOMMENDATION_ID \
    --project=${PROJECT} \
    --location=${LOCATION} \
    --recommender=${RECOMMENDER} \
    --etag=etag \
    --state-metadata=priority=high,tracking_number=12345
    --format=FORMAT

Onde

STATE_CHANGE é a alteração que quer fazer a uma recomendação. Os valores válidos são:
- mark-succeeded para marcar a recomendação como bem-sucedida.
- mark-failed para marcar a recomendação como falhada.
STATE_METADATA são metadados opcionais sobre a operação. Especifique os metadados como uma lista separada por vírgulas de pares KEY=VALUE. Esta opção está disponível quando 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

Introduza 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

where:

RECOMMENDATION_ID é o ID de uma recomendação que obteve de uma chamada anterior para listar recomendações
STATE_CHANGE é a alteração que quer fazer a uma recomendação. Os valores válidos são:
- markSucceeded para marcar a recomendação como bem-sucedida.
- markFailed para marcar a recomendação como falhada.
etag é a etag devolvida que representa o estado da recomendação
STATE_METADATA é um campo opcional com metadados adicionais acerca da operação. Especifique os metadados como pares key:value. Este campo está disponível quando marca uma recomendação como reivindicada, com êxito ou com falha.

Por 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

Esta operação devolve a entidade Recommendation no formato especificado após a operação.

O resultado é semelhante ao 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"
    }
  }
}

Tenha em atenção que o valor do campo state foi alterado para SUCCEEDED.