Partilhar via

Listar diretórios e arquivos

  • Artigo

A operação List Directories and Files retorna uma lista de arquivos ou diretórios no compartilhamento ou diretório especificado. Ele lista o conteúdo apenas para um único nível da hierarquia de diretórios. Esta operação é suportada na versão 2025-05-05 e posterior para Partilhas de Ficheiros com o protocolo NFS ativado.

Disponibilidade do protocolo

Protocolo de compartilhamento de arquivos habilitado Disponível
PME Sim
NFS Sim

Solicitar

A solicitação List Directories and Files é construída da seguinte forma. Recomendamos que você use HTTPS.

Método Solicitar URI Versão HTTP
OBTER https://myaccount.file.core.windows.net/myshare/mydirectorypath?restype=directory&comp=list HTTP/1.1
OBTER https://myaccount.file.core.windows.net/myshare/mydirectorypath?restype=directory&sharesnapshot=<DateTime>&comp=list HTTP/1.1

Substitua os componentes de caminho mostrados no URI de solicitação pelo seu, da seguinte maneira:

Componente Caminho Descrição
myaccount O nome da sua conta de armazenamento.
myshare O nome do seu compartilhamento de arquivos.
mydirectorypath O caminho para o diretório.

Para obter detalhes sobre restrições de nomenclatura de caminho, consulte Nomeando e referenciando compartilhamentos, diretórios, arquivos e metadados.

Parâmetros de URI

Você pode especificar os seguintes parâmetros adicionais no URI.

Parâmetros comuns de URI

Parâmetro Descrição
prefix Opcional. Versão 2016-05-31 e posterior. Filtra os resultados para retornar somente arquivos e diretórios com nomes que começam com o prefixo especificado.
sharesnapshot Opcional. Versão 2017-04-17 e posterior. O parâmetro share snapshot é um valor DateTime opaco que, quando presente, especifica o snapshot de compartilhamento para consultar a lista de arquivos e diretórios.
marker Opcional. Um valor de cadeia de caracteres que identifica a parte da lista a ser retornada com a próxima operação de lista. A operação retorna um valor de marcador dentro do corpo da resposta se a lista retornada não estiver completa. Em seguida, você pode usar o valor do marcador em uma chamada subsequente para solicitar o próximo conjunto de itens de lista.

O valor do marcador é opaco para o cliente.
maxresults Opcional. Especifica o número máximo de arquivos ou diretórios a serem retornados. Se a solicitação não especificar maxresultsou especificar um valor maior que 5.000, o servidor retornará até 5.000 itens.

Definir maxresults para um valor menor ou igual a zero resulta no código de resposta de erro 400 (Solicitação incorreta).
timeout Opcional. O parâmetro timeout é expresso em segundos. Para obter mais informações, consulte Definindo tempos limite para operações do Azure Files.

Parâmetros URI somente SMB

Parâmetro Descrição
include={Timestamps, ETag, Attributes, PermissionKey} Opcionalmente disponível, a partir da versão 2020-04-08. Especifica uma ou mais propriedades a serem incluídas na resposta:
  • Timestamps
  • ETag
  • Attributes (atributos de arquivo Win32)
  • PermissionKey

Para especificar mais de uma dessas opções no URI, você deve separar cada opção com uma vírgula codificada por URL (%82).

O cabeçalho x-ms-file-extended-info é implicitamente assumido como verdadeiro quando esse parâmetro é especificado.

Parâmetros URI somente NFS

Nenhuma.

Cabeçalhos de solicitação

Os cabeçalhos de solicitação obrigatórios e opcionais são descritos nas tabelas a seguir:

Cabeçalhos de solicitação comuns

Cabeçalho da solicitação Descrição
Authorization Necessário. Especifica o esquema de autorização, o nome da conta e a assinatura. Para obter mais informações, consulte Autorizar solicitações para o Armazenamento do Azure.
Date ou x-ms-date Necessário. Especifica o Tempo Universal Coordenado (UTC) para a solicitação. Para obter mais informações, consulte Autorizar solicitações para o Armazenamento do Azure.
x-ms-version Obrigatório para todos os pedidos autorizados. Especifica a versão da operação a ser usada para essa solicitação. Esta operação é suportada na versão 2025-05-05 e posterior para Partilhas de Ficheiros com o protocolo NFS ativado.

