Elenco di directory e file

Articolo
03/29/2023

L'operazione List Directories and Files restituisce un elenco di file o directory sotto la condivisione o directory specificata. Elenca il contenuto solo per un singolo livello della gerarchia di directory.

Disponibilità del protocollo

Protocollo di condivisione file abilitato	Disponibile
SMB
NFS

Richiesta

È possibile costruire la List Directories and Files richiesta come indicato di seguito. È consigliato il protocollo HTTPS.

Metodo	URI richiesta	Versione 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

Sostituire i componenti del percorso mostrati nell'URI di richiesta con valori personalizzati, come illustrato 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 del percorso, vedere Denominazione e riferimento a condivisioni, directory, file e metadati.

Parametri URI

È possibile specificare i parametri aggiuntivi seguenti nell'URI.

Parametro	Descrizione
`prefix`	Facoltativa. Versione 2016-05-31 e successiva. Filtra i risultati per restituire solo file e directory con nomi che iniziano con il prefisso specificato.
`sharesnapshot`	Facoltativa. Versione 2017-04-17 e successiva. Il parametro snapshot di condivisione è un valore opaco `DateTime` che, quando presente, specifica lo snapshot di condivisione per eseguire query per l'elenco di file e directory.
`marker`	Facoltativa. Valore stringa che identifica la parte dell'elenco da restituire con l'operazione elenco successiva. L'operazione restituisce un valore di 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 marcatore risulta opaco al client.
`maxresults`	Facoltativa. Specifica il numero massimo di file o directory da restituire. Se la richiesta non specifica `maxresults`o specifica un valore maggiore di 5.000, il server restituirà fino a 5.000 elementi. L'impostazione di `maxresults` su un valore minore o uguale a zero restituisce il codice di risposta 400 (Richiesta non valida).
`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 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 questo parametro viene specificato.
`timeout`	Facoltativa. Il parametro `timeout` viene espresso in secondi. Per altre informazioni, vedere Impostazione dei timeout per le operazioni di File di Azure.

Intestazioni della richiesta

Nella seguente tabella vengono descritte le intestazioni di richiesta obbligatorie e facoltative.

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 la data per la richiesta nel fuso orario UTC (Coordinated Universal Time). Per altre informazioni, vedere Autorizzare le richieste ad Archiviazione di Azure.
`x-ms-version`	Obbligatorio per tutte le richieste autorizzate, facoltativo per le richieste anonime. Specifica la versione dell'operazione da usare per questa richiesta. Per altre informazioni, vedere Controllo delle versioni per i servizi di archiviazione di Azure.
`x-ms-client-request-id`	Facoltativa. Fornisce un valore opaco generato dal client con un limite di caratteri di 1 kibibyte (KiB) registrato nei log quando la registrazione è configurata. È consigliabile usare questa intestazione per correlare le attività lato client con le richieste ricevute dal server. Per altre informazioni, vedere Monitorare File di Azure.
`x-ms-file-extended-info: {true}`	Facoltativa. Versione 2020-04-08 e versioni successive. Questa intestazione viene implicitamente considerata true se il `include` parametro di query non è vuoto. Se true, la `Content-Length` proprietà sarà aggiornata. Nelle versioni 2020-04-08, 2020-06-12 e 2020-08-04, `FileId` viene restituito solo per file e directory solo se questa intestazione è true. Nelle versioni 2020-10-02 e versioni successive viene `FileId` sempre restituito per file e directory.
`x-ms-file-request-intent`	Obbligatorio se `Authorization` l'intestazione specifica un token OAuth. Il valore accettabile è `backup`. Questa intestazione specifica che l'oggetto `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 versioni successive.
`x-ms-allow-trailing-dot: { <Boolean> }`	Facoltativa. Versione 2022-11-02 e versioni successive. Il valore booleano specifica se un punto finale presente nell'URL della richiesta deve essere tagliato o meno. Per altre informazioni, vedere Denominazione e riferimenti a condivisioni, directory, file e metadati.

Testo della richiesta

Nessuno.

Risposta

Nella risposta sono inclusi un codice di stato HTTP, un set di intestazioni di risposta e il corpo della risposta nel formato XML.

Codice stato

Un'operazione completata correttamente restituisce 200 (OK). Per informazioni sui codici di stato, vedere Codici di stato e di errore.

Intestazioni di risposta

Nella risposta per questa operazione sono incluse le intestazioni riportate di seguito; La risposta può includere anche intestazioni HTTP aggiuntive e standard. Tutte le intestazioni standard sono conformi alla specifica del protocollo HTTP/1.1.

Intestazione 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 relativi alle 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 le richieste e le 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.

Corpo della risposta

Il formato della risposta XML è il seguente.

Si noti che gli Markerelementi , 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 completati.

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

Si noti che l'elemento Content-Length viene restituito nell'elenco. Tuttavia, questo valore potrebbe non essere aggiornato, perché un client SMB 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 op viene interrotto. Per recuperare i valori delle proprietà correnti, usare o chiamare x-ms-file-extended-info: trueRecupera proprietà file.

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 versioni successive viene FileId sempre restituito per file e directory.

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

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

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

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.

Commenti

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

Si noti che ogni elemento Directory ha restituito i conteggi fino al risultato massimo, proprio come ogni elemento File. I file e le directory sono elencati interminate, in ordine lessicalmente ordinato nel corpo della risposta.

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

Vedi anche

Operazioni sulle directory