Exportar a BigQuery

En este tema, se muestra cómo exportar los metadatos de activo de tu organización, carpeta o proyecto a una tabla de BigQuery y, luego, ejecutar un análisis de datos en tu inventario. BigQuery brinda una experiencia similar a SQL para que los usuarios analicen datos y generen estadísticas significativas sin usar secuencias de comandos personalizadas.

Antes de comenzar

Antes de comenzar, completa los pasos que se indican a continuación.

  1. Habilita la API de Cloud Asset Inventory en el proyecto en el que ejecutarás los comandos de la API.
    Habilita la API de Cloud Asset Inventory

  2. Configura los permisos necesarios para llamar a la API de Cloud Asset Inventory con la CLI de gcloud o la API.

  3. Completa los siguientes pasos para configurar el entorno.

    gcloud

    Para configurar tu entorno de modo que use la CLI de gcloud para llamar a la API de Cloud Asset Inventory, instala la CLI de Google Cloud en tu cliente local.

    API

    Para configurar tu entorno a fin de llamar a la API de Cloud Asset Inventory con el comando curl de Unix, completa los siguientes pasos.

    1. Instala oauth2l en tu máquina local para que puedas interactuar con el sistema Google OAuth.
    2. Confirma que tienes acceso al comando curl de Unix.
    3. Asegúrate de otorgar a tu cuenta una de las siguientes funciones en tu proyecto, organización o carpeta.

      • Función de visualizador de Cloud Asset (roles/cloudasset.viewer)
      • Función básica de propietario (roles/owner)

    Ten en cuenta que la CLI de gcloud usa el proyecto de facturación como proyecto del consumidor. Si recibes un mensaje de permiso denegado, puedes verificar si el proyecto de facturación es diferente del proyecto principal:

    gcloud config list
    

    Para configurar el proyecto de facturación en el proyecto de consumidor, haz lo siguiente:

    gcloud config set billing/quota_project CONSUMER_PROJECT_NUMBER
    
  4. Si exportas a un conjunto de datos de BigQuery en un proyecto que no tiene habilitada la API de Cloud Asset Inventory, también debes otorgar las siguientes funciones a la cuenta de servicio service-${CONSUMER_PROJECT_NUMBER}@gcp-sa-cloudasset.iam.gserviceaccount.com en el proyecto de destino.

    • Función de editor de datos de BigQuery (roles/bigquery.dataEditor)
    • Función del usuario de BigQuery (roles/bigquery.user)

    La cuenta de servicio se creará llamando a la API una vez, o puedes usar los siguientes comandos para crear la cuenta de servicio y otorgar la función de agente de servicio de forma manual:

      gcloud beta services identity create --service=cloudasset.googleapis.com --project=PROJECT_ID
      gcloud projects add-iam-policy-binding PROJECT_ID --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-cloudasset.iam.gserviceaccount.com --role=roles/cloudasset.serviceAgent
    

  5. Crea un conjunto de datos de BigQuery.

Limitaciones

  • No se admiten las tablas de BigQuery encriptadas con claves personalizadas de Cloud Key Management Service (Cloud KMS).

  • No se admite agregar el resultado de la exportación a una tabla existente, a menos que exportes a una tabla particionada. La tabla de destino debe estar vacía o debes reemplazarla. Para reemplazarlo, usa la marca --output-bigquery-force con la CLI de gcloud o force con la API.

  • Los tipos de recursos de Google Kubernetes Engine (GKE), excepto container.googleapis.com/Cluster y container.googleapis.com/NodePool, no son compatibles cuando se exportan a tablas separadas por tipo de recurso.

Configurar el esquema de BigQuery para la exportación

