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:[e-mail] --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.

  Figura 1. Esquema de recurso

  

  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.

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

  Figura 4. Esquema da política VPCSC

  

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

  Figura 5. Esquema do inventário do SO

  

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

  Figura 6. Esquema de relacionamentos

  

Separar tabelas por tipo de recurso

Observação: no momento, esse recurso não é compatível com os 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, 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

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.

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

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