Conjuntos de dados do Storage Insights

O recurso de conjuntos de dados do Storage Insights ajuda você a entender, organizar e gerenciar seus dados em grande escala. Você pode escolher uma organização ou um ou mais projetos ou pastas que contenham os buckets e objetos em que você quer atualizar os metadados. Um índice de metadados pesquisável para os buckets e objetos incluídos nesses projetos é disponibilizado como um conjunto de dados vinculado do BigQuery.

Se você quiser insights sobre seus recursos do Cloud Storage exportados para o BigQuery, use os conjuntos de dados do Storage Insights. Esses insights podem ajudar na análise de dados, otimização de custos, aplicação de segurança e implementação de governança. Os conjuntos de dados do Storage Insights são um recurso exclusivo disponível apenas com a assinatura do Storage Intelligence.

Visão geral

Um conjunto de dados do Storage Insights é um snapshot contínuo de metadados de todos os buckets e objetos em um ou vários projetos de origem especificados em uma organização. As informações fornecidas pelos conjuntos de dados permitem que você entenda melhor e audite regularmente seus dados do Cloud Storage.

Para criar um conjunto de dados, primeiro crie uma configuração de conjunto de dados em um projeto. Você pode escolher uma organização ou um ou mais projetos ou pastas que contêm buckets e objetos para os quais você quer conferir os metadados. A configuração do conjunto de dados gera conjuntos de dados diariamente. As configurações e os conjuntos de dados são recursos armazenados no Cloud Storage.

Para visualizar um conjunto de dados, primeiro vincule-o ao BigQuery.

Propriedades de configuração do conjunto de dados

Ao criar uma configuração de conjunto de dados, você define as seguintes propriedades do conjunto de dados:

  • Nome: um nome usado para referenciar o conjunto de dados. Os nomes são usados como identificador das configurações do conjunto de dados e não podem ser alterados depois que a configuração é criada. O nome tem até 128 caracteres usando letras, números e sublinhados. O nome precisa começar com uma letra.

  • Descrição (opcional): uma descrição do conjunto de dados. Você pode editar a descrição a qualquer momento.

  • Escopo do conjunto de dados: uma organização, projetos ou pastas que contêm os buckets e objetos para os quais você quer metadados. É possível especificar projetos ou pastas individualmente ou como um arquivo CSV, com cada número de projeto ou pasta em uma linha separada. É possível especificar até 10.000 projetos ou pastas em uma configuração de conjunto de dados.

  • Filtros de baldes (opcional): filtros usados para incluir e excluir baldes específicos do conjunto de dados por nome ou região.

  • Período de retenção: o número de dias em que o conjunto de dados captura e retém dados, incluindo a data de criação do conjunto de dados. Os conjuntos de dados são atualizados com metadados a cada 24 horas e podem reter dados por até 90 dias. Os dados capturados fora da janela de retenção são excluídos automaticamente. Por exemplo, suponha que você tenha um conjunto de dados criado em 1º de outubro de 2023 com uma janela de retenção definida como 30. Em 30 de outubro, o conjunto de dados vai refletir os últimos 30 dias de dados, de 1 a 30 de outubro. Em 31 de outubro, o conjunto de dados vai refletir os dados de 2 a 31 de outubro. Você pode modificar a janela de retenção a qualquer momento.

  • Local: um local para armazenar o conjunto de dados e os dados dele. Por exemplo, us-central1. O local precisa ter suporte do BigQuery. Recomendamos que você selecione o local das suas tabelas do BigQuery, se tiver.

  • Tipo de agente de serviço: um agente de serviço com escopo de configuração ou com escopo de projeto.

    A criação de uma configuração de conjunto de dados provisiona um agente de serviço para você. Para ler conjuntos de dados, o agente de serviço precisa ter as permissões necessárias para ler dados dos buckets do Cloud Storage.

    Um agente de serviço no escopo do projeto pode acessar e gravar conjuntos de dados gerados a partir de todas as configurações de conjunto de dados no projeto. Por exemplo, se você tiver várias configurações de conjunto de dados em um projeto, basta conceder as permissões necessárias ao agente de serviço no escopo do projeto uma vez para que ele possa ler e gravar conjuntos de dados para todas as configurações no projeto. Para mais informações sobre as permissões necessárias para ler e gravar conjuntos de dados, consulte Permissões. Quando uma configuração de conjunto de dados é excluída, o agente de serviço no escopo do projeto não é excluído.

    Um agente de serviço com escopo de configuração só pode acessar e gravar o conjunto de dados gerado pela configuração específica. Isso significa que, se você tiver várias configurações de conjuntos de dados, vai precisar conceder as permissões necessárias a cada agente de serviço com escopo de configuração. Quando uma configuração de conjunto de dados é excluída, o agente de serviço no escopo da configuração é excluído.

