Condividi tramite

Elencare directory e file

  • Articolo

L'operazione List Directories and Files restituisce un elenco di file o directory nella condivisione o nella directory specificata. Elenca il contenuto solo per un singolo livello della gerarchia di directory. Questa operazione è supportata nella versione 2025-05-05 e successive per condivisioni file con protocollo NFS abilitato.

Disponibilità del protocollo

Protocollo di condivisione file abilitato Disponibile
SMB sì
NFS sì

Richiesta

La richiesta di List Directories and Files viene costruita nel modo seguente. È consigliabile usare HTTPS.

Metodo URI della richiesta Versione HTTP
OTTIENI https://myaccount.file.core.windows.net/myshare/mydirectorypath?restype=directory&comp=list HTTP/1.1
OTTIENI https://myaccount.file.core.windows.net/myshare/mydirectorypath?restype=directory&sharesnapshot=<DateTime>&comp=list HTTP/1.1

Sostituire i componenti del percorso visualizzati nell'URI della richiesta con i propri, come indicato di seguito:

Componente percorso Descrizione
myaccount Nome dell'account di archiviazione.
myshare Nome della condivisione file.
mydirectorypath Percorso della directory.

Per informazioni dettagliate sulle restrizioni di denominazione dei percorsi, vedere Denominazione e riferimento a condivisioni, directory, file e metadati.

Parametri URI

È possibile specificare i parametri aggiuntivi seguenti nell'URI.

Parametri URI comuni

Parametro Descrizione
prefix Opzionale. Versione 2016-05-31 e successive. Filtra i risultati per restituire solo file e directory con nomi che iniziano con il prefisso specificato.
sharesnapshot Opzionale. Versione 2017-04-17 e successive. Il parametro snapshot di condivisione è un valore opaco DateTime che, quando presente, specifica lo snapshot di condivisione su cui eseguire una query per l'elenco di file e directory.
marker Opzionale. Valore stringa che identifica la parte dell'elenco da restituire con l'operazione di elenco successiva. L'operazione restituisce un valore marcatore all'interno del corpo della risposta se l'elenco restituito non è stato completato. È quindi possibile usare il valore del marcatore in una chiamata successiva per richiedere il set successivo di elementi di elenco.

Il valore dell'indicatore è opaco per il client.
maxresults Opzionale. Specifica il numero massimo di file o directory da restituire. Se la richiesta non specifica maxresultso specifica un valore maggiore di 5.000, il server restituisce fino a 5.000 elementi.

Se si imposta maxresults su un valore minore o uguale a zero, viene restituito il codice di risposta di errore 400 (richiesta non valida).
timeout Opzionale. Il parametro timeout è espresso in secondi. Per altre informazioni, vedere Impostazione dei timeout per le operazioni di File di Azure.

Solo parametri URI SMB

Parametro Descrizione
include={Timestamps, ETag, Attributes, PermissionKey} Facoltativamente disponibile, a partire dalla versione 2020-04-08. Specifica una o più proprietà da includere nella risposta:
  • Timestamps
  • ETag
  • Attributes (attributi di file Win32)
  • PermissionKey

Per specificare più di una di queste opzioni nell'URI, è necessario separare ogni opzione con una virgola con codifica URL (%82).

L'intestazione x-ms-file-extended-info viene considerata implicitamente true quando si specifica questo parametro.

Solo parametri URI NFS

Nessuno.

Intestazioni della richiesta

Le intestazioni di richiesta obbligatorie e facoltative sono descritte nelle tabelle seguenti:

Intestazioni di richiesta comuni

Intestazione della richiesta Descrizione
Authorization Obbligatorio. Specifica lo schema di autorizzazione, il nome dell'account e la firma. Per altre informazioni, vedere Autorizzare le richieste ad Archiviazione di Azure.
Date o x-ms-date Obbligatorio. Specifica l'ora UTC (Coordinated Universal Time) per la richiesta. Per altre informazioni, vedere Autorizzare le richieste ad Archiviazione di Azure.
x-ms-version Obbligatorio per tutte le richieste autorizzate. Specifica la versione dell'operazione da utilizzare per questa richiesta. Questa operazione è supportata nella versione 2025-05-05 e successive per condivisioni file con protocollo NFS abilitato.

Per altre informazioni, vedere Controllo delle versioni per i servizi di archiviazione di Azure.
x-ms-client-request-id Opzionale. Fornisce un valore opaco generato dal client con un limite di caratteri di 1 kibibyte (KiB) registrato nei log quando viene configurata la registrazione. È consigliabile usare questa intestazione per correlare le attività sul lato client alle richieste ricevute dal server. Per altre informazioni, vedere Monitorare File di Azure.
x-ms-file-request-intent Obbligatorio se Authorization intestazione specifica un token OAuth. Il valore accettabile è backup. Questa intestazione specifica che il Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action o Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action deve essere concesso se sono inclusi nei criteri di controllo degli accessi in base al ruolo assegnati all'identità autorizzata usando l'intestazione Authorization. Disponibile per la versione 2022-11-02 e successive.
x-ms-allow-trailing-dot: { <Boolean> } Opzionale. Versione 2022-11-02 e successive. Il valore booleano specifica se un punto finale presente nell'URL della richiesta deve essere tagliato o meno.

Questa intestazione viene ignorata se la destinazione si trova in una condivisione file con protocollo NFS abilitato, che supporta il punto finale per impostazione predefinita.

Per altre informazioni, vedere Denominazione e riferimento a condivisioni, directory, file e metadati.

Intestazioni di richiesta solo SMB

