Como usar a API: insights

Esta página explica como visualizar e gerenciar insights no Recommender usando comandos gcloud ou API REST.

Uma interação de insights típica com a API do Recomendador é:

  • Listar insights disponíveis atualmente para um tipo de insight específico
  • Marque um insight sobre o qual você pretende tomar ações aceitas.

Para saber mais sobre como alterar o estado dos insights no Console do Google Cloud, consulte a documentação do Hub de recomendações ou o tipo de insight apropriado.

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
INSIGHT_TYPE=INSIGHT_TYPE_ID

onde:

  • TARGET_PROJECT_ID é o projeto com os insights que 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 local do Google Cloud em que os recursos associados aos insights estão localizados (por exemplo, global ou us-central1-a).

  • INSIGHT_TYPE_ID é o ID do tipo de insight totalmente qualificado (por exemplo, google.iam.policy.Insight).

Consulte Tipos de insights para ver uma tabela de links com informações sobre cada tipo de insight, incluindo locais compatíveis e códigos de tipo de informação.

Definir permissões

Você precisa ter permissões para acessar insights 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 tipo de insight exige permissões específicas. Consulte Tipos de insights para ver uma tabela de links para informações sobre cada tipo de insight, incluindo as permissões necessárias.

Listar insights

Para listar insights no projeto de destino:

gcloud

Digite o seguinte:

gcloud recommender insights list \
    --project=${PROJECT} \
    --location=${LOCATION} \
    --insight-type=${INSIGHT_TYPE} \
    --format=FORMAT

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

Exemplo:

gcloud recommender insights list \
    --project=example-project \
    --location=global \
    --insight-type=google.iam.policy.Insight \
    --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}/insightTypes/${INSIGHT_TYPE}/insights"

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/insightTypes/google.iam.policy.Insight/insights"

Essa operação gera os insights atuais da política do IAM no projeto de destino como uma lista de entidades Insight no formato especificado.

A resposta será semelhante a:

[
  {
    "category": "SECURITY",
    "content": {
      "condition": {
        "description": "",
        "expression": "",
        "location": "",
        "title": ""
      },
      "exercisedPermissions": [],
      "inferredPermissions": [],
      "member": "user:my-service-account@example-project.iam.gserviceaccount.com",
      "role": "roles/iam.securityReviewer"
    },
    "description": "0 permission checks were authorized by this policy binding tuple.",
    "etag": "\"45f4e2c63f6952e8\"",
    "insightSubtype": "PERMISSIONS_USAGE",
    "lastRefreshTime": "2020-03-06T08:00:00Z",
    "name": "projects/32428390823/locations/global/insightTypes/google.iam.policy.Insight/insights/a523ff7e-ed03-4143-a3a5-5b396b99cba9",
    "observationPeriod": "7776000s",
    "stateInfo": {
      "state": "ACTIVE",
    },
    "targetResources": [
      "//cloudresourcemanager.googleapis.com/projects/32428390823"
    ],
  }
]

Os insights retornados incluem os seguintes campos:

  • Um campo name no seguinte formato:

    projects/PROJECT_ID/locations/LOCATION/insightTypes/INSIGHT_TYPE_ID/insights/INSIGHT_ID

    em que INSIGHT_ID identifica exclusivamente o insight

  • Um campo etag associado ao estado de insight atual.

Ao fazer referência a um insight usando comandos gcloud ou chamadas de API REST subsequentes, faça referência ao ID do insight e à etag, o que garante que todas as operações sejam realizadas somente se o insight não tiver sido modificado desde sua última recuperação.

Marcar um insight como aceito

É possível marcar um insight como aceito para indicar que você pretende realizar ou executar uma ação em um recurso associado com base nas informações fornecidas. Quando um insight é aceito, seu nome de usuário é atribuído como o analista para ele, e o Recomendador não atualiza o insight com conteúdo mais recente.

Para marcar um insight como aceito:

gcloud

Digite o seguinte:

gcloud recommender insights mark-accepted \
    INSIGHT_ID \
    --project=${PROJECT} \
    --location=${LOCATION} \
    --insight-type=${INSIGHT_TYPE} \
    --etag=etag \
    --state-metadata=STATE_METADATA
    --format=FORMAT

onde:

  • INSIGHT_ID é o ID de um insight recuperado de uma chamada anterior para listar insights.
  • etag é a etag retornada que representa o estado do insight;
  • STATE_METADATA é um metadado opcional sobre a operação. Especifique os metadados como uma lista separada por vírgulas de pares KEY=VALUE.

Exemplo:

gcloud recommender insights mark-accepted \
    a523ff7e-ed03-4143-a3a5-5b396b99cba9 \
    --project=example-project \
    --location=global \
    --insight-type=google.iam.policy.Insight \
    --etag='"280b34810bba8a1a"' \
    --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}/insightTypes/${INSIGHT_TYPE}/insights/INSIGHT_ID:markAccepted \
<< EOM
{
  "etag": "etag",
  "stateMetadata": STATE_METADATA
}
EOM

onde:

  • INSIGHT_ID é o ID de um insight recuperado de uma chamada anterior para listar insights.
  • etag é a etag retornada que representa o estado do insight;
  • STATE_METADATA é um campo opcional com metadados adicionais sobre a operação. Especifique os metadados como pares key:value.

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/global/insightTypes/google.iam.policy.Insight/insights/a523ff7e-ed03-4143-a3a5-5b396b99cba9:markAccepted \
<< EOM
{
  "etag": "\"280b34810bba8a1a\""
  "stateMetadata": {
    "priority" : "high",
    "tracking_number": "12345"
  }
}
EOM

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

A resposta será semelhante a:

{
  "category": "SECURITY",
  "content": { ...  },
  "description": "0 permission checks were authorized by this policy binding tuple.",
  "etag": "\"356ae51165729f38\"",
  "insightSubtype": "PERMISSIONS_USAGE",
  "lastModifiedUser": "admin123@example-project.iam.gserviceaccount.com",
  "lastRefreshTime": "2020-03-06T08:00:00Z",
  "name": "projects/32428390823/locations/global/insightTypes/google.iam.policy.Insight/insights/a523ff7e-ed03-4143-a3a5-5b396b99cba9",
  "observationPeriod": "7776000s",
  "stateInfo": {
    "state": "ACCEPTED",
    "stateMetadata": {
      "priority" : "high",
      "tracking_number": "12345"
    }
  },
  "targetResources": [
    "//cloudresourcemanager.googleapis.com/projects/32428390823"
  ],
  "userLastUpdateTime": "2020-03-31T20:57:50.509855Z"
}

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