Para obter mais informações, consulte controle de versão para os serviços de Armazenamento do Azure.
x-ms-client-request-id Opcional. Fornece um valor opaco gerado pelo cliente com um limite de caracteres de 1 kibibyte (KiB) que é registrado nos logs quando o log é configurado. É altamente recomendável que você use esse cabeçalho para correlacionar atividades do lado do cliente com solicitações que o servidor recebe. Para obter mais informações, consulte Monitorar arquivos do Azure.
x-ms-file-request-intent Obrigatório se Authorization cabeçalho especificar um token OAuth. O valor aceitável é backup. Este cabeçalho especifica que os Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action ou Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action devem ser concedidos se forem incluídos na política RBAC atribuída à identidade autorizada usando o cabeçalho Authorization. Disponível para a versão 2022-11-02 e posterior.
x-ms-allow-trailing-dot: { <Boolean> } Opcional. Versão 2022-11-02 e posterior. O valor booleano especifica se um ponto à direita presente na url da solicitação deve ser cortado ou não.

Esse cabeçalho será ignorado se o destino estiver localizado em um compartilhamento de arquivos com o protocolo NFS habilitado, que oferece suporte a pontos à direita por padrão.

Para obter mais informações, consulte Nomeando e referenciando compartilhamentos, diretórios, arquivos e metadados.

Cabeçalhos de solicitação somente SMB

Cabeçalho da solicitação Descrição
x-ms-file-extended-info: {true} Opcional. Versão 2020-04-08 e posterior. Este cabeçalho é implicitamente assumido como verdadeiro se o parâmetro de consulta include não estiver vazio. Se verdadeiro, a propriedade Content-Length para arquivos que indica o tamanho do arquivo estará atualizada.

Cabeçalhos de solicitação somente NFS

Nenhuma.

Corpo do pedido

Nenhuma.

Resposta

A resposta inclui um código de status HTTP, um conjunto de cabeçalhos de resposta e um corpo de resposta em formato XML.

Código de status

Uma operação bem-sucedida retorna o código de status 200 (OK). Para obter informações sobre códigos de status, consulte Códigos de status e de erro.

Cabeçalhos de resposta

A resposta para esta operação inclui os cabeçalhos nas tabelas a seguir. A resposta também pode incluir cabeçalhos HTTP padrão adicionais. Todos os cabeçalhos padrão estão em conformidade com a especificação do protocolo HTTP/1.1.

Cabeçalhos de resposta comuns

Cabeçalho da resposta Descrição
Content-Type Especifica o formato no qual os resultados são retornados. Atualmente este valor é application/xml.
x-ms-request-id Esse cabeçalho identifica exclusivamente a solicitação que foi feita e pode ser usado para solucionar problemas da solicitação. Para obter mais informações, consulte Solução de problemas de operações de API.
x-ms-version Indica a versão dos Arquivos do Azure usada para executar a solicitação.
Date ou x-ms-date Um valor de data/hora UTC que indica a hora em que a resposta foi iniciada. O serviço gera esse valor.
x-ms-client-request-id Você pode usar esse cabeçalho para solucionar problemas de solicitações e respostas correspondentes. O valor desse cabeçalho é igual ao valor do cabeçalho x-ms-client-request-id, se ele estiver presente na solicitação. O valor é, no máximo, 1024 caracteres ASCII visíveis. Se o cabeçalho x-ms-client-request-id não estiver presente na solicitação, esse cabeçalho não estará presente na resposta.

Cabeçalhos de resposta somente SMB

Nenhuma.

Cabeçalhos de resposta somente NFS

Nenhuma.

Corpo de resposta

O formato da resposta XML é o seguinte.

Os elementos Marker, ShareSnapshote MaxResults estarão presentes somente se você especificá-los no URI da solicitação. O elemento NextMarker tem um valor somente se os resultados da lista não estiverem completos.

O elemento Content-Length é retornado na listagem de arquivos, que indica o tamanho do arquivo. No entanto, esse valor pode não estar up-to-date, porque um cliente SMB ou NFS pode ter modificado o arquivo localmente. O valor de Content-Length pode não refletir esse fato até que o identificador seja fechado ou o bloqueio operacional SMB seja quebrado. Para recuperar valores de propriedade atuais, use x-ms-file-extended-info: true para um diretório localizado em um Compartilhamento de Arquivos com o protocolo SMB habilitado ou chame Obter Propriedades do Arquivo no arquivo específico.

Nas versões 2021-12-02 e mais recentes, List Directory and Files codificará percentualmente (por RFC 2396) todos os valores de elementos FileName, DirectoryName, Prefix ou DirectoryPath que contenham caracteres inválidos em XML (especificamente, U+FFFE ou U+FFFF). Se codificado, o elemento Name, Prefix ou EnumerationResults incluirá um atributo Encoded=true. Isso ocorre apenas para os valores do elemento Name que contêm os caracteres inválidos em XML, não para os elementos Name restantes na resposta.

Corpo de resposta para compartilhamentos de arquivos com o protocolo SMB habilitado

