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 ferramenta gcloud ou a API.

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

   gcloud

   Para configurar seu ambiente para usar a ferramenta gcloud para chamar a API Cloud Asset Inventory, instale o SDK do 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 ferramenta 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:[e-mail] --role=roles/cloudasset.serviceAgent
   

5. crie um conjunto de dados do BigQuery;

Observação: no momento, as tabelas do BigQuery criptografadas com chaves personalizadas do Cloud KMS não são aceitas.

Como exportar um instantâneo de um recurso

Observação: não é possível anexar a saída de exportação a uma tabela atual. A tabela de destino precisa estar vazia ou você precisa substituí-la. Para substituí-la, use a sinalização --output-bigquery-force com a ferramenta gcloud ou use force com a API.

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.

• --organization=ORGANIZATION_ID
• --folder=FOLDER_ID

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

Como definir o tipo de conteúdo

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: ao definir o tipo de conteúdo como RESOURCE ou não, você cria uma tabela do BigQuery com o esquema mostrado na figura 1. Resource.data são os metadados do recurso representados como uma string JSON.

  Figura 1. Esquema de recurso

  

Observação: o esquema de recursos só se aplica quando você não usa a sinalização per-asset-type ou a define como false. Consulte a seção Tabelas separadas por tipo de recurso para entender o esquema ao definir a sinalização per-asset-type como true.

.

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

  Figura 2. Esquema do IAM

  

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

  Figura 3. Esquema da política da organização

  

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

  Figura 4 Esquema da política VPCSC

  

• Inventário de instância do OSConfig: ao definir o tipo de conteúdo como OS_INVENTORY na API REST ou os-inventory na ferramenta gcloud, você cria uma tabela do BigQuery que tem o esquema mostrado na figura 5.

  Figura 5. Esquema do inventário do SO

  

Separar tabelas por tipo de recurso

Observação: no momento, este recurso não é compatível com tipos de recursos do Google Kubernetes Engine, exceto "container.googleapis.com/Cluster" e "container.googleapis.com" /NodePool".

Para exportar um snapshot do recurso em um determinado carimbo de data/hora por tipo de recurso, siga estas etapas:

gcloud

Para exportar recursos em um projeto por tipo de recurso, execute o comando a seguir. Esse comando armazenará o snapshot exportado em zero tabelas se os resultados do snapshot estiverem vazios ou em várias tabelas do BigQuery. Cada tabela contém os resultados de um tipo de recurso e tem BIGQUERY_TABLE concatenado com _ (sublinhado) e o nome do tipo de recurso. Caracteres não alfanuméricos são substituídos 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

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

Para exportar recursos em um projeto por tipo de recurso, execute o comando a seguir. Esse comando armazenará o snapshot exportado em zero tabelas se os resultados do snapshot estiverem vazios ou em várias tabelas do BigQuery. Cada uma contém os resultados de um tipo de recurso e tem BIGQUERY_TABLE concatenado com _ (sublinhado) e o nome do tipo de recurso. Os caracteres não alfanuméricos são substituídos por _. Consulte o método exportAssets para saber mais informações.

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

Se a exportação para qualquer tabela falhar, toda a operação de exportação falhará e retornará o primeiro erro. No entanto, os resultados das exportações bem-sucedidas continuarão.

A definição do tipo de conteúdo durante a exportação determina o esquema para cada tabela.

• Recurso: quando você define o tipo de conteúdo como RESOURCE, o esquema de cada tabela inclui colunas de tipo RECORD mapeadas para os campos aninhados no campo Resource.data desse tipo de recurso (o BigQuery oferece suporte para até 15 níveis aninhados). Consulte os esquemas de BigQuery por tipo de tabelas de exemplo em projects/export-assets-examples/datasets/structured_export.

• Política do IAM, política da organização, política de VPCSC ou não especificada: quando você define o tipo de conteúdo como IAM_POLICY, ORG_POLICY, ACCESS_POLICY ou não define o tipo de conteúdo, cada tabela tem o mesmo esquema que você definiu por tipo de recurso como falso, consulte os esquemas na seção Como configurar o tipo de conteúdo para mais detalhes.

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

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

Exportar para tabelas particionadas

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

gcloud

Para exportar recursos em um projeto em tabelas particionadas, execute o comando a seguir. Esse comando armazena o snapshot exportado em uma tabela do BigQuery em BIGQUERY_TABLE com granularidade diária e duas colunas de carimbo de data/hora adicionais, readTime e requestTime, e uma delas será a chave de partição de acordo com seu 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 \

Em que:

• CONTENT_TYPE é o tipo de conteúdo do recurso.
• 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 da chave de partição ao exportar para tabelas particionadas do BigQuery.
• --output-bigquery-force substitui a tabela de destino, se ela existir.

API

Para exportar recursos em um projeto em tabelas particionadas, execute o comando a seguir. Esse comando armazena o snapshot exportado em uma tabela do BigQuery em BIGQUERY_TABLE com granularidade diária e duas colunas de carimbo de data/hora adicionais, readTime e requestTime, e uma delas será a chave de partição de acordo com seu parâmetro partition-key. 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 \
      "partitionSpec": {"partitionKey": "PARTITION_KEY"} \
    } \
  }}' \
  https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER:exportAssets

Quando uma tabela de destino já existir, o esquema da tabela atual será atualizado conforme necessário, anexando colunas adicionais. Essa atualização de esquema falhará se alguma coluna alterar seu tipo ou modo, como opcional para repetida. 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 permanecerão intactos. Se output-bigquery-force não estiver definido ou FALSE, ele anexará os dados à partição correspondente.

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

Como verificar o status de uma exportação

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

Observação: as operações são associadas a um valor OPERATION_ID, que é um UUID. Esse valor é potencialmente confidencial, já que o comando gcloud asset operations describe não requer permissões adicionais para ser executado com êxito. Compartilhe o valor OPERATION_ID somente com usuários de confiança.

Observação: o servidor rejeitará solicitações se uma solicitação anterior ao mesmo destino foi iniciada em 15 minutos e ainda está em execução. Os resultados não definidos podem ocorrer se o tempo de exportação for maior que 15 minutos e uma solicitação consecutiva para o mesmo destino será executada antes da primeira solicitação ser bem-sucedida.

gcloud

Para verificar o status da exportação, execute o comando a seguir. Ele é exibido na ferramenta gcloud depois de executar o 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 do Cloud.
   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 de seus resultados usando a ferramenta gcloud ou a API.

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.

Observação: se você solicitar um startIndex além da última linha, o método retornará com êxito, mas sem a property rows. Para ver quantas linhas há na tabela, chame o método tables.get e examine a property numRows.

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.

Observação: alguns campos experimentais podem inicialmente aparecer vazios no BigQuery. Não defina uma dependência nas colunas afetadas até que os campos sejam preenchidos. Para ver quais campos são públicos, consulte o Documento de descoberta do recurso.

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 do Cloud.
   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.