Vincule o conjunto de dados ao BigQuery depois de criar uma configuração de conjunto de dados. A vinculação de um conjunto de dados ao BigQuery cria um conjunto de dados vinculado no BigQuery para consultas. É possível vincular ou desvincular o conjunto de dados a qualquer momento.

Para mais informações sobre as propriedades que você define ao criar ou atualizar uma configuração de conjunto de dados, consulte o recurso DatasetConfigs na documentação da API JSON.

Locais suportados

Os seguintes locais do BigQuery são compatíveis com a criação de conjuntos de dados vinculados:

  • EU
  • US
  • asia-southeast1
  • europe-west1
  • us-central1
  • us-east1
  • us-east4

Esquema de metadados do conjunto de dados

Os seguintes campos de metadados são incluídos nos conjuntos de dados. Para mais informações sobre os modos de coluna do BigQuery, consulte Modos. Os modos de coluna determinam como o BigQuery armazena e consulta os dados.

O campo snapshotTime armazena o horário da atualização do snapshot de metadados do bucket no formato RFC 3339.

Metadados do bucket

Salvo indicação em contrário, é possível encontrar descrições mais detalhadas dos campos de metadados de bucket a seguir consultando a representação do recurso buckets para a API JSON.

Campo de metadados Modo Tipo
snapshotTime NULLABLE TIMESTAMP
name NULLABLE STRING
location NULLABLE STRING
project NULLABLE INTEGER
storageClass NULLABLE STRING
versioning NULLABLE BOOLEAN
lifecycle NULLABLE BOOLEAN
metageneration NULLABLE INTEGER
timeCreated NULLABLE TIMESTAMP
public NULLABLE RECORD
public.bucketPolicyOnly NULLABLE BOOLEAN
public.publicAccessPrevention NULLABLE STRING
autoclass NULLABLE RECORD
autoclass.enabled NULLABLE BOOLEAN
autoclass.toggleTime NULLABLE TIMESTAMP
softDeletePolicy NULLABLE OBJECT
softDeletePolicy.effectiveTime NULLABLE DATETIME
softDeletePolicy.retentionDurationSeconds NULLABLE LONG
tags* NULLABLE RECORD
tags.lastUpdatedTime NULLABLE TIMESTAMP
tags.tagMap REPEATED RECORD
tags.tagMap.key NULLABLE STRING
tags.tagMap.value NULLABLE STRING
labels REPEATED RECORD
labels.key NULLABLE STRING
labels.value NULLABLE STRING

* As tags do bucket. Para mais informações, consulte a API Cloud Resource Manager.

Metadados do objeto

A menos que indicado de outra forma, é possível encontrar descrições mais detalhadas dos campos de metadados de objetos a seguir consultando a representação do recurso de objetos para a API JSON.

Campo de metadados Modo Tipo
snapshotTime NULLABLE TIMESTAMP
bucket NULLABLE STRING
location NULLABLE STRING
componentCount NULLABLE INTEGER
contentDisposition NULLABLE STRING
contentEncoding NULLABLE STRING
contentLanguage NULLABLE STRING
contentType NULLABLE STRING
crc32c NULLABLE INTEGER
customTime NULLABLE TIMESTAMP
etag NULLABLE STRING
eventBasedHold NULLABLE BOOLEAN
generation NULLABLE INTEGER
md5Hash NULLABLE STRING
metageneration NULLABLE INTEGER
name NULLABLE STRING
size NULLABLE INTEGER
storageClass NULLABLE STRING
temporaryHold NULLABLE BOOLEAN
timeCreated NULLABLE TIMESTAMP
timeDeleted NULLABLE TIMESTAMP
updated NULLABLE TIMESTAMP
timeStorageClassUpdated NULLABLE TIMESTAMP
retentionExpirationTime NULLABLE TIMESTAMP
softDeleteTime NULLABLE DATETIME
hardDeleteTime NULLABLE DATETIME
metadata REPEATED RECORD
metadata.key NULLABLE STRING
metadata.value NULLABLE STRING

Metadados do projeto

Os metadados do projeto são expostos como uma visualização chamada project_attributes_view no conjunto de dados vinculado:

Campo de metadados Modo Tipo
snapshotTime NULLABLE TIMESTAMP
name NULLABLE STRING
id NULLABLE STRING
number NULLABLE NUMBER

Esquema do conjunto de dados para eventos e erros

No conjunto de dados vinculado, também é possível conferir os eventos de processamento de capturas de tela e os erros nas visualizações events_view e error_attributes_view. Para saber como resolver erros de processamento de snapshots, consulte Resolver erros de conjuntos de dados.

