Conjuntos de dados do Storage Insights

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

Se quiser insights sobre os 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, na otimização de custos, na aplicação de segurança e na implementação da 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 rotativo de metadados de todos os buckets e objetos em um ou mais projetos de origem especificados em uma organização. Com as informações fornecidas pelos conjuntos de dados, é possível entender melhor e auditar rotineiramente os 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 quer ver 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 acessar 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 essas propriedades do conjunto de dados. Pode levar até 48 horas para que os primeiros dados sejam preenchidos como um conjunto de dados vinculado no BigQuery depois que você configurar o conjunto de dados. Todos os objetos ou buckets recém-adicionados são incluídos no próximo snapshot diário.

  • Nome: um nome usado para referenciar o conjunto de dados. Os nomes são usados como o identificador das configurações do conjunto de dados e não podem ser alterados depois que a configuração é criada. O nome pode ter 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. É possível editar a descrição a qualquer momento.

  • Escopo do conjunto de dados: um campo obrigatório que especifica 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. Os conjuntos de dados são configurados para o escopo especificado. Só é possível especificar um escopo de conjunto de dados para cada configuração de conjunto de dados. É possível atualizar o escopo do conjunto de dados ao editar a configuração dele.

  • Filtros de agrupamento (opcional): usados para incluir e excluir agrupamentos específicos do conjunto de dados por nome ou regiões.

  • 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. Os conjuntos de dados são atualizados com metadados a cada 24 horas e podem reter dados por até 90 dias. Os dados coletados 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 as informações de 2 a 31 de outubro. É possível modificar o período 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 ser compatível com o BigQuery. Recomendamos que você selecione o local das suas tabelas do BigQuery, se houver.

  • Tipo de agente de serviço: um agente de serviço com escopo de configuração ou um agente de serviço 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 e gravar conjuntos de dados, o agente de serviço precisa receber as permissões necessárias.

    Um agente de serviço no escopo do projeto pode acessar e gravar conjuntos de dados gerados com base em 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, só precisará 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 de conjunto de dados no projeto. 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 conjunto de dados, será necessário conceder as permissões necessárias a cada agente de serviço no escopo da configuração. Quando uma configuração de conjunto de dados é excluída, o agente de serviço no escopo da configuração também é excluído.

Vincule o conjunto de dados ao BigQuery depois de criar uma configuração. 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 definidas 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

As seções a seguir descrevem os campos de metadados 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.

Metadados do bucket

A tabela a seguir descreve os campos de metadados do bucket:

Campo de metadados Modo Tipo Descrição
snapshotTime NULLABLE TIMESTAMP O campo snapshotTime armazena o horário da atualização do snapshot dos metadados do bucket no formato RFC 3339.
name NULLABLE STRING O nome do bloco.
location NULLABLE STRING O local do bloco. Os dados de objetos no bucket ficam armazenados fisicamente nesse local.
project NULLABLE INTEGER O número do projeto a que o bucket pertence.
storageClass NULLABLE STRING A classe de armazenamento padrão do bucket.
public NULLABLE RECORD Obsoleto. Esse campo indica se um bucket estava acessível ao público. Use iamConfiguration.
public.bucketPolicyOnly NULLABLE BOOLEAN Obsoleto. Esse campo, parte do registro public, indica se o acesso uniforme no nível do bucket foi ativado, o que impede a concessão de acesso por ACLs no nível do objeto.
public.publicAccessPrevention NULLABLE STRING Obsoleto. Esse campo, parte do registro public, indica se o acesso público ao bucket foi impedido.
autoclass NULLABLE RECORD A configuração da classe automática do bucket, que, quando ativada, controla a classe de armazenamento dos objetos com base em como e quando eles são acessados.
autoclass.enabled NULLABLE BOOLEAN Indica se a classe automática está ativada.
autoclass.toggleTime NULLABLE TIMESTAMP O horário em que a classe automática foi ativada ou desativada pela última vez para este bucket, no formato RFC 3339.
versioning NULLABLE BOOLEAN Indica se o controle de versão do bucket está ativado. Para mais informações, consulte Controle de versão de objetos.
lifecycle NULLABLE BOOLEAN Se o bucket tem ou não uma configuração de ciclo de vida. Consulte gerenciamento do ciclo de vida para mais informações.
metageneration NULLABLE INTEGER A geração de metadados deste bucket.
timeCreated NULLABLE TIMESTAMP A hora da criação do bucket no formato RFC 3339.
tags NULLABLE RECORD Obsoleto. Esse campo contém pares de chave-valor definidos pelo usuário associados ao bucket. Use tags de recursos.
tags.lastUpdatedTime NULLABLE TIMESTAMP Obsoleto. Esse campo, parte do registro tags, indica a última vez em que as tags foram atualizadas.
tags.tagMap REPEATED RECORD Obsoleto. Esse campo, parte do registro tags, contém o mapa de chaves e valores de tag.
tags.tagMap.key NULLABLE STRING Obsoleto. Esse campo, parte do registro tags.tagMap, representa a chave de uma tag.
tags.tagMap.value NULLABLE STRING Obsoleto. Esse campo, parte do registro tags.tagMap, representa o valor de uma tag.
labels REPEATED RECORD Rótulos de agrupamento fornecidos pelo usuário, em pares de chave-valor.
labels.key NULLABLE STRING Uma entrada de rótulo individual.
labels.value NULLABLE STRING O valor do rótulo.
softDeletePolicy NULLABLE OBJECT A política de exclusão reversível do bucket, que define o período em que os objetos no bucket são mantidos em um estado de exclusão reversível após serem excluídos. Os objetos em estado de exclusão reversível não podem ser excluídos permanentemente e podem ser restaurados até o hardDeleteTime.
softDeletePolicy.effectiveTime NULLABLE DATETIME

