Criar nomes de chave de objeto - Amazon Simple Storage Service
Diretrizes de nomeação de chave de objeto

Criar nomes de chave de objeto

A chave de objeto (ou nome da chave) identifica o objeto em um bucket do Amazon S3 de maneira exclusiva. Metadados de objeto são um conjunto de pares de nome-valor. Para obter mais informações sobre metadados de objeto, consulte Trabalhar com metadados de objeto.

Quando você cria um objeto, especifica o nome da chave que, exclusivamente, identifica o objeto no bucket. Por exemplo, no console do Amazon S3, quando você destaca um bucket, uma lista de objetos no bucket é exibida. 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. Os nomes das chaves de objeto diferenciam letras maiúsculas de minúsculas.

nota

Os nomes de chave 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.

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 pasta. A chave s3-dg.pdf não tem um prefixo, de modo que 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 alguns aplicativos 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 (')

  • Abrir parênteses (()

  • Fechar parênteses ())

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

Objetos com nomes de chave terminando com pontos "." e baixados usando o console do Amazon S3 terão os pontos “.” removidos do nome da chave do objeto baixado. Para baixar um objeto com o nome da chave terminado com ponto “.” mantido no objeto baixado, será necessário usar a AWS Command Line Interface (AWS CLI), AWS SDKs ou a API REST.

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

  • Objetos com um prefixo de “./” devem ser carregados ou baixados com a AWS Command Line Interface (AWS CLI), AWS SDKs ou a API REST. Você não pode usar o console do Amazon S3.

  • Objetos com um prefixo de “../” não podem ser carregados usando a AWS Command Line Interface (AWS CLI) ou o console do Amazon S3.

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:

  • Sinal tipográfico (“&”)

  • Dólar ("$")

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

  • Símbolo 'Arroba' ("@")

  • Igual a ("=")

  • Ponto-e-vírgula (“;")

  • Barra (“/”)

  • Dois pontos (“:")

  • Mais ("+")

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

  • Vírgula (“,”)

  • Ponto de interrogação (“?”)

Caracteres a serem evitados

Evite os caracteres a seguir em um nome de chave devido ao tratamento especial significativo necessário para consistência em todos os aplicativos.

  • Barra invertida (“\")

  • Chave esquerda (“{”)

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

  • Circunflexo ("^")

  • Chave direita (“}")

  • Caractere de porcentagem (“%")

  • Crase (“`")

  • Colchete direito (“]")

  • Pontos de interrogação

  • Sinal de maior (“>")

  • Colchete esquerdo (“[")

  • Til (“~")

  • Sinal de menor ("<")

  • Caractere 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) 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 equivalentes:

  • ' como &apos;

  • ” como &quot;

  • & como &amp;

  • < como &lt;

  • > como &gt;

  • \r como &#13; ou &#x0D;

  • \n como &#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 (onde \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>