Compartilhar 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ório. Essa operação tem suporte na versão 2025-05-05 e posterior para Compartilhamentos de Arquivos com o protocolo NFS habilitado.

Disponibilidade do protocolo

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

Pedir

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

Método URI de solicitação 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 da solicitação por seus próprios, da seguinte maneira:

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

Para obter detalhes sobre restrições de nomenclatura de caminho, consulte Nomenclatura e referência a 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 apenas arquivos e diretórios que têm nomes que começam com o prefixo especificado.
sharesnapshot Opcional. Versão 2017-04-17 e posterior. O parâmetro de instantâneo de compartilhamento é um valor opaco DateTime que, quando presente, especifica o instantâneo de compartilhamento a ser consultado para 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 retornará um valor de marcador dentro do corpo da resposta se a lista retornada não estiver concluída. 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 como um valor menor ou igual a zero resulta em 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 Definir tempos limite para operações de Arquivos do Azure.

Parâmetros de URI somente SMB

Parâmetro Descrição
include={Timestamps, ETag, Attributes, PermissionKey} Opcionalmente disponível, começando na 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 em URL (%82).

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

Parâmetros de URI somente NFS

Nenhum.

Cabeçalhos de solicitação

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

Cabeçalhos de solicitação comuns

Cabeçalho de 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 UTC (Tempo Universal Coordenado) para a solicitação. Para obter mais informações, consulte Autorizar solicitações para o Armazenamento do Azure.
x-ms-version Necessário para todas as solicitações autorizadas. Especifica a versão da operação a ser usada para essa solicitação. Essa operação tem suporte na versão 2025-05-05 e posterior para Compartilhamentos de Arquivos com o protocolo NFS habilitado.

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 kib (1 kibibyte) que é registrado nos logs quando o registro em log é configurado. É altamente recomendável que você use esse cabeçalho para correlacionar atividades do lado do cliente com solicitações recebidas pelo servidor. Para obter mais informações, consulte Monitorar arquivos do Azure.
x-ms-file-request-intent Necessário se Authorization cabeçalho especificar um token OAuth. O valor aceitável é backup. Esse 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 booliano 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, o que dá suporte ao ponto à direita por padrão.

Para obter mais informações, consulte Nomenclatura e referência a compartilhamentos, diretórios, arquivos e metadados.

Cabeçalhos de solicitação somente SMB

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

Cabeçalhos de solicitação somente NFS

Nenhum.

Corpo da solicitação

Nenhum.

Resposta

A resposta inclui um código de status HTTP, um conjunto de cabeçalhos de resposta e um corpo de resposta no 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 Status e códigos de erro.

Cabeçalhos de resposta

A resposta dessa 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 de protocolo HTTP/1.1 .

Cabeçalhos de resposta comuns

Cabeçalho de resposta Descrição
Content-Type Especifica o formato no qual os resultados são retornados. Atualmente, esse valor está application/xml.
x-ms-request-id Esse cabeçalho identifica exclusivamente a solicitação 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

Nenhum.

Cabeçalhos de resposta somente NFS

Nenhum.

Corpo da resposta

O formato da resposta XML é o seguinte.

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

O elemento Content-Length é retornado na listagem de arquivos, o que indica o tamanho do arquivo. No entanto, esse valor pode não ser 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 op SMB esteja 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á percentual (por RFC 2396) todos os valores de elemento FileName, DirectoryName, Prefix ou DirectoryPath que contêm 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 de elemento Name que contêm os caracteres inválidos em XML, não os elementos de Name restantes na resposta.

Corpo da 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 será 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 o FileId do diretório no qual a API está sendo chamada.

Corpo da 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 de exemplo Versão da API
CreationTime ISO 8601 2020-09-17T13:38:03.2740000Z 2020-04-08 e posterior
LastAccessTime ISO 8601 2020-09-17T13:38:03.2740000Z 2020-04-08 e posterior
LastWriteTime ISO 8601 2020-09-17T13:38:03.2740000Z 2020-04-08 e posterior
ChangeTime ISO 8601 2020-09-17T13:38:03.2740000Z 2020-06-12 e posterior
Last-Modified RFC 1123 Thu, 17 Sep 2020 13:38:07 GMT 2020-06-12 e posterior

Autorização

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

Observações

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 faz. Arquivos e diretórios são listados intermingled, em ordem lexicamente classificada no corpo da resposta.

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

Consulte também

operações de em diretórios