Se usó la API de Cloud Translation para traducir esta página.
Switch to English

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 herramienta de gcloud o con la API.

  3. Completa los siguientes pasos para configurar el entorno.

    gcloud

    Si deseas configurar tu entorno para usar la herramienta de gcloud a fin de llamar a la API de Cloud Asset Inventory, instala el SDK de 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)
  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á mediante un solo llamado a la API o puedes usar el siguiente comando:

      gcloud beta services identity create --service=cloudasset.googleapis.com --project=PROJECT_ID
    

  5. Crea un conjunto de datos de BigQuery.

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

Aquí:

  • 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

Configura el tipo de contenido

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 no especificado: Cuando configuras el tipo de contenido como RESOURCE o no configuras el tipo de contenido, creas una tabla de BigQuery que tiene el esquema que se muestra en la Figura 1. Resource.data son los metadatos de recursos representados como una string JSON.

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

  • Política de la organización: Cuando estableces el tipo de contenido en ORG_POLICY en la API de REST o org-policy en la herramienta de gcloud, creas una tabla de BigQuery que tiene el esquema que se muestra en la Figura 3.

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

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

Tablas separadas por tipo de recurso

Para exportar una instantánea de un activo en una marca de tiempo determinada por tipo de recurso, completa los siguientes pasos:

gcloud

Para exportar activos en un proyecto por tipo de recurso, ejecuta el siguiente comando. Este comando almacena la instantánea exportada en cero tablas si los resultados de la instantánea están vacíos o en varias tablas de BigQuery. Cada tabla contiene los resultados de un tipo de activo y tiene BIGQUERY_TABLE concatenado con _ (guion bajo) y el nombre del tipo de activo. Los caracteres que no sean alfanuméricos se reemplazan por _.

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

Aquí:

  • 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. 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

Para exportar activos en un proyecto por tipo de recurso, ejecuta el siguiente comando. Este comando almacena la instantánea exportada en cero tablas si los resultados de la instantánea están vacíos o en varias tablas de BigQuery. Cada tabla contiene los resultados de un tipo de activo y tiene BIGQUERY_TABLE concatenado con _ (guion bajo) y el nombre del tipo de activo. Los caracteres que no sean alfanuméricos se reemplazan por _. Consulta el método exportAssets para obtener más información.

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

Si se exporta a cualquier tabla, la operación de exportación fallará y mostrará el primer error. Pero se conservarán los resultados de las exportaciones que se realicen de forma correcta.

Configurar el tipo de contenido durante la exportación determina el esquema para cada una de ellas.

  • Recurso: Cuando configuras el tipo de contenido como RESOURCE, el esquema de cada tabla incluirá la columna con tipo especificado de REGISTRO mapeada a los campos anidados en el campo Resource.data de ese tipo de activo (BigQuery admite hasta el nivel anidado 15). Consulta esquemas de BigQuery por tipo de tablas de ejemplo en projects/export-assets-examples/datasets/structured_export.

  • Política de IAM, política de la organización, política de VPCSC o no especificada: Cuando configuras el tipo de contenido en IAM_POLICY, ORG_POLICY, ACCESS_POLICY o no estableces el tipo de contenido, cada tabla tiene el mismo esquema que configuraste por tipo de activo como falso. Consulta los esquemas en la sección Configura el tipo de contenido para obtener más detalles.

Los siguientes tipos se incluyen en una string JSON para superar el problema de compatibilidad entre los JSON3 y los 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 tablas particionadas

Para exportar una instantánea de activos en una marca de tiempo determinada en una tabla particionada, completa los siguientes pasos.

gcloud

Para exportar activos en un proyecto en tablas particionadas, ejecuta el siguiente comando. Este comando almacena la instantánea exportada 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, que será la clave de partición según tu parámetro partition-key.

  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 \

Aquí:

  • CONTENT_TYPE es el tipo de contenido del activo.
  • 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

Para exportar activos en un proyecto en tablas particionadas, ejecuta el siguiente comando. Este comando almacena la instantánea exportada 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, que será la clave de partición según tu parámetro partition-key. 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 \
      "partitionSpec": {"partitionKey": "PARTITION_KEY"} \
    } \
  }}' \
  https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER:exportAssets

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

La operación de exportación fallará si la actualización del esquema o el intento de adjuntar los datos fallan.

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 herramienta 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 herramienta de gcloud o la API.

  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 manera predeterminada, BigQuery ejecuta trabajos de consulta interactivos 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.