Listar Diretórios e Ficheiros

Artigo
03/29/2023

A List Directories and Files operação devolve uma lista de ficheiros ou diretórios na partilha ou diretório especificado. Lista os conteúdos apenas para um único nível da hierarquia de diretórios.

Disponibilidade do protocolo

Protocolo de partilha de ficheiros ativado	Disponível
SMB
NFS

Pedir

Pode construir o pedido da List Directories and Files seguinte forma. É recomendado HTTPS.

Método	URI do pedido	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 de caminho apresentados no URI do pedido pelo seu, da seguinte forma:

Componente caminho	Description
`myaccount`	O nome da sua conta de armazenamento.
`myshare`	O nome da partilha de ficheiros.
`mydirectorypath`	O caminho para o diretório.

Para obter detalhes sobre as restrições de nomenclatura de caminhos, veja Nomenclatura e referência de partilhas, diretórios, ficheiros e metadados.

Parâmetros URI

Pode especificar os seguintes parâmetros adicionais no URI.

Parâmetro	Description
`prefix`	Opcional. Versão 2016-05-31 e posterior. Filtra os resultados para devolver apenas ficheiros e diretórios que tenham nomes que comecem pelo prefixo especificado.
`sharesnapshot`	Opcional. Versão 2017-04-17 e posterior. O parâmetro de instantâneo de partilha é um valor opaco `DateTime` que, quando presente, especifica o instantâneo de partilha a consultar para a lista de ficheiros e diretórios.
`marker`	Opcional. Um valor de cadeia que identifica a parte da lista a devolver com a operação de lista seguinte. A operação devolve um valor de marcador no corpo da resposta se a lista devolvida não tiver sido concluída. Em seguida, pode utilizar o valor do marcador numa chamada subsequente para pedir 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 ficheiros ou diretórios a devolver. Se o pedido não especificar `maxresults`ou especificar um valor superior a 5000, o servidor devolverá até 5000 itens. Definir `maxresults` para um valor inferior ou igual a zero resulta no código de resposta de erro 400 (Pedido Incorreto).
`include={Timestamps, ETag, Attributes, PermissionKey}`	Opcionalmente disponível, a partir da versão 2020-04-08. Especifica uma ou mais propriedades a incluir na resposta: `Timestamps` `ETag` `Attributes` (Atributos de ficheiro Win32) `PermissionKey` Para especificar mais do que uma destas opções no URI, tem de separar cada opção com uma vírgula codificada por URL (`%82`). Assume-se implicitamente que o cabeçalho `x-ms-file-extended-info` é verdadeiro quando este parâmetro é especificado.
`timeout`	Opcional. O `timeout` parâmetro é expresso em segundos. Para obter mais informações, veja Setting timeouts for Ficheiros do Azure operations (Definir tempos limite para operações de Ficheiros do Azure).

Cabeçalhos do pedido

A tabela seguinte descreve os cabeçalhos de pedido obrigatórios e opcionais.

Cabeçalho do pedido	Description
`Authorization`	Obrigatório. Especifica o esquema de autorização, o nome da conta e a assinatura. Para obter mais informações, veja Autorizar pedidos para o Armazenamento do Azure.
`Date` ou `x-ms-date`	Obrigatório. Especifica a Hora Universal Coordenada (UTC) do pedido. Para obter mais informações, veja Autorizar pedidos para o Armazenamento do Azure.
`x-ms-version`	Necessário para todos os pedidos autorizados, opcional para pedidos anónimos. Especifica a versão da operação a utilizar para este pedido. Para obter mais informações, veja Controlo de versões dos serviços de Armazenamento do Azure.
`x-ms-client-request-id`	Opcional. Fornece um valor opaco gerado pelo cliente com um limite de carateres de 1 kibibyte (KiB) que é registado nos registos quando o registo é configurado. Recomendamos vivamente que utilize este cabeçalho para correlacionar as atividades do lado do cliente com os pedidos que o servidor recebe. Para obter mais informações, veja Monitorizar Ficheiros do Azure.
`x-ms-file-extended-info: {true}`	Opcional. Versão 2020-04-08 e posterior. Este cabeçalho é implicitamente considerado verdadeiro se o `include` parâmetro de consulta não estiver vazio. Se for verdade, a `Content-Length` propriedade estará atualizada. Nas versões 2020-04-08, 2020-06-12 e 2020-08-04, `FileId` só é devolvido para ficheiros e diretórios se este cabeçalho for verdadeiro. Nas versões 2020-10-02 e posterior, `FileId` é sempre devolvido para ficheiros e diretórios.
`x-ms-file-request-intent`	Necessário se o `Authorization` cabeçalho especificar um token OAuth. O valor aceitável é `backup`. Este cabeçalho especifica que o `Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action` ou `Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action` deve ser concedido se estiverem incluídos na política RBAC atribuída à identidade autorizada com 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 booleano especifica se um ponto à direita presente no URL do pedido deve ser cortado ou não. Para obter mais informações, veja Nomenclatura e referência de partilhas, diretórios, ficheiros e metadados.

Corpo do pedido

Nenhum.

Resposta

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

Código de estado

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

Cabeçalhos de resposta

A resposta para esta operação inclui os seguintes cabeçalhos. 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 no qual os resultados são devolvidos. Atualmente, este valor é `application/xml`.
`x-ms-request-id`	Este cabeçalho identifica exclusivamente o pedido que foi feito e pode ser utilizado para resolver o pedido. Para obter mais informações, veja Resolver problemas de operações da API.
`x-ms-version`	Indica a versão do Ficheiros do Azure utilizado para executar o pedido.
`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 este valor.
`x-ms-client-request-id`	Pode utilizar este cabeçalho para resolver problemas de pedidos e respostas correspondentes. O valor deste cabeçalho é igual ao valor do `x-ms-client-request-id` cabeçalho, se estiver presente no pedido. O valor é, no máximo, 1024 carateres ASCII visíveis. Se o `x-ms-client-request-id` cabeçalho não estiver presente no pedido, este cabeçalho não estará presente na resposta.

Corpo da resposta

O formato da resposta XML é o seguinte.

Tenha em atenção que os Markerelementos , ShareSnapshote MaxResults só estão presentes se os especificar no URI do pedido. O NextMarker elemento só tem um valor 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>

Tenha em atenção que o Content-Length elemento é devolvido na listagem. No entanto, este valor pode não estar atualizado, porque um cliente SMB pode ter modificado o ficheiro localmente. O valor de Content-Length pode não refletir esse facto até que a alça seja fechada ou o bloqueio de operações seja quebrado. Para obter valores de propriedade atuais, utilize x-ms-file-extended-info: trueou chame Obter Propriedades do Ficheiro.

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

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

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

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

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

Apenas o proprietário da conta pode chamar esta operação.

Observações

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

Tenha em atenção que cada Directory elemento devolvido conta para o resultado máximo, tal como cada File elemento. Os ficheiros e diretórios são listados entrelaçados, por ordem lexicamente ordenada no corpo da resposta.

A listagem está limitada a um único nível da hierarquia de diretórios. Para listar vários níveis, pode fazer várias chamadas de forma iterativa. Utilize o Directory valor devolvido de um resultado numa chamada subsequente para List Directories and Files.

Ver também

Operações em diretórios

Partilhar via