Nomenclatura e referência de compartilhamentos, diretórios, arquivos e metadados

  • Artigo

Uma conta de armazenamento pode conter zero ou mais compartilhamentos de arquivos do Azure. Um compartilhamento contém propriedades, metadados e zero ou mais arquivos ou diretórios. Um diretório contém propriedades e zero ou mais arquivos ou diretórios. Um arquivo é qualquer entidade contendo dados binários, propriedades e metadados.

Nomes de recurso

O URI para fazer referência a um compartilhamento, diretório ou arquivo deve ser exclusivo. Dentro de uma determinada conta de armazenamento, cada compartilhamento deve ter um nome exclusivo. Cada arquivo dentro de um determinado compartilhamento ou diretório deve ter um nome exclusivo dentro desse compartilhamento ou diretório.

Se você tentar criar um compartilhamento, diretório ou arquivo com um nome que viola as regras de nomenclatura, a solicitação falhará com um código de status 400 (Solicitação Incorreta).

Compartilhar nomes

As regras para os nomes de compartilhamento do serviço de arquivo são mais restritivas do que é prescrito pelo protocolo SMB para nomes de compartilhamento SMB, para que os serviços de Blob e arquivos possam compartilhar convenções de nomenclatura semelhantes para contêiners e compartilhamentos. As restrições de nomenclatura para os compartilhamentos são os seguintes:

  • Um nome de compartilhamento deve ter um nome DNS válido.
  • Os nomes de compartilhamento devem começar com uma letra ou número e podem conter apenas letras, números e o caractere hífen/subtração (-).
  • Cada caractere hifen/menos (-) deve ser imediatamente precedido e seguido por uma letra ou número; Hífens consecutivos não são permitidos em nomes de compartilhamento.
  • Todas as letras em um nome compartilhado deve estar em letra minúscula.
  • Os nomes compartilhados devem ter de 3 a 63 caracteres de comprimento.

A tabela a seguir compara as restrições de nomenclatura para Arquivos do Azure e armazenamento de Blobs do Azure:

Nomeando e referenciando contêineres, blobs e metadados Restrições de nome de compartilhamento SMB
• Um nome de contêiner deve ser um nome DNS válido.
• Os nomes de contêiner devem começar com uma letra ou número e podem conter apenas letras, números e o caractere hífen/subtração (-).
• Cada caractere hífen/subtração (-) deve ser imediatamente precedido e seguido por uma letra ou número; Hífens consecutivos não são permitidos em nomes de contêiner.
• Todas as letras em um nome de contêiner devem ser minúsculas.
• Os nomes de contêiner devem ter de 3 a 63 caracteres.		 • Um nome de compartilhamento não deve ter mais de 80 caracteres de comprimento.
• Os seguintes caracteres são ilegais em um nome de compartilhamento: \ / [ ] : ¦ < > + = ; , * ? "
• Os caracteres de controle no intervalo 0x00 até 0x1F, inclusive, são ilegais em um nome de compartilhamento.
• Todos os outros caracteres Unicode são legais.
• Os nomes são de preservação de maiúsculas e minúsculas.

Nomes de diretório e arquivo

Arquivos do Azure impõe as seguintes regras de nomenclatura para nomes de diretório e arquivo:

  • Os nomes de diretório e arquivo preservam e diferenciam maiúsculas e minúsculas.
  • Os nomes do componente de arquivo e diretório não devem ter mais de 255 caracteres de comprimento.
  • Os nomes de diretório não podem terminar com o caractere de barra (/). Se fornecido, será removido automaticamente.
  • Os nomes de arquivo não devem terminar com um caractere de barra (/).
  • Os caracteres reservados de URL precisam ser escapados corretamente.
  • Os seguintes caracteres não são permitidos: " \ / : | < > * ?
  • Caracteres ilegais de caminho de URL não são permitidos. Pontos de código como \uE000, embora válidos em nomes de arquivo NTFS, não são caracteres Unicode válidos. Além disso, alguns caracteres ASCII ou Unicode, como caracteres de controle (0x00 para 0x1F), também não são permitidos. Para regras que regem cadeias de caracteres Unicode em HTTP/1.1 , consulte RFC 2616, Seção 2.2: Regras Básicas e RFC 3987.
  • Não há suporte para caracteres Unicode inválidos (chamados de pares alternativos inválidos).
  • Os seguintes nomes de arquivo não são permitidos: LPT1, LPT2, LPT3, LPT4, LPT5, LPT6, LPT7, LPT8, LPT9, COM1, COM2, COM3, COM4, COM5, COM6, COM7, COM8, COM9, PRN, AUX, NUL, CON, CLOCK$, caractere de ponto (.) e dois caracteres de ponto (..).
  • A partir da versão 2021-12-02, os nomes de diretório e arquivo dão suporte a caracteres U+FFFE e U+FFFF em todas as operações. Esses caracteres também têm suporte por meio de protocolos SMB e REST. As operações List Directory e Files e List Handles precisarão de tratamento especial para esses caracteres, conforme mencionado em sua respectiva documentação.

