Como exportar para o BigQuery

Este tópico mostra como exportar metadados de recursos para sua organização, pasta ou projeto para uma tabela do BigQuery e, em seguida, executar análises de dados no inventário. O BigQuery oferece uma experiência parecida com SQL para que os usuários analisem dados e gerem insights significativos sem usar scripts personalizados.

Antes de começar

Antes de começar, conclua as etapas a seguir.

  1. Ative a API Cloud Asset Inventory no projeto em que você executará os comandos da API.
    Ativar a API Cloud Asset Inventory

  2. Configure as permissões necessárias para chamar a API Cloud Asset Inventory usando a CLI gcloud ou a API.

  3. Conclua as etapas a seguir para configurar seu ambiente.

    gcloud

    Para configurar seu ambiente e usar a CLI gcloud para chamar a API Cloud Asset Inventory, instale a CLI do Google Cloud no cliente local.

    API

    Para configurar seu ambiente para chamar a API Cloud Asset Inventory com o comando curl do Unix, conclua as etapas a seguir.

    1. Instale o oauth2l na sua máquina local para interagir com o sistema do Google OAuth.
    2. Confirme se você tem acesso ao comando curl do Unix.
    3. Certifique-se de conceder à conta um dos papéis a seguir no projeto, na pasta ou na organização.

      • Papel Leitor de recursos do Cloud (roles/cloudasset.viewer)
      • Papel básico do proprietário (roles/owner)

    Observe que a CLI do gcloud usa o projeto de faturamento como o projeto do consumidor. Se você receber uma mensagem de permissão negada, verifique se o projeto de faturamento é diferente do projeto principal:

    gcloud config list
    

    Para definir o projeto de faturamento como o do consumidor:

    gcloud config set billing/quota_project CONSUMER_PROJECT_NUMBER
    
  4. Se você estiver exportando para um conjunto de dados do BigQuery em um projeto que não tem a API Cloud Asset Inventory ativada, também é necessário conceder os papéis a seguir ao service-${CONSUMER_PROJECT_NUMBER}@gcp-sa-cloudasset.iam.gserviceaccount.com no projeto de destino.

    • Papel de editor de dados do BigQuery (roles/bigquery.dataEditor)
    • Papel de usuário do BigQuery (roles/bigquery.user)

    A conta de serviço é criada chamando a API uma vez. Outra opção é usar os comandos abaixo para criar a conta de serviço e conceder o papel de agente de serviço manualmente:

      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. crie um conjunto de dados do BigQuery;

Limitações

  • As tabelas do BigQuery criptografadas com chaves do Cloud Key Management Service (Cloud KMS) não são compatíveis.

  • Não é possível anexar a saída de exportação a uma tabela, a menos que você esteja exportando para uma tabela particionada. A tabela de destino precisa estar vazia ou você precisa substituí-la. Para substituí-la, use a sinalização --output-bigquery-force com a CLI gcloud ou use force com a API.

  • Os tipos de recursos do Google Kubernetes Engine (GKE), exceto container.googleapis.com/Cluster e container.googleapis.com/NodePool, não são compatíveis com a exportação para tabelas separadas por tipo de recurso.

Como definir o esquema do BigQuery para a exportação

Todas as tabelas do BigQuery são definidas por um esquema que descreve os nomes, tipos de dados e outras informações da coluna. A definição do tipo de conteúdo durante a exportação determina o esquema para a tabela.

  • Recurso ou não especificado: quando você define o tipo de conteúdo como RESOURCE ou não o especifica e define a sinalização per-asset-type como falsa ou não a usa, cria uma tabela do BigQuery que tem o esquema mostrado na figura 1. Resource.data são os metadados de recursos representados como uma string JSON.

    Ao definir o tipo de conteúdo como RESOURCE ou não definir o tipo de conteúdo e definir a sinalização per-asset-type como true, você criará tabelas separadas por tipo de recurso. O esquema de cada tabela inclui colunas do tipo RECORD mapeadas para os campos aninhados no campo Resource.data desse tipo de recurso (até os 15 níveis aninhados compatíveis com o BigQuery). Para tabelas de exemplo do BigQuery por tipo, consulte projects/export-assets-examples/dataset/structured_export.

  • Política do IAM: ao definir o tipo de conteúdo como IAM_POLICY na API REST ou iam-policy na CLI gcloud, você cria uma tabela do BigQuery que tem o esquema mostrado na figura 2. A RECORD do iam_policy está completamente expandida.

  • Política da organização: ao definir o tipo de conteúdo como ORG_POLICY na API REST ou org-policy na CLI gcloud, você cria uma tabela do BigQuery que tem o esquema mostrado na figura 3.

  • Política de VPCSC: ao definir o tipo de conteúdo como ACCESS_POLICY na API REST ou access-policy na CLI gcloud, você cria uma tabela do BigQuery que tem o esquema mostrado na figura 4.

  • Inventário de instâncias do OSConfig: ao definir o tipo de conteúdo como OS_INVENTORY na API REST ou os-inventory na CLI gcloud, crie uma tabela do BigQuery que tenha o esquema mostrado na Figura 5.

  • Relação: ao definir o tipo de conteúdo como RELATIONSHIP na API REST ou relationship na CLI gcloud, você cria uma tabela do BigQuery que tem o seguinte esquema mostrado na figura 6.