<?xml version="1.0" encoding="utf-8"?>  
<EnumerationResults ServiceEndpoint="https://myaccount.file.core.windows.net/" ShareName="myshare" ShareSnapshot="date-time" DirectoryPath="directory-path">  
  <Marker>string-value</Marker>
  <Prefix>string-value</Prefix>
  <MaxResults>int-value</MaxResults>
  <DirectoryId>directory-id</DirectoryId>
  <Entries>
    <File>
      <FileId>file-id</FileId>
      <Name>file-name</Name>  
      <Properties>  
        <Content-Length>size-in-bytes</Content-Length>
        <CreationTime>datetime</CreationTime>
        <LastAccessTime>datetime</LastAccessTime>
        <LastWriteTime>datetime</LastWriteTime>
        <ChangeTime>datetime</ChangeTime>
        <Last-Modified>datetime</Last-Modified>
        <Etag>etag</Etag>
      </Properties>
      <Attributes>Archive|Hidden|Offline|ReadOnly</Attributes>
      <PermissionKey>4066528134148476695*1</PermissionKey>
    </File>  
    <Directory>
      <FileId>file-id</FileId>
      <Name>directory-name</Name>  
      <Properties>
        <CreationTime>datetime</CreationTime>
        <LastAccessTime>datetime</LastAccessTime>
        <LastWriteTime>datetime</LastWriteTime>
        <ChangeTime>datetime</ChangeTime>
        <Last-Modified>datetime</Last-Modified>
        <Etag>etag</Etag>
      </Properties>
      <Attributes>Archive|Hidden|Offline|ReadOnly</Attributes>
      <PermissionKey>4066528134148476695*1</PermissionKey>
    </Directory>  
  </Entries>  
  <NextMarker />  
</EnumerationResults>

Nas versões 2020-04-08, 2020-06-12 e 2020-08-04, FileId é retornado para arquivos e diretórios se o cabeçalho x-ms-file-extended-info for verdadeiro. Na versão 2020-10-02 e posterior, FileId é sempre retornado para arquivos e diretórios.

Na versão 2020-04-08, include={timestamps} retorna as seguintes propriedades de carimbo de data/hora: CreationTime, LastAccessTimee LastWriteTime. Na versão 2020-06-12 e posterior, include={timestamps} retorna as seguintes propriedades de carimbo de data/hora: CreationTime, LastAccessTime, LastWriteTime, ChangeTimee Last-Modified.

Na versão 2020-10-02 e posterior, DirectoryId é retornado na resposta. Ele especifica a FileId do diretório no qual a API está sendo chamada.

Corpo de resposta para compartilhamentos de arquivos com o protocolo NFS habilitado

<?xml version="1.0" encoding="utf-8"?>
<EnumerationResults ServiceEndpoint="https://myaccount.file.core.windows.net/" ShareName="myshare" ShareSnapshot="date-time" DirectoryPath="directory-path">
  <Marker>string-value</Marker>
  <Prefix>string-value</Prefix>
  <MaxResults>int-value</MaxResults>
  <DirectoryId>directory-id</DirectoryId>
  <Entries>
    <File>
      <FileId>file-id</FileId>
      <Name>file-name</Name>
      <Properties>
        <Content-Length>size-in-bytes</Content-Length>
      </Properties>
    </File>
    <Directory>
      <FileId>file-id</FileId>
      <Name>directory-name</Name>
    </Directory>
  </Entries>
  <NextMarker />
</EnumerationResults>

Formato datetime e versão da API para campos de carimbo de data/hora

Elemento Formato datetime Valor da amostra Versão da API
CreationTime Certificação ISO 8601 2020-09-17T13:38:03.2740000Z 2020-04-08 e seguintes
LastAccessTime Certificação ISO 8601 2020-09-17T13:38:03.2740000Z 2020-04-08 e seguintes
LastWriteTime Certificação ISO 8601 2020-09-17T13:38:03.2740000Z 2020-04-08 e seguintes
ChangeTime Certificação ISO 8601 2020-09-17T13:38:03.2740000Z 2020-06-12 e seguintes
Last-Modified RFC 1123 [en] Thu, 17 Sep 2020 13:38:07 GMT 2020-06-12 e seguintes

Autorização

Somente o proprietário da conta pode chamar essa operação.

Comentários

O valor retornado no elemento Content-Length corresponde ao valor do cabeçalho x-ms-content-length do arquivo.

Cada elemento Directory retornado conta para o resultado máximo, assim como cada elemento File. Arquivos e diretórios são listados misturados, em ordem lexicamente ordenada no corpo da resposta.

A listagem é limitada a um único nível da hierarquia de diretórios. Para listar vários níveis, você pode fazer várias chamadas de maneira iterativa. Use o valor Directory retornado de um resultado em uma chamada subsequente para List Directories and Files.

Ver também

Operações em Diretórios