A data e hora em que a política de exclusão temporária entra em vigor, no formato RFC 3339.

softDeletePolicy.effectiveTime é atualizado sempre que softDeletePolicy.retentionDurationSeconds aumenta.
softDeletePolicy.retentionDurationSeconds NULLABLE LONG O período de tempo em que um objeto excluído de forma reversível é retido e não pode ser excluído permanentemente, em segundos. O valor precisa ser maior ou igual a 604800 (7 dias) e menor que 7776000 (90 dias). O valor também pode ser definido como 0, o que desativa a política de exclusão reversível.
iamConfiguration NULLABLE RECORD A configuração do IAM para um bucket.
iamConfiguration.uniformBucketLevelAccess NULLABLE RECORD A configuração de acesso uniforme no nível do bucket do bucket.
iamConfiguration.uniformBucketLevelAccess.enabled NULLABLE BOOLEAN Se o bucket usa ou não o acesso uniforme no nível do bucket.
iamConfiguration.publicAccessPrevention NULLABLE STRING O status da prevenção de acesso público do bucket, que é "inherited" ou "enforced".
resourceTags REPEATED RECORD As tags do bucket. Para mais informações, consulte a API Cloud Resource Manager.
resourceTags.key NULLABLE STRING A chave da tag de recurso.
resourceTags.value NULLABLE STRING O valor da tag de recurso.

Metadados do objeto

A tabela a seguir descreve os campos de metadados do objeto:

Campo de metadados Modo Tipo Descrição
snapshotTime NULLABLE TIMESTAMP O campo snapshotTime armazena o horário da atualização do snapshot de metadados do objeto no formato RFC 3339.
bucket NULLABLE STRING O nome do bucket que contém o objeto.
location NULLABLE STRING O local do bloco. Os dados de objetos no bucket ficam armazenados fisicamente nesse local.
componentCount NULLABLE INTEGER Retornado apenas para objetos compostos. Número de objetos não compostos no objeto composto. componentCount inclui objetos não compostos que faziam parte de objetos compostos usados para compor o objeto atual.
contentDisposition NULLABLE STRING Content-Disposition dos dados do objeto.
contentEncoding NULLABLE STRING Content-Encoding dos dados do objeto.
contentLanguage NULLABLE STRING Content-Language dos dados do objeto.
contentType NULLABLE STRING Content-Type dos dados do objeto.
crc32c NULLABLE INTEGER Checksum CRC32c, conforme descrito no RFC 4960, Apêndice B; codificado usando base64 na ordem de bytes big-endian.
customTime NULLABLE TIMESTAMP Um carimbo de data/hora especificado pelo usuário para o objeto no formato RFC 3339.
etag NULLABLE STRING Tag de entidade HTTP 1.1 do objeto.
eventBasedHold NULLABLE BOOLEAN Se o objeto está sujeito a uma retenção baseada em evento.
generation NULLABLE INTEGER A geração de conteúdo desse objeto.
md5Hash NULLABLE STRING Hash MD5 dos dados, codificado usando base64. Esse campo não está presente para objetos compostos.
metadata REPEATED RECORD Metadados fornecidos pelo usuário, em pares de chave-valor.
metadata.key NULLABLE STRING Uma entrada de metadados individuais.
metadata.value NULLABLE STRING O valor dos metadados.
metageneration NULLABLE INTEGER A versão dos metadados desse objeto nessa geração.
name NULLABLE STRING O nome do objeto.
size NULLABLE INTEGER Content-Length dos dados em bytes.
storageClass NULLABLE STRING A classe de armazenamento do objeto.
temporaryHold NULLABLE BOOLEAN Indica se o objeto está sujeito a uma retenção temporária.
timeCreated NULLABLE TIMESTAMP O horário de criação do objeto no formato RFC 3339.
timeDeleted NULLABLE TIMESTAMP O horário de exclusão do objeto no formato RFC 3339.
updated NULLABLE TIMESTAMP O horário de modificação dos metadados do objeto no formato RFC 3339.
timeStorageClassUpdated NULLABLE TIMESTAMP O horário em que a classe de armazenamento do objeto foi alterada pela última vez.
retentionExpirationTime NULLABLE TIMESTAMP O primeiro momento em que o objeto pode ser excluído, o que depende de qualquer configuração de retenção definida para o objeto e de qualquer política de retenção definida para o bucket que contém o objeto. O valor para retentionExpirationTime é fornecido no formato RFC 3339.
softDeleteTime NULLABLE DATETIME O horário em que o objeto foi excluído de maneira reversível. Disponível apenas para objetos em buckets com uma política de exclusão reversível.
hardDeleteTime NULLABLE DATETIME O momento em que um objeto excluído de maneira reversível é excluído permanentemente e não pode mais ser restaurado. O valor é a soma do valor softDeleteTime e do valor softDeletePolicy.retentionDurationSeconds do bucket. Disponível apenas para objetos em buckets com uma política de exclusão reversível.
project NULLABLE INTEGER O número do projeto a que o bucket pertence.

