Metadados do objeto

Gerenciar

Nesta página, falamos sobre os campos de metadados usados com frequência que são armazenados com os objetos no Cloud Storage.

Introdução

Os objetos armazenados no Cloud Storage têm metadados associados a eles. Os metadados identificam propriedades do objeto e especificam como ele será tratado quando for acessado. Os metadados têm o formato de pares de chave-valor. Por exemplo, a classe de armazenamento de um objeto é representada pela entrada de metadados storageClass:STANDARD, em que storageClass é a chave dos metadados (todos os objetos estão associados a uma chave desse tipo) e STANDARD especifica o valor desse objeto (esse valor é variável dependendo do objeto).

A mutabilidade dos metadados varia: alguns podem ser editados a qualquer momento, uns só podem ser definidos no momento em que o objeto é criado e outros podem apenas ser visualizados. Por exemplo, é possível editar o valor dos metadados Cache-Control a qualquer momento, mas é possível atribuir os metadados storageClass somente quando o objeto é criado ou regravado. Além disso, não é possível editar diretamente o valor dos metadados generation, embora o valor generation seja alterado quando o objeto é substituído.

Metadados editáveis

Existem duas categorias de metadados que os usuários podem alterar para objetos:

  • Metadados de chave fixa: metadados que têm chaves definidas, mas permitem a especificação de um valor.

  • Metadados personalizados: metadados que são adicionados com a especificação de uma chave e um valor associados a ela.

Ao editar os metadados, evite caracteres não-ASCII, porque eles não são permitidos em cabeçalhos HTTP, que são usados pela API XML.

Metadados de chave fixa

É possível editar metadados a seguir para objetos. Porém você precisa ter permissões suficientes para fazer isso.

Metadados de controle de acesso

O Cloud Storage usa o Cloud Identity and Access Management (Cloud IAM) e as listas de controle de acesso (ACLs, na sigla em inglês) para controlar o acesso a objetos. Use esses links para saber mais sobre esses métodos de controle de acesso e metadados associados.

Cache-Control

Os metadados de Cache-Control especificam dois aspectos diferentes de como os dados são exibidos a partir do Cloud Storage: se eles podem ser armazenados em cache e se podem ser transformados.

Como armazenar dados em cache

Com os metadados Cache-Control, é possível controlar se e por quanto tempo os caches podem armazenar seus objetos, que poderão ser exibidos para atender a solicitações futuras. Os caches podem incluir caches do navegador e da Internet, além do armazenamento em cache integrado do Cloud Storage.

Se um objeto relevante não tiver uma entrada de metadados Cache-Control, o Cloud Storage usará o valor padrão:

Se você permitir o armazenamento em cache, talvez continue recebendo versões antigas de um objeto ao fazer o download dele, mesmo depois de fazer o upload de uma versão mais recente. Isso ocorre porque essas versões mais antigas permanecem "atualizadas" em caches por um período determinado pelo valor de max-age. Além disso, como os objetos podem ser armazenados em cache em vários locais na Internet, não há como forçar um objeto que esteja armazenado em cache a expirar globalmente. Ou seja, se você revogar o acesso público a um objeto, ele ainda poderá ser disponibilizado a partir de um cache, dependendo de quando foi acessado pela última vez e da configuração de Cache-Control. Por exemplo, se o objeto foi exibido com um Cache-Control de public, max-age=3600, ele poderá permanecer no cache por uma hora. Se você quiser impedir a exibição de versões armazenadas em cache de objetos de leitura pública, defina Cache-Control: no-store no objeto.

Se você precisa de mais controle sobre o comportamento do cache, configure o Cloud CDN na frente do seu bucket.

Transformação de dados

Com os metadados Cache-Control, também é possível exibir objetos da maneira como estão armazenados, sem aplicar quaisquer transformações aos dados, como a remoção de codificação de conteúdo gzip para clientes incompatíveis. Para exibir um objeto como ele está, defina Cache-Control:no-transform.