Separar tabelas por tipo de recurso

Para exportar um snapshot do recurso em um determinado carimbo de data/hora, conclua as etapas a seguir.

gcloud

Para exportar recursos em um projeto, execute o seguinte comando. Esse comando armazena o snapshot exportado em uma tabela do BigQuery em BIGQUERY_TABLE.

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

Em que:

  • CONTENT_TYPE é o tipo de conteúdo do recurso.
  • PROJECT_ID é o ID do projeto com os metadados que estão sendo exportados. O projeto pode ser aquele do qual você está executando a exportação ou outro projeto.
  • SNAPSHOT_TIME (opcional) é o momento em que você quer tirar um snapshot dos seus recursos. O valor precisa ser a hora atual ou um horário no passado. Por padrão, um snapshot é capturado no horário atual. Para informações sobre formatos de tempo, consulte gcloud topic datetimes.
  • BIGQUERY_TABLE é a tabela para a qual você está exportando seus metadados, no formato projects/PROJECT_ID/datasets/DATASET_ID/tables/TABLE_NAME.
  • --output-bigquery-force substitui a tabela de destino, se ela existir.

Para exportar os recursos de uma organização ou pasta, use uma das seguintes sinalizações no lugar de --project.

access-policy só pode ser exportado para um --organization.

API

Para exportar os metadados do recurso no seu projeto, execute o seguinte comando: Esse comando armazena o snapshot exportado em uma tabela do BigQuery chamada TABLE_NAME. Saiba mais sobre o 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

Exportar tabelas separadas para cada tipo de recurso

Para exportar os recursos de um projeto para separar as tabelas do BigQuery de cada tipo de recurso, use a sinalização --per-asset-type. O nome de cada tabela é BIGQUERY_TABLE concatenado com _ (sublinhado) e ASSET_TYPE_NAME. Caracteres não alfanuméricos serão substituídos por _.

Os tipos de recursos do GKE, exceto para container.googleapis.com/Cluster e container.googleapis.com/NodePool, não são compatíveis com esse tipo de exportação.

Para exportar recursos separados de tabelas do BigQuery para cada tipo de recurso, execute o comando a seguir.

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

Em que:

  • CONTENT_TYPE é o tipo de conteúdo do recurso. Esse valor também determina o esquema da exportação.
  • PROJECT_ID é o ID do projeto com os metadados que estão sendo exportados. O projeto pode ser aquele do qual você está executando a exportação ou outro projeto.
  • SNAPSHOT_TIME (opcional) é o momento em que você quer tirar um snapshot dos seus recursos. O valor precisa ser a hora atual ou um horário no passado. Por padrão, um snapshot é capturado no horário atual. Consulte Tópico sobre datas e horas no gcloud para mais informações sobre formatos de hora válidos.
  • BIGQUERY_TABLE é a tabela para a qual você está exportando seus metadados, no formato projects/PROJECT_ID/datasets/DATASET_ID/tables/TABLE_NAME.
  • --output-bigquery-force substitui a tabela de destino, se ela existir.
  • --per-asset-type exporta para várias tabelas do 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

Saiba mais sobre o método exportAssets.

Se a exportação para qualquer tabela falhar, toda a operação de exportação falhará e retornará o primeiro erro. Os resultados de exportações bem-sucedidas anteriores permanecem.

Os tipos a seguir são compactados em uma string JSON para superar o problema de compatibilidade entre JSON3 e tipos do BigQuery.

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

Como exportar para uma tabela particionada

Para exportar recursos em um projeto para tabelas particionadas, use a sinalização --partition-key. O snapshot exportado é armazenado em uma tabela do BigQuery em BIGQUERY_TABLE com granularidade diária e duas outras colunas de carimbo de data/hora, readTime e requestTime, uma das quais é o parâmetro partition-key.

Para exportar recursos em um projeto para tabelas particionadas, execute o seguinte 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 \

Em que:

  • CONTENT_TYPE é o tipo de conteúdo do recurso. Esse valor também determina o esquema da exportação.
  • PROJECT_ID é o ID do projeto com os metadados exportados. O projeto pode ser aquele do qual você está executando a exportação ou outro projeto.
  • SNAPSHOT_TIME (opcional) é o momento em que você quer tirar um snapshot dos seus recursos. O valor precisa ser a hora atual ou um horário no passado. Por padrão, um snapshot é capturado no horário atual. Para informações sobre formatos de tempo, consulte gcloud topic datetimes.
  • BIGQUERY_TABLE é a tabela para a qual você está exportando seus metadados, no formato projects/PROJECT_ID/datasets/DATASET_ID/tables/TABLE_NAME.
  • PARTITION_KEY é a coluna de chave de partição ao exportar para tabelas particionadas do BigQuery.
  • --output-bigquery-force substitui a tabela de destino, se ela existir.

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

