Como trabalhar com metadados de objetos

Visão geral dos metadados

Os objetos podem ter metadados associados, que controlam aspectos de como as solicitações GET são processadas, incluindo Content-Type, Cache-Control, Content-Disposition e Content-Encoding (discutido em mais detalhes nas subseções abaixo). Além disso, você pode configurar metadados personalizados que podem ser usados por aplicativos (por exemplo, incluir tags para que determinados objetos possuam alguma propriedade).

Há duas maneiras de configurar metadados em objetos:

  • No momento do upload, você pode especificar uma ou mais propriedades de metadados para associar a objetos, usando a opção gsutil -h. Por exemplo, o comando a seguir faz com que o gsutil configure o Content-Type e o Cache-Control para cada um dos arquivos que estão sendo enviados de um diretório local chamado images:

    gsutil -h "Content-Type:text/html" \
           -h "Cache-Control:public, max-age=3600" cp -r images \
           gs://bucket/images
    

    Observe que -h é uma opção no comando gsutil, e não no subcomando cp.

  • Você pode configurar ou remover campos de metadados de objetos já enviados usando o comando gsutil setmeta. Consulte gsutil help setmeta.

Veja abaixo mais detalhes sobre partes específicas de metadados.

Content-Type

O metadado mais comum é o Content-Type, também conhecido como tipo MIME. Ele permite que os navegadores renderizem o objeto corretamente. O gsutil configura o Content-Type automaticamente no momento do upload, com base em cada extensão de nome de arquivo. Por exemplo, o upload de arquivos com nomes terminados em .txt definirá Content-Type como text/plain. Se você estiver executando o gsutil no Linux ou no macOS e preferir que o tipo de conteúdo seja configurado com base no nome e no exame de conteúdo, veja a variável de configuração use_magicfile no arquivo de configuração .boto. Em geral, usar use_magicfile é mais robusto e configurável, mas não está disponível no Windows.

Se você especificar o Content-Type com -h ao fazer upload de conteúdo (como o comando gsutil de exemplo da seção anterior), ele substituirá o Content-Type que seria definido com base na extensão de nome de arquivo ou no conteúdo. Isso pode ser útil se o algoritmo de detecção do Content-Type não funcionar como desejado em alguns de seus arquivos.

Cache-Control

Outra parte dos metadados comumente configurada é o Cache-Control, que permite controlar se e por quanto tempo os caches de navegador e da Internet podem armazenar seus objetos em cache. O Cache-Control só se aplica a objetos com uma ACL de leitura pública. Os dados não públicos não podem ser armazenados em cache.

Veja um exemplo de upload de um conjunto de objetos de um diretório local chamado photos para permitir o armazenamento em cache:

gsutil -h "Cache-Control:public,max-age=3600" cp -a public-read \
       -r photos gs://bucket/photos

Esse comando faz upload de todos os arquivos do diretório (e subdiretórios) photos e os torna acessíveis publicamente e armazenáveis em cache, com validade de cache de uma hora.

Se você permitir o armazenamento em cache, no momento do download, poderá ver versões mais antigas de objetos depois de fazer upload de um objeto de substituição mais recente. Além disso, como os objetos podem ser armazenados em cache em vários locais na Internet, não há como forçar a expiração global de um objeto em cache (diferentemente da forma como é possível forçar o navegador a atualizar o cache). Se você quiser impedir a exibição de versões armazenadas em cache de objetos de leitura pública, defina "Cache-Control:no-cache, max-age=0" no objeto. Você pode fazer isso com um comando como:

gsutil -h "Cache-Control:no-cache,max-age=0" \
       cp -a public-read file.png gs://your-bucket

Outro uso do Cache-Control é por meio do valor "no-transform", que instrui o Cloud Storage a não aplicar transformações de conteúdo com base em detalhes de uma solicitação de download, como remover a codificação de conteúdo gzip para clientes incompatíveis. Esse parâmetro é respeitado apenas pela API XML. A API JSON do Cloud Storage respeita apenas os parâmetros "public", "private", "no-cache" e "max-age" do Cache-Control.

