Use a API – Estatísticas

Esta página explica como ver e gerir estatísticas no Recommender através de comandos gcloudou da API REST.

Nota: alguns recomendadores não suportam a utilização da API REST nem da CLI gcloud para ver e gerir recomendações e estatísticas. Para ver detalhes sobre os sistemas de recomendação e os clientes suportados, consulte o artigo Sistemas de recomendação.

Uma interação típica com estatísticas da API Recommender é:

• Liste as estatísticas de um projeto específico
• Marque uma estatística sobre a qual pretende tomar medidas como aceite

Para obter informações sobre como alterar o estado das estatísticas na Google Cloud consola, consulte a documentação do centro de recomendações ou do tipo de estatísticas 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
INSIGHT_TYPE=INSIGHT_TYPE_ID

where:

• TARGET_PROJECT_ID é o projeto cujas estatísticas 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 estatísticas (por exemplo, global ou us-central1-a).

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

Consulte o artigo Tipos de estatísticas para ver uma tabela de links para informações sobre cada tipo de estatísticas, incluindo localizações suportadas e IDs de tipos de estatísticas.

Defina autorizações

Tem de ter autorizações para aceder às estatísticas 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 tipo de estatística requer autorizações específicas. Consulte Tipos de estatísticas para ver uma tabela de links para informações sobre cada tipo de estatísticas, incluindo as autorizações necessárias.

Nota: se usar o cabeçalho x-goog-user-project ou o parâmetro da string de consulta no seu pedido, tem de ter autorização serviceusage.services.use para o ID do projeto que especificar, além das autorizações de IAM normais necessárias para fazer o pedido.

userProject

Apresente estatísticas

Conforme mostrado no separador gcloud Beta, pode listar todas as estatísticas 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

Pré-visualização

Esta funcionalidade está sujeita aos "Termos das Ofertas de Pré-DG" na secção Termos Gerais de Serviço dos Termos Específicos do Serviço. As funcionalidades de pré-DG estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

Introduza os seguintes dados:

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

onde FORMAT é um Google Cloud CLI formato de saída suportado, como json.

Por exemplo:

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

Nota: ao contrário do resultado seguinte para os separadores gcloud e REST, que se limita a estatísticas de uma localização e um recomendador, o resultado inclui todas as estatísticas do projeto.

gcloud

Introduza os seguintes dados:

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

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

Por exemplo:

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

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

Esta operação gera as estatísticas da política de IAM atual no projeto de destino como uma lista de entidades Insight no formato especificado.

O resultado é semelhante ao seguinte:

[
  {
    "category": "SECURITY",
    "content": {
      "condition": {
        "description": "",
        "expression": "",
        "location": "",
        "title": ""
      },
      "exercisedPermissions": [],
      "inferredPermissions": [],
      "member": "user:[e-mail]",
      "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"
    ],
  }
]

Tenha em atenção que as estatísticas devolvidas 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 de forma exclusiva a estatística

• Um campo etag associado ao estado atual das estatísticas.

Quando faz referência a uma estatística com comandos gcloud subsequentes ou chamadas API REST, faz referência ao ID da estatística e ao etag, o que garante que as operações só são realizadas se a estatística não tiver sido modificada desde a última vez que a obteve.

Marque uma estatística como aceite

Pode marcar uma estatística como aceite para indicar que pretende tomar ou tomou uma ação num recurso associado com base nas informações fornecidas na estatística. Quando uma estatística é aceite, o seu nome de utilizador é atribuído como o autor da estatística, e o Recomendador não atualiza a estatística com conteúdo mais recente.

Para marcar uma estatística como aceite:

gcloud

Introduza os seguintes dados:

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

where:

• INSIGHT_ID é o ID de uma estatística obtida a partir de uma chamada anterior para listar estatísticas
• etag é a etag devolvida que representa o estado da estatística
• STATE_METADATA são metadados opcionais sobre a operação. Especifique os metadados como uma lista separada por vírgulas de pares KEY=VALUE.

Por 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

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}/insightTypes/${INSIGHT_TYPE}/insights/INSIGHT_ID:markAccepted \
<< EOM
{
  "etag": "etag",
  "stateMetadata": STATE_METADATA
}
EOM

where:

• INSIGHT_ID é o ID de uma estatística obtida a partir de uma chamada anterior para listar estatísticas
• etag é a etag devolvida que representa o estado da estatística
• STATE_METADATA é um campo opcional com metadados adicionais acerca da operação. Especifique os metadados como pares key:value.

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

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

O resultado é semelhante ao seguinte:

{
  "category": "SECURITY",
  "content": { ...  },
  "description": "0 permission checks were authorized by this policy binding tuple.",
  "etag": "\"356ae51165729f38\"",
  "insightSubtype": "PERMISSIONS_USAGE",
  "lastModifiedUser": "[e-mail]",
  "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"
}

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