Nomear objetos do Amazon S3 - Amazon Simple Storage Service
Escolher nomes de chave de objetoDiretrizes de nomeação de chave de objeto

Nomear objetos do Amazon S3

A chave de objeto (ou nome da chave) identifica o objeto em um bucket do Amazon S3 de maneira exclusiva. Ao criar um objeto, você especifica o nome da chave. Por exemplo, no console do Amazon S3, quando você seleciona um bucket, é exibida uma lista de objetos no bucket. Esses nomes são as chaves de objeto.

O nome da chave do objeto é uma sequência de caracteres Unicode com codificação UTF-8 de até 1.024 bytes de extensão, ou 1.024 caracteres latinos. Em algumas localidades, um único caractere pode equivaler a 2 bytes. Ao nomear objetos, esteja ciente do seguinte:

  • Os nomes das chaves de objeto diferenciam letras maiúsculas de minúsculas.

  • Os nomes das chaves de objeto incluem quaisquer prefixos (conhecidos como pastas no console). Por exemplo, Development/Projects.xls é o nome completo da chave do objeto Projects.xls localizado dentro do prefixo (ou pasta) Development. O prefixo, o delimitador (/) e o nome do objeto estão incluídos na limitação de 1.024 bytes para o nome da chave do objeto. Para ter mais informações sobre prefixos e pastas, consulte Escolher nomes de chave de objeto.

  • Certos caracteres podem exigir tratamento especial quando usados em nomes de chaves de objeto. Para ter mais informações, consulte Diretrizes de nomeação de chave de objeto.

nota

Os nomes de chaves de objeto com o valor "soap" não são compatíveis com solicitações de estilo de hospedagem virtual. Quanto a valores de nome de chave de objeto em que se usa "soap", deve-se usar, em vez disso, um URL de estilo de caminho.

Escolher nomes de chave de objeto

O modelo de dados do Amazon S3 é uma estrutura plana: você cria um bucket e o bucket armazena objetos. Não há hierarquia de sub-buckets ou de subpastas. No entanto, é possível pressupor a hierarquia lógica usando prefixos e delimitadores de nome de chave como faz o console do Amazon S3. O console do Amazon S3 é compatível com o conceito de pastas. Para obter mais informações sobre como editar metadados do console do Amazon S3, consulte Editar metadados de objeto no console do Amazon S3.

Vamos supor que seu bucket (admin-created) tenha quatro objetos com as seguintes chaves de objeto:

Development/Projects.xls

Finance/statement1.pdf

Private/taxdocument.pdf

s3-dg.pdf

O console usa prefixos de nome de chave (Development/, Finance/ e Private/) e o delimitador (/) para apresentar uma estrutura de pastas. A chave s3-dg.pdf não contém um prefixo delimitado por barra, por isso seu objeto aparece diretamente no nível da raiz do bucket. Ao abrir a pasta Development/, o objeto Projects.xlsx é exibido.

  • O Amazon S3 é compatível com buckets e objetos e não há nenhuma hierarquia. No entanto, ao usar prefixos e delimitadores em um nome de chave de objeto, o console do Amazon S3 e os AWS SDKs podem pressupor uma hierarquia e apresentar o conceito de pastas.

  • O console do Amazon S3 implementa a criação de objetos de pasta criando objetos de zero bytes com o valor de prefixo e do delimitador da pasta como a chave. Esses objetos de pasta não aparecem no console. Caso contrário, eles se comportam como qualquer outro objeto e podem ser visualizados e manipulados por meio da API REST, AWS CLI e AWS SDKs.

Diretrizes de nomeação de chave de objeto

Você pode usar qualquer caractere UTF-8 em um nome de chave de objeto. No entanto, o uso de determinados caracteres em nomes de chave pode causar problemas com algumas aplicações e protocolos. As seguintes diretrizes ajudam você a maximizar a conformidade com DNS, caracteres seguros da web, parsers de XML e outras APIs.

Caracteres seguros

Os seguintes conjuntos de caracteres são, geralmente, confiáveis para uso em nomes de chave:

Alphanumeric characters

  • 0-9

  • a-z

  • A-Z