Registro de eventos

É possível conferir os registros de eventos na visualização events_view do conjunto de dados vinculado:

Nome da coluna Modo Tipo Descrição
manifest.snapshotTime NULLABLE TIMESTAMP O horário em que o resumo dos eventos é atualizado, no formato RFC 3339.
manifest.viewName NULLABLE STRING O nome da visualização que foi atualizada.
manifest.location NULLABLE STRING O local de origem dos dados atualizados.
eventTime NULLABLE STRING A hora em que o evento ocorreu.
eventCode NULLABLE STRING O código do evento associado à entrada correspondente. O código de evento 1 se refere à visualização manifest.viewName sendo atualizada com todas as entradas do local de origem manifest.location no snapshot manifest.snapshotTime.

Códigos de erro

É possível conferir os códigos de erro na visualização error_attributes_view no conjunto de dados vinculado:

Nome da coluna Modo Tipo Descrição
errorCode NULLABLE INTEGER O código de erro associado a essa entrada. Para conferir uma lista de valores válidos e como resolvê-los, consulte Resolver erros de conjunto de dados.
errorSource NULLABLE STRING A origem do erro. Valor válido: CONFIGURATION_PREPROCESSING.
errorTime NULLABLE TIMESTAMP A hora em que o erro ocorreu.
sourceGcsLocation NULLABLE STRING O local do Cloud Storage de origem do erro. Para projetos, esse campo é nulo porque eles não têm localização.
bucketErrorRecord.bucketName NULLABLE STRING O nome do bucket envolvido no erro. Use essas informações para depurar um erro de bucket.
bucketErrorRecord.serviceAccount NULLABLE STRING A conta de serviço que precisa de permissão para importar objetos do bucket. Use essas informações para depurar um erro de bucket.
projectErrorRecord.projectNumber NULLABLE INTEGER O número do projeto envolvido no erro. Use essas informações para depurar um erro do projeto.
projectErrorRecord.organizationName NULLABLE STRING O número da organização a que o projeto precisa pertencer para ser processado. Um valor de 0 indica que o conjunto de dados não está na organização. Use essas informações para depurar um erro de projeto.

Resolver erros de conjuntos de dados

Para saber como resolver os erros de processamento de snapshots registrados na visualização error_attributes_view no conjunto de dados vinculado, consulte a tabela a seguir:

Código do erro Caso de erro Mensagem de erro Solução de problemas
1 O projeto de origem não pertence à organização O projeto de origem projectErrorRecord.projectNumber não pertence à organização projectErrorRecord.organizationName. Adicione o projeto de origem projectErrorRecord.projectNumber à organização projectErrorRecord.organizationName. Para instruções sobre como migrar um projeto entre organizações, consulte Migrar projetos entre organizações.
2 Erro de autorização do bucket Permissão negada para ingerir objetos do bucket bucketErrorRecord.bucketName. Conceda à conta de serviço bucketErrorRecord.serviceAccount permissões de gerenciamento de identidade e acesso (IAM) para permitir a ingestão de objetos no bucket bucketErrorRecord.bucketName. Para mais informações, consulte Conceder as permissões necessárias ao agente de serviço.
3 O projeto de destino não pertence à organização O projeto de destino projectErrorRecord.projectNumber não está na organização projectErrorRecord.organizationName. Adicione o projeto de destino projectErrorRecord.projectNumber à organização projectErrorRecord.organizationName. Para instruções sobre como migrar um projeto entre organizações, consulte Migrar projetos entre organizações.
4 O projeto de origem não tem o Storage Intelligence configurado. O projeto de origem projectErrorRecord.projectNumber não tem o Storage Intelligence configurado. Configure o Storage Intelligence para o projeto de origem projectErrorRecord.projectNumber. Para mais informações, consulte Configurar e gerenciar o Storage Intelligence.
5 O bucket não tem o Storage Intelligence configurado. O bucket bucketErrorRecord.bucketName não tem o Storage Intelligence configurado. Configure o Storage Intelligence para o bucket bucketErrorRecord.bucketName. Para mais informações, consulte Configurar e gerenciar o Storage Intelligence.

Considerações

Considere o seguinte para as configurações de conjuntos de dados:

  • Quando você renomear uma pasta em um bucket com o namespace hierárquico ativado, os nomes dos objetos nesse bucket serão atualizados. Quando ingeridos pelo conjunto de dados vinculado, esses snapshots de objetos são considerados novas entradas nos conjuntos de dados vinculados.

  • Os conjuntos de dados são aceitos apenas nesses locais do BigQuery.

A seguir