Metadados do objeto

Acessar exemplos

Nesta página, você encontrará informações sobre os campos de metadados que são armazenados junto com 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. Ao usar essa API, também há um limite de 16 KB para o tamanho combinado do URL de solicitação e dos cabeçalhos HTTP. Por isso, leve esse limite em consideração ao definir o tamanho total dos metadados.

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 do navegador e da Internet podem armazenar seus objetos, que poderão ser exibidos para atender a solicitações futuras. Os metadados Cache-Control se aplicam somente ao acessar objetos que:

O Cloud Storage respeita valores padrão para Cache-Control, como estes:

  • public: o objeto pode ser armazenado em cache em qualquer lugar.
  • private: o objeto pode ser armazenado em cache no cache local de um solicitante.
  • no-cache: o objeto pode ser armazenado em cache, mas não pode ser usado para atender a solicitações futuras, a menos que seja validado primeiro pelo Cloud Storage.
  • no-store: o objeto não pode ser armazenado em cache em nenhum lugar.
  • max-age=TIME_IN_SECONDS: o período em que um objeto pode ser armazenado em cache antes de ser considerado desatualizado. Objetos desatualizados não são exibidos a partir de caches, exceto em circunstâncias especiais (em inglês).

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

  • public, max-age=3600.

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 a versão mais antiga permanece "atual" no cache 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. 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.

Para mais informações sobre o armazenamento em cache com o Cloud Storage e o Cloud CDN, consulte Armazenamento em cache.

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://tools.ietf.org/html/rfc6266 (em inglês) para mais informações sobre a especificação 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 (em inglês) para ver os valores compatíveis com esses metadados.

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.

Metadados personalizados

Os metadados personalizados são aqueles que você pode adicionar e remover. Para criar metadados personalizados, especifique um valor e uma chave. Depois de criar um par de key:value de metadados personalizados, é possível excluir a chave ou alterar o valor. Não há limite para o número de chaves de metadados personalizadas de um objeto, mas o uso de metadados personalizados incorre em 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. Para distinguir claramente os cabeçalhos de metadados personalizados dos cabeçalhos de solicitação padrão, os cabeçalhos de metadados personalizados da API XML têm o prefixo x-goog-meta-.

Algumas ferramentas que usam a API XML também aplicam essa convenção. Por exemplo, ao definir metadados personalizados com a gsutil, será necessário incluir o prefixo x-goog-meta-. O gsutil remove o prefixo quando você o usa para visualizar os metadados de um objeto.

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.

A seguir