Snapshot mais recente de metadados de buckets e objetos

O conjunto de dados vinculado expõe o snapshot mais recente dos metadados do bucket e do objeto nas seguintes visualizações dedicadas:

  • O bucket_attributes_latest_snapshot_view fornece os metadados mais recentes dos seus buckets do Cloud Storage. A estrutura dele corresponde ao esquema de metadados do bucket.

  • O object_attributes_latest_snapshot_view fornece os metadados mais recentes dos seus objetos do Cloud Storage. A estrutura dele corresponde ao esquema de metadados do objeto.

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 Descrição
snapshotTime NULLABLE TIMESTAMP O campo snapshotTime armazena o horário da atualização do snapshot dos metadados do projeto no formato RFC 3339.
name NULLABLE STRING O nome do projeto.
id NULLABLE STRING O identificador exclusivo do projeto.
number NULLABLE NUMBER Um valor numérico associado ao projeto.

Esquema do conjunto de dados para eventos e erros

No conjunto de dados vinculado, também é possível conferir os eventos e erros de processamento de snapshots nas visualizações events_view e error_attributes_view. Para saber como resolver problemas de erros de processamento de snapshots, consulte Resolver problemas de 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 no formato RFC 3339 em que o snapshot dos eventos é atualizado.
manifest.viewName NULLABLE STRING O nome da visualização que foi atualizada.
manifest.location NULLABLE STRING O local de origem dos dados atualizados.
globalManifest.snapshotTime NULLABLE TIMESTAMP O horário no formato RFC 3339 em que o snapshot dos eventos é atualizado.
eventTime NULLABLE STRING O horário em que o evento aconteceu.
eventCode NULLABLE STRING O código do evento associado à entrada correspondente. O código do evento 1 se refere à atualização da visualização manifest.viewName com todas as entradas do local de origem manifest.location no snapshot manifest.snapshotTime. O código de evento 2 indica que o conjunto de dados foi atualizado com as entradas de bucket e objeto de todos os locais de origem. Essa atualização ocorre no snapshot globalManifest.snapshotTime.

Códigos de erro

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

Nome da coluna Modo Tipo Descrição
errorCode NULLABLE INTEGER O código de erro associado a esta entrada. Para uma lista de valores válidos e como resolver problemas, consulte Resolver problemas de 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 de origem do erro no Cloud Storage. Para projetos, esse campo é nulo porque eles não têm local.
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 ingerir 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 de 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 conjunto de dados

Para saber como resolver os erros de processamento de snapshots registrados na visualização error_attributes_view do 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 no 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 configurações de conjunto de dados:

  • Quando você renomeia uma pasta em um bucket com o namespace hierárquico ativado, os nomes dos objetos nesse bucket sã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 compatíveis apenas nestes locais do BigQuery.

A seguir