Content-Disposition

Os metadados Content-Disposition especificam as informações de apresentação dos dados que estão sendo transmitidos. Ao definir Content-Disposition, você controla o estilo de apresentação do conteúdo. Por exemplo, é possível determinar se um anexo será exibido automaticamente ou se será necessária alguma ação do usuário para abri-lo. Consulte https://datatracker.ietf.org/doc/html/rfc6266 para a especificação de Content-Disposition.

Content-Encoding

Use os metadados Content-Encoding para indicar que um objeto está compactado, enquanto mantém os metadados Content-Type subjacentes dele. Por exemplo, um arquivo de texto compactado como .gzip pode ter essas duas características indicadas, respectivamente, em Content-Type e Content-Encoding. Verifique se os arquivos estão realmente compactados usando os metadados Content-Encoding especificados antes de fazer upload deles. Caso contrário, poderá ocorrer um comportamento inesperado quando você tentar fazer o download dos objetos. Para mais informações, consulte a página sobre transcodificação.

No caso de conteúdo que possa ser compactado, como texto, usar Content-Encoding: gzip economiza custos de rede e de armazenamento, além de melhorar o desempenho na exibição. No entanto, para conteúdo que já está compactado de maneira intrínseca, como arquivos e muitos formatos de mídia, aplicar outro nível de compactação e marcá-lo nos metadados Content-Encoding normalmente é prejudicial em termos de tamanho e desempenho do objeto. Portanto, evite fazer isso.

Content-Language

Os metadados Content-Language indicam o(s) idioma(s) pretendido(s) para o objeto. Consulte os códigos de idioma ISO 639-1 para conferir os valores típicos desses metadados.

O Cloud Storage é compatível com valores de Content-Language de até 100 caracteres.

Content-Type

Os metadados mais comumente configurados são Content-Type (também conhecido como tipo de mídia), que permite que os navegadores renderizem o objeto corretamente. Todos os objetos contam com um valor especificado nos metadados Content-Type. No entanto, esse valor não precisa corresponder ao tipo subjacente do objeto. Por exemplo, caso o usuário que fez o upload não tenha especificado o valor de Content-Type e não for possível determiná-lo, esses metadados serão definidos como application/octet-stream ou application/x-www-form-urlencoded, dependendo do método utilizado no upload do objeto. Para ver uma lista de tipos de conteúdo válidos, consulte a página Tipos de mídia IANA.

Custom-Time

Os metadados Custom-Time são uma data e hora especificadas pelo usuário no formato RFC 3339 YYYY-MM-DD'T'HH:MM:SS.SS'Z' ou YYYY-MM-DD'T'HH:MM:SS'Z' quando milissegundos são zero. Esses metadados geralmente são definidos para usar a condição DaysSinceCustomTime no gerenciamento do ciclo de vida de objetos.

Não é possível remover Custom-Time depois de definir um objeto. Além disso, o valor de Custom-Time não pode diminuir. Ou seja, não é possível definir Custom-Time como data/hora anterior à Custom-Time atual. No entanto, é possível remover ou redefinir efetivamente o Custom-Time gravando o objeto.

Retenções de objetos

Use sinalizações de metadados para colocar retenções de objetos, o que impede que os objetos sejam excluídos ou substituídos. Para mais informações, consulte a página Retenções de objetos.

Configuração da retenção

Quando presente, a configuração de retenção de um objeto define uma data e hora antes de que o objeto não possa ser excluído ou substituído. Para mais informações, consulte Bloqueio de retenção de objetos.

Metadados personalizados

Os metadados personalizados são aqueles em que você define a chave e o valor. Para criar metadados personalizados, especifique uma chave e um valor. Depois de criar um par de key:value para os metadados personalizados, é possível excluir a chave ou alterar o valor.

Os metadados personalizados estão sujeitos a um limite de tamanho e geram custos de armazenamento.

