Estadísticas de uso de la API

En esta página, se explica cómo ver y administrar las estadísticas en el recomendador mediante los comandos de gcloud o la API de REST.

La siguiente es una interacción de estadística típica con la API de Recomendador:

  • Estadísticas de lista disponibles actualmente para un tipo de estadística específico.
  • Marca como aceptada una estadística con la que quieras realizar acciones.

Para obtener información sobre cómo cambiar el estado de las estadísticas en la consola de Google Cloud, consulta la documentación del Centro de recomendaciones o el tipo de estadística correspondiente.

Configura el proyecto predeterminado

Configura el proyecto predeterminado si aún no lo hiciste:

gcloud config set project PROJECT_ID

En el ejemplo anterior, PROJECT_ID es el ID de tu proyecto.

Configure las variables de entorno

Configura las variables de entorno para las interacciones del Recomendador:

PROJECT=TARGET_PROJECT_ID
LOCATION=LOCATION_ID
INSIGHT_TYPE=INSIGHT_TYPE_ID

Donde:

  • TARGET_PROJECT_ID es el proyecto cuyas estadística deseas enumerar. Este puede ser un proyecto diferente del actual.

    • Para los comandos de gcloud, debes usar el ID del proyecto
    • Para las solicitudes a la API, puedes usar el número o el ID del proyecto. Se recomienda usar el número del proyecto.

    El número de proyecto se muestra en las respuestas de la API y los comandos de gcloud.

  • LOCATION_ID es la ubicación de Google Cloud en la que se encuentran los recursos asociados con las estadísticas (por ejemplo, global o us-central1-a).

  • INSIGHT_TYPE_ID es el ID de tipo de estadística completamente calificado (por ejemplo, google.iam.policy.Insight).

Consulta Tipos de estadísticas para obtener una tabla de vínculos a información sobre cada tipo de estadística, incluidas las ubicaciones admitidas y los ID de tipos de estadísticas.

Configurar permisos

Debes tener permisos para acceder a las estadísticas del proyecto de destino.

  • Para solicitantes que incluyen un proyecto de facturación en su solicitud. El proyecto usado en la solicitud debe estar en regla y el usuario debe tener un rol en el proyecto que contenga el permiso serviceusage.services.use. El rol Consumidor de Service Usage contiene el permiso requerido.
  • Cada tipo de estadística requiere permisos específicos. Consulta Tipos de estadísticas para obtener una tabla de vínculos a información sobre cada tipo de estadística, incluidos los permisos necesarios.

Crea una lista de estadísticas

Para crear una lista de las estadísticas en el proyecto de destino, haz lo siguiente:

gcloud

Ingrese lo siguiente:

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

En el comando anterior, FORMAT es un formato de salida de gcloud compatible (por ejemplo, json).

Por ejemplo:

gcloud recommender insights list \
    --project=example-project \
    --location=global \
    --insight-type=google.iam.policy.Insight \
    --format=json

REST

Ingrese lo siguiente:

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 ejemplo:

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 operación genera las estadísticas actuales de la política de IAM en el proyecto de destino como una lista de entidades Insight en el formato especificado.

El resultado es similar al siguiente:

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

Ten en cuenta que las estadísticas que se muestran incluyen los siguientes campos:

  • Un campo name en el siguiente formato:

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

    En el ejemplo anterior, INSIGHT_ID identifica de forma exclusiva la estadística

  • Un campo etag asociado con el estado actual de la estadística.

Cuando haces referencia a una estadística mediante comandos gcloud posteriores o llamadas a la API de REST, haces referencia al ID de estadística y a la etiqueta ETag, lo que garantiza que cualquier operación se realice solo si la estadística no se modificó desde su última recuperación.

Marca una estadística como aceptada

Puedes marcar una estadística como aceptada para indicar que se tiene la intención de realizar o que se han realizado acciones en un recurso asociado según la información proporcionada en la estadística. Cuando se acepta una estadística, tu nombre de usuario se asigna como la entidad que actúa para la estadística, y el recomendador no actualizará la estadística con contenido más reciente.

Para marcar una estadística como aceptada, haz lo siguiente:

gcloud

Ingresa lo siguiente:

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

Donde:

  • INSIGHT_ID es el ID de una estadística recuperada de una llamada anterior a la lista de estadísticas
  • etag es la etiqueta ETag que representa el estado de las estadísticas
  • STATE_METADATA es un metadato opcional sobre la operación. Especifica los metadatos como una lista separada por comas de pares KEY=VALUE.

Por ejemplo:

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

Ingrese lo siguiente:

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

Donde:

  • INSIGHT_ID es el ID de una estadística recuperada de una llamada anterior a la lista de estadísticas
  • etag es la etiqueta ETag que representa el estado de las estadísticas
  • STATE_METADATA es un campo opcional con metadatos adicionales sobre la operación. Especifica los metadatos como pares key:value.

Por ejemplo:

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 operación muestra la entidad Insight en el formato especificado después de que se realiza la operación.

El resultado es similar al siguiente:

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

Ten en cuenta que el valor del campo state cambió a ACCEPTED.