Saiba mais sobre o método exportAssets.

Caso uma tabela de destino já exista, o esquema dessa tabela será atualizado conforme necessário anexando outras colunas. Essa atualização de esquema falhará se alguma coluna alterar o tipo ou modo, como opcional para repetido. Em seguida, se a sinalização output-bigquery-force estiver definida como TRUE, a partição correspondente será substituída pelos resultados do snapshot. No entanto, os dados em uma ou mais partições diferentes permanecem intactos. Se output-bigquery-force não estiver definido ou for FALSE, os dados serão anexados à partição correspondente.

A operação de exportação falhará se a atualização do esquema ou a tentativa de anexar dados falhar.

Como verificar o status de uma exportação

Para verificar o status de uma exportação, execute os comandos a seguir.

gcloud

Para verificar o status da exportação, execute o comando a seguir. Ele é exibido na CLI gcloud após a execução do comando de exportação.

gcloud asset operations describe OPERATION_ID

API

Para ver o status da exportação, execute o comando a seguir com o ID da operação retornado na resposta à exportação.

  1. Encontre o OPERATION_ID no campo name da resposta à exportação, que tem a seguinte formatação:

    "name": "projects/PROJECT_NUMBER/operations/ExportAssets/CONTENT_TYPE/OPERATION_ID"
    
  2. Para verificar o status da exportação, execute o seguinte comando com OPERATION_ID:

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

Como visualizar um instantâneo de um recurso

Para visualizar a tabela que contém os metadados do snapshot do recurso, siga estas etapas.

Console

  1. Acesse a página do BigQuery no console.
    Acessar a página do BigQuery

  2. Para exibir as tabelas e visualizações no conjunto de dados, abra o painel de navegação. Na seção Recursos, selecione seu projeto para expandi-lo e selecione um conjunto de dados.

  3. Na lista, selecione a tabela.

  4. Selecione Detalhes e anote o valor em Número de linhas. Talvez esse valor seja necessário para controlar o ponto de partida dos seus resultados usando a CLI ou a API da gcloud.

  5. Para visualizar um conjunto de dados de amostra, selecione Visualizar.

API

Para procurar os dados da tabela, chame tabledata.list. No parâmetro tableId, especifique o nome da sua tabela.

É possível configurar os seguintes parâmetros opcionais para controlar a saída.

  • maxResults é o número máximo de resultados a serem retornados.
  • selectedFields é uma lista de colunas separadas por vírgulas a ser retornada. Se não for especificado, todas as colunas serão retornadas.
  • startIndex é o índice baseado em zero da primeira linha a ser lida.

Os valores são retornados incorporados em um objeto JSON para análise, conforme descrito na documentação de referência de tabledata.list.

A exportação lista recursos e os respectivos nomes.

Como consultar um snapshot de um recurso

Depois de exportar seu snapshot para o BigQuery, é possível executar consultas nos metadados do recurso. Consulte Como exportar para consultas de amostra do BigQuery para saber mais sobre vários casos de uso típicos.

Por padrão, o BigQuery executa jobs de consulta interativa ou sob demanda, o que significa que ela é executada o mais rápido possível. Essas consultas são realizadas de acordo com o limite de taxa simultânea e o limite de taxa diária.

Os resultados da consulta são salvos em uma tabela temporária ou permanente. É possível anexar ou substituir dados em uma tabela atual ou criar uma nova tabela, se não houver nenhuma com o mesmo nome.

Para executar uma consulta interativa que grava a saída em uma tabela temporária, conclua as etapas a seguir.

Console

  1. Acesse a página do BigQuery no console.
    Acessar a página do BigQuery

  2. Selecione Escrever nova consulta.

  3. Na área de texto do Editor de consultas, insira uma consulta SQL do BigQuery válida.

  4. (Opcional) Para alterar o local de processamento de dados, conclua as etapas a seguir.

    1. Selecione Mais e, em seguida, selecione Configurações de consulta.
    2. Em Local de processamento, selecione Seleção automática e escolha o local dos dados.
    3. Para atualizar as configurações de consulta, selecione Salvar.
  5. Selecione Run.

API

  1. Para iniciar um novo job, chame o método jobs.insert. No recurso do job, defina os parâmetros a seguir.

    • No campo configuration, defina query como um JobConfigurationQuery que descreve o job de consulta do BigQuery.

    • No campo jobReference, defina location como apropriado para seu job.

  2. Para pesquisar resultados, chame getQueryResults. Pesquisar até jobComplete igual a true. É possível verificar se há erros e avisos na lista errors.