Intestazione della richiesta Descrizione
x-ms-file-extended-info: {true} Opzionale. Versione 2020-04-08 e successive. Si presuppone che questa intestazione sia implicitamente true se il parametro di query include non è vuoto. Se true, la proprietà Content-Length per i file che indica le dimensioni del file saranno aggiornate.

Intestazioni di richiesta solo NFS

Nessuno.

Corpo della richiesta

Nessuno.

Risposta

La risposta include un codice di stato HTTP, un set di intestazioni di risposta e un corpo della risposta in formato XML.

Codice di stato

Un'operazione riuscita restituisce il codice di stato 200 (OK). Per informazioni sui codici di stato, vedere Stato e codici di errore.

Intestazioni di risposta

La risposta per questa operazione include le intestazioni nelle tabelle seguenti. La risposta può includere anche intestazioni HTTP standard aggiuntive. Tutte le intestazioni standard sono conformi alla specifica del protocollo HTTP/1.1 .

Intestazioni di risposta comuni

Intestazione della risposta Descrizione
Content-Type Specifica il formato in cui vengono restituiti i risultati. Attualmente questo valore è application/xml.
x-ms-request-id Questa intestazione identifica in modo univoco la richiesta effettuata e può essere usata per la risoluzione dei problemi della richiesta. Per altre informazioni, vedere Risoluzione dei problemi delle operazioni API.
x-ms-version Indica la versione di File di Azure usata per eseguire la richiesta.
Date o x-ms-date Valore di data/ora UTC che indica l'ora in cui è stata avviata la risposta. Il servizio genera questo valore.
x-ms-client-request-id È possibile usare questa intestazione per risolvere i problemi relativi alle richieste e alle risposte corrispondenti. Il valore di questa intestazione è uguale al valore dell'intestazione x-ms-client-request-id, se presente nella richiesta. Il valore è al massimo 1024 caratteri ASCII visibili. Se l'intestazione x-ms-client-request-id non è presente nella richiesta, questa intestazione non sarà presente nella risposta.

Intestazioni di risposta solo SMB

Nessuno.

Intestazioni di risposta solo NFS

Nessuno.

Corpo della risposta

Il formato della risposta XML è il seguente.

Gli elementi Marker, ShareSnapshote MaxResults sono presenti solo se vengono specificati nell'URI della richiesta. L'elemento NextMarker ha un valore solo se i risultati dell'elenco non sono completi.

L'elemento Content-Length viene restituito nell'elenco dei file, che indica le dimensioni del file. Tuttavia, questo valore potrebbe non essere up-to-date, perché un client SMB o NFS potrebbe aver modificato il file in locale. Il valore di Content-Length potrebbe non riflettere tale fatto finché l'handle non viene chiuso o il blocco operativo SMB non viene interrotto. Per recuperare i valori correnti delle proprietà, usare x-ms-file-extended-info: true per una directory che si trova in una condivisione file con protocollo SMB abilitato oppure chiamare Ottenere proprietà file rispetto al file specifico.

Nelle versioni 2021-12-02 e successive, List Directory and Files codifica percentuale (per RFC 2396) tutti i FileName, DirectoryName, Prefix o valori di elemento DirectoryPath che contengono caratteri non validi in XML (in particolare U+FFFE o U+FFFF). Se codificato, l'elemento Name, Prefix o EnumerationResults includerà un attributo Encoded=true. Ciò si verifica solo per i valori dell'elemento Name contenenti i caratteri non validi in XML, non per gli elementi Name rimanenti nella risposta.

Corpo della risposta per condivisioni file con protocollo SMB abilitato

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

Nelle versioni 2020-04-08, 2020-06-12 e 2020-08-04, FileId viene restituito per i file e le directory se l'intestazione x-ms-file-extended-info è true. Nella versione 2020-10-02 e successive, FileId viene sempre restituito per file e directory.

Nella versione 2020-04-08, include={timestamps} restituisce le proprietà timestamp seguenti: CreationTime, LastAccessTimee LastWriteTime. Nella versione 2020-06-12 e versioni successive, include={timestamps} restituisce le proprietà timestamp seguenti: CreationTime, LastAccessTime, LastWriteTime, ChangeTimee Last-Modified.

Nella risposta viene restituita la versione 2020-10-02 e successive DirectoryId. Specifica il FileId della directory in cui viene chiamata l'API.

Corpo della risposta per condivisioni file con protocollo NFS abilitato

<?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 versione API per i campi timestamp

Elemento Formato Datetime Valore di esempio Versione DELL'API
CreationTime ISO 8601 2020-09-17T13:38:03.2740000Z 2020-04-08 e versioni successive
LastAccessTime ISO 8601 2020-09-17T13:38:03.2740000Z 2020-04-08 e versioni successive
LastWriteTime ISO 8601 2020-09-17T13:38:03.2740000Z 2020-04-08 e versioni successive
ChangeTime ISO 8601 2020-09-17T13:38:03.2740000Z 2020-06-12 e versioni successive
Last-Modified RFC 1123 Thu, 17 Sep 2020 13:38:07 GMT 2020-06-12 e versioni successive

Autorizzazione

Solo il proprietario dell'account può chiamare questa operazione.

Osservazioni

Il valore restituito nell'elemento Content-Length corrisponde al valore dell'intestazione x-ms-content-length del file.

Ogni elemento Directory restituito conta per il risultato massimo, esattamente come avviee per ogni elemento File. I file e le directory sono elencati in ordine lessicale nel corpo della risposta.

L'elenco è limitato a un singolo livello della gerarchia di directory. Per elencare più livelli, è possibile effettuare più chiamate in modo iterativo. Usare il valore Directory restituito da un risultato in una chiamata successiva a List Directories and Files.

Vedere anche

operazioni sulle directory