A cada tabla de BigQuery se define en un esquema que describe los nombres de las columnas, los tipos de datos y otra información. Configurar el tipo de contenido durante la exportación determina el esquema de tu tabla.

  • Recurso o sin especificar: cuando configuras el tipo de contenido como RESOURCE o no lo especificas, y configuras la marca per-asset-type como falsa o no la usas, creas una tabla de BigQuery que tiene el esquema que se muestra en la Figura 1. Resource.data son los metadatos del recurso representados como una string JSON.

    Cuando configuras el tipo de contenido como RESOURCE o no configuras el tipo de contenido y la marca per-asset-type en true, creas tablas separadas por tipo de elemento. El esquema de cada tabla incluye columnas de tipo RECORD mapeadas a los campos anidados en el campo Resource.data de ese tipo de elemento (hasta los 15 niveles anidados que admite BigQuery). Para ver tablas de ejemplo de BigQuery por tipo, consulta projects/export-assets-examples/datasets/structured_export.

  • Política de IAM: Cuando configuras el tipo de contenido como IAM_POLICY en la API de REST o en iam-policy en la CLI de gcloud, creas una tabla de BigQuery que tiene el esquema que se muestra en la Figura 2. iam_policy RECORD está totalmente expandido.

  • Política de la organización: cuando configuras el tipo de contenido como ORG_POLICY en la API de REST o en org-policy en la CLI de gcloud, creas una tabla de BigQuery que tiene el esquema que se muestra en la figura 3.

  • Política de VPCSC: cuando configuras el tipo de contenido en ACCESS_POLICY en la API de REST o en access-policy en la CLI de gcloud, creas una tabla de BigQuery que tiene el esquema que se muestra en la Figura 4.

  • Inventario de instancias de OSConfig: cuando configuras el tipo de contenido como OS_INVENTORY en la API de REST o os-inventory en la CLI de gcloud, creas una tabla de BigQuery que tiene el esquema que se muestra en la Figura 5.

Exportar una instantánea de activo

Para exportar una instantánea del activo en una marca de tiempo determinada, completa los siguientes pasos.

gcloud

Para exportar activos en un proyecto, ejecuta el siguiente comando. Este comando almacena la instantánea exportada en una tabla de BigQuery en BIGQUERY_TABLE.

  gcloud asset export \
     --content-type CONTENT_TYPE \
     --project 'PROJECT_ID' \
     --snapshot-time 'SNAPSHOT_TIME' \
     --bigquery-table 'BIGQUERY_TABLE' \
     --output-bigquery-force

Donde:

  • CONTENT_TYPE es el tipo de contenido del activo.
  • PROJECT_ID es el ID del proyecto cuyos metadatos se exportan. Este proyecto puede ser el mismo proyecto desde el que ejecutas la exportación o uno diferente.
  • SNAPSHOT_TIME es el tiempo en el que quieres tomar una instantánea de tus activos (opcional). El valor debe ser la hora actual o una hora en el pasado. De forma predeterminada, se toma una instantánea a la hora actual. Para obtener información sobre los formatos de hora, consulta gcloud topic datetime.
  • BIGQUERY_TABLE es la tabla a la que exportarás los metadatos, en el formato projects/PROJECT_ID/datasets/DATASET_ID/tables/TABLE_NAME.
  • --output-bigquery-force reemplaza la tabla de destino, si existe.

Para exportar los activos de una organización o carpeta, puedes usar una de las siguientes marcas en lugar de --project.

access-policy solo se puede exportar para una --organization.

API

Para exportar los metadatos del activo en su proyecto, ejecuta el siguiente comando. Este comando almacena la instantánea exportada en una tabla de BigQuery llamada TABLE_NAME. Obtén más información sobre el método exportAssets.

gcurl -d '{"contentType":"CONTENT_TYPE", \
  "outputConfig":{ \
    "bigqueryDestination": { \
      "dataset": "projects/PROJECT_ID/datasets/DATASET_ID",\
      "table": "TABLE_NAME", \
      "force": true \
    } \
  }}' \
  https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER:exportAssets

Exporta tablas separadas para cada tipo de recurso

A fin de exportar elementos en un proyecto a fin de separar tablas de BigQuery para cada tipo de recurso, usa la marca --per-asset-type. Cada nombre de tabla es BIGQUERY_TABLE concatenado con _ (guion bajo) y ASSET_TYPE_NAME. Los caracteres no alfanuméricos se reemplazan por _.

Ten en cuenta que los tipos de recursos de GKE, excepto container.googleapis.com/Cluster y container.googleapis.com/NodePool, no son compatibles con este tipo de exportación.

A fin de exportar elementos separados de tablas de BigQuery para cada tipo de recurso, ejecuta el siguiente comando.

gcloud

  gcloud asset export \
     --content-type CONTENT_TYPE \
     --project 'PROJECT_ID' \
     --snapshot-time 'SNAPSHOT_TIME' \
     --bigquery-table 'BIGQUERY_TABLE' \
     --output-bigquery-force \
     --per-asset-type

