Listar diretórios e arquivos

Artigo
03/29/2023

A operação List Directories and Files retorna uma lista de arquivos ou diretórios sob o diretório ou o compartilhamento especificado. Ela lista o conteúdo apenas para um único nível da hierarquia de diretório.

Disponibilidade do protocolo

Protocolo de compartilhamento de arquivos habilitado	Disponível
SMB
NFS

Solicitação

Você pode construir a solicitação da List Directories and Files seguinte maneira. HTTPS é recomendado.

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

Substitua os componentes do caminho mostrados no URI da solicitação pelos seus próprios, como segue:

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

Para obter detalhes sobre restrições de nomenclatura de caminho, consulte Nomenclatura e referência de compartilhamentos, diretórios, arquivos e metadados.

Parâmetros do URI

Você pode especificar os seguintes parâmetros adicionais no 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 instantâneo de compartilhamento é um valor opaco `DateTime` que, quando presente, especifica o instantâneo 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 na 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 ao cliente.
`maxresults`	Opcional. Especifica o número máximo de arquivos ou diretórios a serem retornados. Se a solicitação não especificar `maxresults`ou especificar um valor maior que 5.000, o servidor retornará até 5.000 itens. A configuração de `maxresults` com um valor menor ou igual a zero resulta em um código de resposta de erro 400 (Solicitação Incorreta).
`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.
`timeout`	Opcional. O parâmetro `timeout` é expresso em segundos. Para obter mais informações, consulte Configurando tempos limite para operações de Arquivos do Azure.

Cabeçalhos da solicitação

A tabela a seguir descreve os cabeçalhos de solicitação obrigatórios e opcionais.

Cabeçalho da solicitação	Descrição
`Authorization`	Obrigatórios. Especifica o esquema de autorização, o nome da conta e a assinatura. Para saber mais, confira Autorizar solicitações para o Armazenamento do Azure.
`Date` ou `x-ms-date`	Obrigatórios. Especifica o UTC (Tempo Universal Coordenado) para a solicitação. Para saber mais, confira Autorizar solicitações para o Armazenamento do Azure.
`x-ms-version`	Necessário para todas as solicitações autorizadas, opcional para solicitações anônimas. Especifica a versão da operação a ser usada para esta solicitação. 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-extended-info: {true}`	Opcional. Versão 2020-04-08 e posterior. Esse cabeçalho será implicitamente considerado verdadeiro se o `include` parâmetro de consulta não estiver vazio. Se for true, a `Content-Length` propriedade estará atualizada. Nas versões 2020-04-08, 2020-06-12 e 2020-08-04, `FileId` só será retornado para arquivos e diretórios se esse cabeçalho for verdadeiro. Nas versões 2020-10-02 e posteriores, `FileId` sempre é retornado para arquivos e diretórios.
`x-ms-file-request-intent`	Obrigatório se `Authorization` o cabeçalho especificar um token OAuth. O valor aceitável é `backup`. Esse cabeçalho especifica que o `Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action` ou `Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action` deve ser concedido se eles estiverem incluídos na política RBAC atribuída à identidade autorizada usando o `Authorization` cabeçalho . 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. Para obter mais informações, consulte Nomenclatura e referência de compartilhamentos, diretórios, arquivos e metadados.

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 Códigos de status e de erro.

Cabeçalhos de resposta

A resposta para esta operação inclui os cabeçalhos 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çalho de resposta	Descrição
`Content-Type`	Especifica o formato em que os resultados são retornados. Atualmente, esse 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 do 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 `x-ms-client-request-id` cabeçalho, se ele estiver presente na solicitação. O valor é no máximo 1024 caracteres ASCII visíveis. Se o `x-ms-client-request-id` cabeçalho não estiver presente na solicitação, esse cabeçalho não estará presente na resposta.

Corpo da resposta

O formato da resposta XML é mostrado a seguir.

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

<?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>

Observe que o elemento Content-Length é retornado na lista. No entanto, esse valor pode não estar atualizado, pois um cliente SMB 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 de operação seja quebrado. Para recuperar valores de propriedade atuais, use x-ms-file-extended-info: trueou chame Obter Propriedades do Arquivo.

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 posteriores, 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.

Nas versões 2021-12-02 e mais recentes, List Directory and Files o codificará por porcentagem (por RFC 2396) todos osNameFile valores de elemento , DirectoryNameou PrefixDirectoryPath que contêm caracteres inválidos em XML (especificamente, U+FFFE ou U+FFFF). Se codificado, o Nameelemento ou PrefixEnumerationResults incluirá um Encoded=true atributo . Observe que isso só ocorrerá para os valores de Name elemento que contêm os caracteres inválidos em XML, não os elementos restantes Name na resposta.

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

Elemento	Formato de data/hora	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.

Comentários

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

Observe que cada elemento Directory retornado conta para o resultado máximo, assim como cada elemento File. 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 Directory valor retornado de um resultado em uma chamada subsequente para List Directories and Files.

Confira também

Operações em diretórios