A página Visualização e edição de metadados inclui informações sobre a configuração de metadados personalizados.

O prefixo x-goog-meta-

A API XML define e recupera metadados de objetos usando cabeçalhos de solicitação, e a API JSON permite definir metadados personalizados na solicitação final de um upload retomável usando cabeçalhos de solicitação. Para distinguir claramente os cabeçalhos de metadados personalizados dos cabeçalhos de solicitação padrão, as duas APIs prefixam esses cabeçalhos de metadados personalizados com x-goog-meta-.

Metadados não editáveis

Alguns metadados não podem ser editados diretamente. Eles são definidos no momento da criação ou regravação do objeto. Como parte da criação ou regravação do objeto, é possível definir alguns desses metadados, como a classe de armazenamento do objeto ou chaves de criptografia gerenciadas pelo cliente. Outros metadados, como o número de geração do objeto ou a hora de criação, são adicionados automaticamente e podem ser apenas visualizados.

Números de geração e metageração

Como parte dos metadados, cada objeto do Cloud Storage tem um property generation numérico e outro metageneration que identifica exclusivamente o objeto:

Propriedade Descrição
generation Identifica a versão de um objeto e existe para cada objeto, independentemente de um bucket usar o controle de versão de objetos.
  • O valor de generation de uma versão do objeto nunca é alterado. Um novo objeto com o mesmo nome pode substituir um objeto existente, mas o novo objeto sempre terá um generation diferente atribuído a ele.
  • Não há garantia de que os números de geração aumentem para versões sucessivas, apenas que cada nova versão tem um número de geração exclusivo.
  • Não há relação entre os números de geração de objetos não relacionados, mesmo que os objetos estejam no mesmo bucket.
metageneration Identifica a versão de metadados e aumenta sempre que os metadados de um determinado generation são atualizados.
  • metageneration começa em 1 para cada novo generation de um objeto.
  • A propriedade metageneration não tem significado sem a propriedade generation e só pode ser usada com ela. não faz sentido comparar gerações de metadados de duas versões de objeto.

As propriedades generation e metageneration são usadas nas seguintes circunstâncias:

Somas de verificação

Os checksums são metadados calculados com base nos dados do objeto associado. Os checksums são usados para validar se os dados do objeto não estão corrompidos. Os objetos do Cloud Storage têm vários campos de metadados de checksum.

CRC32C

Todos os objetos do Cloud Storage têm uma hash CRC32C. As bibliotecas para computação do CRC32c incluem:

A CRC32c codificada em Base64 está na ordem de bytes big-endian.

MD5

Os objetos do Cloud Storage têm um hash MD5 se atenderem aos seguintes critérios:

Esse hash só se aplica a um objeto completo, portanto, não pode ser usado para verificar parcialmente os downloads causados pela execução de um intervalo GET.

ETags

Todos os objetos do Cloud Storage têm uma ETag. O mesmo objeto pode ter um valor de ETag diferente quando solicitado da API XML em comparação com a API JSON. Na maioria dos casos, os usuários não precisam pressupor o valor usado em uma ETag, exceto que ele é alterado sempre que os dados subjacentes ou metadados são alterados, de acordo com a especificação.

O cabeçalho ETag de um objeto retorna o valor MD5 do objeto se todas as condições a seguir forem verdadeiras:

Horário da modificação

Como parte dos metadados, cada objeto do Cloud Storage tem uma propriedade updated que indica a última vez em que os metadados do objeto foram modificados. O horário de updated é definido inicialmente como o horário de criação do objeto e, em seguida, é alterado sempre que os metadados são alterados. Isso inclui alterações feitas por um solicitante, como a modificação de metadados personalizados, bem como mudanças feitas pelo Cloud Storage em nome de um solicitante, como a alteração da classe de armazenamento com base em um objeto. Lifecycle Configuration.

A seguir