Por padrão, caracteres de ponto (.) no final do diretório e nomes de arquivo em URLs de solicitação são ignorados ou deixados de fora.

  • Por exemplo, se um arquivo chamado file1... estiver sendo criado, os pontos no final serão ignorados e um arquivo chamado file1 será criado. O mesmo se aplica a diretórios no caminho. Se uma solicitação de criação de arquivo incluir o caminho \Dir1\Dir2…\File1 , o arquivo será criado em \Dir1\Dir2\File1.
  • No entanto, a partir da versão 2022-11-02, o comportamento padrão pode ser substituído definindo o cabeçalho x-ms-allow-trailing-dot como true na solicitação de URL.
  • Por exemplo, se você quiser criar um arquivo chamado file1... e incluir os pontos à direita, o x-ms-allow-trailing-dot deverá ser incluído no cabeçalho da solicitação e definido como true. O mesmo se aplica à criação de nomes de diretório.
  • No caso de uma solicitação de cópia de arquivo, se você quiser incluir pontos à direita no nome do arquivo de origem, o x-ms-source-allow-trailing-dot cabeçalho deverá ser definido como true. Para obter mais informações, marcar as opções de cabeçalho disponíveis para cada API REST individual.

A tabela a seguir compara as restrições de nomenclatura para Arquivos do Azure e armazenamento de Blobs do Azure:

Nomeando e referenciando contêineres, blobs e metadados Restrições de nome de protocolo SMB
• Um nome de blob deve ter pelo menos um caractere e não pode ter mais de 1.024 caracteres.
• Os nomes de blob diferenciam maiúsculas de minúsculas.
• Os caracteres de URL reservados devem ser escapados corretamente.
• Os nomes de blob podem terminar com um delimitador de diretório virtual, como uma barra (/)
• Caracteres de caminho de URL ilegais não permitidos: pontos de código como \uE000, embora válidos em nomes de arquivo NTFS, não são caracteres Unicode válidos. Além disso, alguns caracteres ASCII ou Unicode, como caracteres de controle (0x00 para 0x1F), também não são permitidos. Para regras que regem cadeias de caracteres Unicode em HTTP/1.1 , consulte RFC 2616, Seção 2.2: Regras Básicas e RFC 3987.		 • Um nome de caminho pode ter no máximo 32.760 caracteres de comprimento.
• Cada componente de nome de caminho (arquivo/diretório) pode ter no máximo 255 caracteres de comprimento.
• Um nome de caminho é composto por um ou mais componentes de nome de caminho separados pelo caractere de barra (\) para trás.
• O nome do caminho é a preservação de maiúsculas e minúsculas (dois nomes que diferem apenas caso não seja permitido).
• Não é possível ter um caminho de diretório igual a um caminho de arquivo.
• Os seguintes caracteres são ilegais em um nome de componente: \ / : ¦ < > * ? "
• Os caracteres de controle no intervalo 0x00 até 0x1F, inclusive, são ilegais em um nome de compartilhamento.

Nomes de caminho

Um nome de caminho é composto por um ou mais componentes de nome de caminho (diretório ou nome de arquivo) separados pelo caractere de barra de encaminhamento (/). Todos os componentes de nome de caminho que não sejam o componente de nome do último caminho denotam diretórios. O último componente de nome de caminho indica um diretório ou um arquivo. As seguintes regras de nomenclatura são aplicadas:

  • Um nome de caminho pode ter no máximo 2.048 caracteres de comprimento. Os componentes individuais no caminho podem ter no máximo 255 caracteres de comprimento.
  • Um nome de caminho é composto por um ou mais componentes de nome de caminho separados pelo caractere de barra de encaminhamento (/).
  • A profundidade dos subdiretórios no caminho não pode exceder 250.
  • O mesmo nome não pode ser usado para um arquivo e um diretório que compartilham o mesmo diretório pai. Por exemplo, um arquivo e um diretório nomeados data não podem existir no mesmo caminho pai.

Nomes de metadados

Os metadados para um recurso de arquivos ou compartilhado são armazenados como pares com valor de nome associados a um recurso. Os nomes de metadados devem seguir as regras de nomenclatura para identificadores C#.

Observe que os nomes de metadados preservam a forma com a qual foram criados, mas não diferenciam maiúsculas de minúsculas quando definidos ou lidos. Se dois ou mais cabeçalhos de metadados com o mesmo nome forem enviados para um recurso, o serviço do Azure File retornará o código de status 400 (Solicitação Incorreta).

Sintaxe do URI do recurso

Cada recurso tem um URI base correspondente, que se refere ao próprio recurso. Para a conta de armazenamento, o URI base inclui apenas o nome da conta:

https://myaccount.file.core.windows.net

Para um compartilhamento, a URI base inclui o nome da conta e o nome do compartilhamento:

https://myaccount.file.core.windows.net/myshare

Para um diretório, a URI base inclui o nome da conta, o nome do compartilhamento e o caminho do diretório:

https://myaccount.file.core.windows.net/myshare/myparentdir/mydir

Para um arquivo, a URI base inclui o nome da conta, o nome do compartilhamento e o caminho do arquivo:

https://myaccount.file.core.windows.net/myshare/myfile  
https://myaccount.file.core.windows.net/myshare/mydir/myfile  
https://myaccount.file.core.windows.net/myshare/myparentdir/mydir/myfile

Confira também