Saiba mais sobre como configurar os metadados do Cache-Control em gsutil help setmeta.

Content-Encoding

É possível especificar um Content-Encoding para indicar que um objeto está compactado (por exemplo, com compactação gzip) enquanto mantém o Content-Type. Você precisará garantir que os arquivos foram compactados usando o Content-Encoding especificado antes de usar o gsutil para fazer upload deles. Pense no seguinte exemplo para Linux:

echo "Highly compressible text" | gzip > foo.txt
gsutil -h "Content-Encoding:gzip" \
       -h "Content-Type:text/plain" \
       cp foo.txt gs://bucket/compressed

Isso é diferente de fazer upload de um objeto foo.txt.gz compactado em gzip com Content-Type: application/x-gzip, porque a maioria dos navegadores é capaz de descompactar dinamicamente e processar objetos exibidos com Content-Encoding: gzip com base no Content-Type subjacente.

Para conteúdos compactáveis, usar o Content-Encoding: gzip economiza custos de rede e armazenamento, além de melhorar o desempenho da exibição de conteúdo. No entanto, para o conteúdo que já é compactado por natureza (por exemplo, arquivos e muitos formatos de mídia), a aplicação de outro nível de compactação por meio do Content-Encoding costuma prejudicar o tamanho e o desempenho do objeto e precisa ser evitado.

Além disso, o gsutil oferece um modo fácil de fazer com que o conteúdo seja compactado e armazenado com Content-Encoding: gzip. Veja as opções -z e -Z em gsutil help cp.

Content-Disposition

É possível configurar o Content-Disposition nos objetos para especificar informações de apresentação sobre os dados que estão sendo transmitidos. Veja um exemplo de upload de arquivos de um diretório local chamado attachments:

gsutil -h 'Content-Disposition:attachment; filename=filename.ext' \
       cp -r attachments gs://bucket/attachments

A configuração do Content-Disposition permite que você controle o estilo de apresentação do conteúdo. Por exemplo, é possível determinar se um anexo deve ser exibido automaticamente ou exigir alguma forma de ação do usuário para abri-lo. Saiba mais sobre o significado do Content-Disposition em https://tools.ietf.org/html/rfc6266.

Metadados personalizados

Você pode adicionar seus próprios metadados personalizados (por exemplo, para uso pelo aplicativo) a um objeto do Cloud Storage usando "x-goog-meta" com -h. Exemplo:

gsutil -h x-goog-meta-reviewer:jane cp mycode.java gs://bucket/reviews

É possível adicionar vários campos de metadados personalizados com nomes diferentes a cada objeto.

Campos configuráveis, valores de campo

Não é possível configurar alguns campos de metadados, como ETag e Content-Length. Você pode configurar os campos a seguir:

  • Cache-Control
  • Content-Disposition
  • Content-Encoding
  • Content-Language
  • Content-Type
  • Metadados personalizados

Os nomes dos campos não diferenciam maiúsculas de minúsculas.

Todos os campos e seus valores precisam consistir apenas em caracteres ASCII, exceto os valores de campos x-goog-meta-, que podem conter valores Unicode arbitrários. Ao configurar metadados usando a API XML, que envia metadados personalizados como cabeçalhos HTTP, os caracteres Unicode serão codificados com UTF-8 e codificados por URL para ASCII. Exemplo:

gsutil setmeta -h "x-goog-meta-foo: ã" gs://bucket/object

armazenaria o par de valores-chave de metadados personalizados de "foo" e "%C3%A3". Depois, executar "ls -L" usando a API JSON para listar os metadados do objeto imprimiria "%C3%A3", enquanto "ls -L" usando a API XML decodificaria esse valor por URL automaticamente, imprimindo o caractere "ã".

Como visualizar metadados que já estão configurados

Você pode ver quais metadados estão configurados em um objeto usando:

gsutil ls -L gs://the_bucket/the_object