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.
Ative a API Cloud Asset Inventory no projeto em que você executará os comandos da API.
Ativar a API Cloud Asset InventoryConfigure as permissões necessárias para chamar a API Cloud Asset Inventory usando a CLI gcloud ou a API.
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.- Instale o oauth2l na sua máquina local para interagir com o sistema do Google OAuth.
- Confirme se você tem acesso ao comando
curl
do Unix. 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
)
- Papel Leitor de recursos do Cloud (
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
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
- Papel de editor 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 useforce
com a API.Os tipos de recursos do Google Kubernetes Engine (GKE), exceto
container.googleapis.com/Cluster
econtainer.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çãoper-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çãoper-asset-type
comotrue
, você criará tabelas separadas por tipo de recurso. O esquema de cada tabela inclui colunas do tipo RECORD mapeadas para os campos aninhados no campoResource.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 ouiam-policy
na CLI gcloud, você cria uma tabela do BigQuery que tem o esquema mostrado na figura 2. ARECORD
doiam_policy
está completamente expandida.Política da organização: ao definir o tipo de conteúdo como
ORG_POLICY
na API REST ouorg-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 ouaccess-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 ouos-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 ourelationship
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
.
--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.
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.
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"
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
Acesse a página do BigQuery no console.
Acessar a página do BigQueryPara 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.
Na lista, selecione a tabela.
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.
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
Acesse a página do BigQuery no console.
Acessar a página do BigQuerySelecione
Escrever nova consulta.Na área de texto do Editor de consultas, insira uma consulta SQL do BigQuery válida.
(Opcional) Para alterar o local de processamento de dados, conclua as etapas a seguir.
- Selecione Mais e, em seguida, selecione Configurações de consulta.
- Em Local de processamento, selecione Seleção automática e escolha o local dos dados.
- Para atualizar as configurações de consulta, selecione Salvar.
Selecione Run.
API
Para iniciar um novo job, chame o método
jobs.insert
. No recurso do job, defina os parâmetros a seguir.No campo
configuration
, definaquery
como um JobConfigurationQuery que descreve o job de consulta do BigQuery.No campo
jobReference
, definalocation
como apropriado para seu job.
Para pesquisar resultados, chame
getQueryResults
. Pesquisar atéjobComplete
igual atrue
. É possível verificar se há erros e avisos na listaerrors
.