Donde:

  • CONTENT_TYPE es el tipo de contenido del activo. Este valor también determina el esquema para la exportación.
  • PROJECT_ID es el ID del proyecto cuyos metadatos se exportan. Este proyecto puede ser el mismo proyecto desde el que ejecutas la exportación o uno diferente.
  • SNAPSHOT_TIME es el tiempo en el que quieres tomar una instantánea de tus activos (opcional). El valor debe ser la hora actual o una hora en el pasado. De forma predeterminada, se toma una instantánea a la hora actual. Consulta gcloud topic datetime para obtener más información sobre los formatos de hora válidos.
  • BIGQUERY_TABLE es la tabla a la que exportarás los metadatos, en el formato projects/PROJECT_ID/datasets/DATASET_ID/tables/TABLE_NAME.
  • --output-bigquery-force reemplaza la tabla de destino, si existe.
  • --per-asset-type exporta a varias tablas de BigQuery por tipo de recurso.

API

gcurl -d '{"contentType":"CONTENT_TYPE", \
  "outputConfig":{ \
    "bigqueryDestination": { \
      "dataset": "projects/PROJECT_ID/datasets/DATASET_ID",\
      "table": "TABLE_NAME", \
      "force": true \
      "separateTablesPerAssetType": true \
    } \
  }}' \
  https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER:exportAssets

Obtén más información sobre el método exportAssets.

Si falla la exportación a cualquier tabla, toda la operación de exportación falla y muestra el primer error. Los resultados de las exportaciones anteriores exitosas persisten.

Los siguientes tipos se empaquetan en una string JSON para solucionar el problema de compatibilidad entre JSON3 y tipos de BigQuery.

  • google.protobuf.Timestamp
  • google.protobuf.Duration
  • google.protobuf.FieldMask
  • google.protobuf.ListValue
  • google.protobuf.Value
  • google.protobuf.Struct
  • google.api.*

Exporta a una tabla particionada

Para exportar elementos de un proyecto a tablas particionadas, usa la marca --partition-key. La instantánea exportada se almacena en una tabla de BigQuery en BIGQUERY_TABLE con un nivel de detalle diario y dos columnas de marca de tiempo adicionales, readTime y requestTime, una de las cuales es el parámetro partition-key.

Para exportar elementos de un proyecto a tablas particionadas, ejecuta el siguiente comando.

gcloud

  gcloud asset export \
     --content-type CONTENT_TYPE \
     --project 'PROJECT_ID' \
     --snapshot-time 'SNAPSHOT_TIME' \
     --bigquery-table 'BIGQUERY_TABLE' \
     --partition-key 'PARTITION_KEY' \
     --output-bigquery-force \

Donde:

  • CONTENT_TYPE es el tipo de contenido del activo. Este valor también determina el esquema para la exportación.
  • PROJECT_ID es el ID del proyecto cuyos metadatos se exportaron. Este proyecto puede ser el mismo proyecto desde el que ejecutas la exportación o uno diferente.
  • SNAPSHOT_TIME es el tiempo en el que quieres tomar una instantánea de tus activos (opcional). El valor debe ser la hora actual o una hora en el pasado. De forma predeterminada, se toma una instantánea a la hora actual. Para obtener información sobre los formatos de hora, consulta gcloud topic datetime.
  • BIGQUERY_TABLE es la tabla a la que exportarás los metadatos, en el formato projects/PROJECT_ID/datasets/DATASET_ID/tables/TABLE_NAME.
  • PARTITION_KEY es la columna de clave de partición cuando se exporta a tablas particionadas de BigQuery.
  • --output-bigquery-force reemplaza la tabla de destino, si existe.

API

gcurl -d '{"contentType":"CONTENT_TYPE", \
  "outputConfig":{ \
    "bigqueryDestination": { \
      "dataset": "projects/PROJECT_ID/datasets/DATASET_ID",\
      "table": "TABLE_NAME", \
      "force": true \
      "partitionSpec": {"partitionKey": "PARTITION_KEY"} \
    } \
  }}' \
  https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER:exportAssets

Obtén más información sobre el método exportAssets.

En el caso en que ya exista una tabla de destino, el esquema existente de la tabla se actualizará según sea necesario agregando columnas adicionales. Esta actualización del esquema falla si alguna columna cambia su tipo o modo, como opcional a repetido. Luego, si la marca output-bigquery-force se configura como TRUE, la partición correspondiente se reemplaza por los resultados de la instantánea. Sin embargo, los datos en una o más particiones permanecen intactos. Si no estableces output-bigquery-force o FALSE, agrega los datos a la partición correspondiente.