Special characters

  • Ponto de exclamação (!)

  • Hífen (-)

  • Sublinhado (_)

  • Ponto final (.)

  • Asterisco (*)

  • Aspas simples (')

  • Parêntese de abertura (()

  • Parêntese de fechamento ())

Os seguintes são exemplos de nomes de chave válidos:

  • 4my-organization

  • my.great_photos-2014/jan/myvacation.jpg

  • videos/2014/birthday/video1.wmv

nota

Se você usar o console do Amazon S3 para fazer download de objetos com nomes de chave que terminam com pontos (.), os pontos serão removidos do final dos nomes de chave dos objetos baixados. Para manter os pontos no final dos nomes de chave nos objetos baixados, você deve usar a AWS Command Line Interface (AWS CLI), os AWS SDKs ou a API REST do Amazon S3.

Além disso, saiba das seguintes limitações do prefixo:

  • Objetos com um prefixo de ./ devem ser carregados ou baixados com a AWS CLI, os AWS SDKs ou a API REST. Não é possível usar o console do Amazon S3 para fazer upload desses objetos.

  • As chaves de objeto que contêm elementos de caminho relativo (por exemplo, ../) são válidas se, quando analisadas da esquerda para a direita, a contagem cumulativa de segmentos de caminho relativo nunca exceder o número de elementos de caminho não relativos encontrados. Essa regra se aplica a todas as solicitações feitas usando o console do Amazon S3, a API REST do Amazon S3, a AWS CLI e os AWS SDKs.

    Por exemplo:

    • videos/2014/../../video1.wmv é válido.

    • videos/../../video1.wmv não é válido.

    • videos/../../2014/video1.wmv não é válido.

Caracteres que podem exigir tratamento especial

Os caracteres a seguir em um nome de chave podem exigir tratamento adicional do código e, provavelmente, precisarão ser criptografados em URL ou referenciados como HEX. Alguns desses caracteres não são imprimíveis, e seu navegador pode não reconhecê-los, o que também exigirá tratamento especial:

  • E comercial (&)

  • Sinal de dólar ($)

  • Caracteres ASCII variam de 00-1F em hexadecimal (0-31 decimal) e 7F (127 decimal)

  • Símbolo de arroba (@)

  • Sinal de igual (=)

  • Ponto e vírgula (;)

  • Barra (/)

  • Dois pontos (:)

  • Sinal de adição (+)

  • Espaço: sequências significativas de espaços podem ser perdidas em alguns casos (especialmente múltiplos espaços)

  • Vírgula (,)

  • Ponto de interrogação (?)

Caracteres a serem evitados

Recomendamos não usar os seguintes caracteres no nome de uma chave devido ao tratamento significativo de caracteres especiais, que não é consistente em todas as aplicações:

  • Barra invertida (\)

  • Chave esquerda ({)

  • Caracteres ASCII não imprimíveis (128-255 caracteres decimais)

  • Acento circunflexo (^)

  • Chave direita (})

  • Caractere de porcentagem (%)

  • Acento grave ou crase (`)

  • Colchete direito (])

  • Aspas (")

  • Sinal maior que (>)

  • Colchete esquerdo ([)

  • Til (~)

  • Sinal menor que (<)

  • Sinal de libra (#)

  • Barra vertical (|)

Conforme especificado pelo padrão XML no processamento de fim de linha, todo o texto XML é normalizado de modo que os retornos de carro simples (código ASCII 13) e os retornos de carro imediatamente seguidos por uma nova linha (código ASCII 10), também conhecidos como caracteres de quebra de linha, sejam substituídos por um único caractere de nova linha. Para garantir a análise correta de chaves de objeto em solicitações XML, retornos de carro e outros caracteres especiais devem ser substituídos por seu código de entidade XML equivalente quando forem inseridos em tags XML.

A seguinte lista mostra os tais caracteres especiais e seus códigos de entidade XML equivalentes:

  • O apóstrofo (') deve ser substituído por &apos;.

  • As aspas (") devem ser substituídas por &quot;.

  • O e comercial (&) deve ser substituído por &amp;.

  • O sinal menor que (<) deve ser substituído por &lt;.

  • O sinal maior que (>) deve ser substituído por &gt;.

  • O retorno de carro (\r) deve ser substituído por &#13; ou &#x0D;.

  • A quebra de linha (\n) deve ser substituída por &#10; ou &#x0A;.

O exemplo a seguir ilustra o uso de um código de entidade XML como uma substituição para um retorno de carro. Esta solicitação DeleteObjects exclui um objeto com o parâmetro key /some/prefix/objectwith\rcarriagereturn (em que \r é o retorno de carro).

<Delete xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Object>
    <Key>/some/prefix/objectwith&#13;carriagereturn</Key>
  </Object>
</Delete>