La operación de exportación falla si falla la actualización del esquema o el intento de agregar datos.

Verifica el estado de una exportación

Para verificar el estado de una exportación, ejecuta los siguientes comandos.

gcloud

Para verificar el estado de la exportación, puedes ejecutar el siguiente comando. Se muestra en la CLI de gcloud después de ejecutar el comando de exportación.

gcloud asset operations describe OPERATION_ID

API

Para ver el estado de tu exportación, ejecuta el siguiente comando con el ID de operación que se muestra en la respuesta a tu exportación.

  1. Puedes encontrar el OPERATION_ID en el campo name de la respuesta a la exportación, que tiene el siguiente formato:

    "name": "projects/PROJECT_NUMBER/operations/ExportAssets/CONTENT_TYPE/OPERATION_ID"
    
  2. Para verificar el estado de la exportación, ejecuta el siguiente comando con OPERATION_ID:

    gcurl https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER/operations/ExportAssets/CONTENT_TYPE/OPERATION_ID
    

Visualiza la instantánea de un activo

Para ver la tabla que contiene los metadatos de la instantánea de activos, completa los siguientes pasos.

Console

  1. Ve a la página de BigQuery en Cloud Console.
    Ir a la página de BigQuery

  2. Para mostrar las tablas y vistas en el conjunto de datos, abre el panel de navegación. En la sección Recursos, selecciona tu proyecto para expandirlo y, luego, selecciona un conjunto de datos.

  3. En la lista, selecciona tu tabla.

  4. Selecciona Detalles y anota el valor de Número de filas. Es posible que necesites este valor para controlar el punto de partida de tus resultados mediante la CLI o la API de gcloud.

  5. Para ver una muestra del conjunto de datos, selecciona Vista previa.

API

Para explorar los datos de tu tabla, llama a tabledata.list. En el parámetro tableId, especifica el nombre de tu tabla.

Puedes configurar los siguientes parámetros opcionales para controlar el resultado.

  • maxResults es la cantidad máxima de resultados que se mostrarán.
  • selectedFields es una lista de las columnas separadas por comas que se mostrarán, si no se especifica, se mostrarán todas las columnas.
  • startIndex es el índice basado en cero de la fila inicial que se leerá.

Los valores se muestran unidos en un objeto JSON que debes analizar, como se describe en la documentación de referencia de tabledata.list.

La exportación enumera los activos y sus nombres de recursos.

Consulta una instantánea de activos

Después de exportar la instantánea a BigQuery, puedes ejecutar consultas en los metadatos de tus activos. Consulta Exporta a BigQuery las consultas de muestra para obtener más información sobre varios casos de uso típicos.

De forma predeterminada, BigQuery ejecuta trabajos de consulta interactivos o a pedido, lo que significa que la consulta se ejecuta en cuanto sea posible. Las consultas interactivas se toman en cuenta para tu límite de frecuencia simultánea y límite diario.

Los resultados de las consultas se almacenan en una tabla temporal o permanente. Puedes agregar o reemplazar datos en una tabla existente o crear una tabla nueva, si no existe una con el mismo nombre.

Para ejecutar una consulta interactiva que escribe el resultado en una tabla temporal, completa los siguientes pasos.

Console

  1. Ve a la página de BigQuery en Cloud Console.
    Ir a la página de BigQuery

  2. Seleccione Redactar consulta nueva.

  3. En el área de texto del Editor de consultas, ingresa una consulta de SQL de BigQuery válida.

  4. Para cambiar la ubicación de procesamiento de datos, completa los siguientes pasos (opcional).

    1. Selecciona Más y, luego, Configuración de consulta.
    2. En Ubicación de procesamiento, selecciona Selección automática y, luego, la ubicación de tus datos.
    3. Para actualizar la configuración de la consulta, selecciona Guardar.
  5. Selecciona Run.

API

  1. Para iniciar un trabajo nuevo, llama al método jobs.insert. En el recurso de trabajo, establece los siguientes parámetros.

    • En el campo configuration, configura el campo query como una JobConfigurationQuery que describa el trabajo de consulta de BigQuery.

    • En el campo jobReference, configura el campo location de forma adecuada para tu trabajo.

  2. Para consultar los resultados, llama a getQueryResults. Busca hasta que jobComplete sea igual a true. Puedes comprobar si hay errores y advertencias en la lista errors.