Verzeichnisse und Dateien auflisten
Der vorgang List Directories and Files
gibt eine Liste von Dateien oder Verzeichnissen unter der angegebenen Freigabe oder dem angegebenen Verzeichnis zurück. Er listet den Inhalt nur für eine einzelne Ebene der Verzeichnishierarchie auf. Dieser Vorgang wird in Version 2025-05-05 und höher für Dateifreigaben mit aktiviertem NFS-Protokoll unterstützt.
Protokollverfügbarkeit
Aktiviertes Dateifreigabeprotokoll | Verfügbar |
---|---|
SMB |
![]() |
NFS |
![]() |
Bitten
Die List Directories and Files
Anforderung wird wie folgt erstellt. Es wird empfohlen, HTTPS zu verwenden.
Methode | Anforderungs-URI | HTTP-Version |
---|---|---|
ERHALTEN | https://myaccount.file.core.windows.net/myshare/mydirectorypath?restype=directory&comp=list |
HTTP/1.1 |
ERHALTEN | https://myaccount.file.core.windows.net/myshare/mydirectorypath?restype=directory&sharesnapshot=<DateTime>&comp=list |
HTTP/1.1 |
Ersetzen Sie die pfadkomponenten, die im Anforderungs-URI angezeigt werden, wie folgt:
Pfadkomponente | Beschreibung |
---|---|
myaccount |
Der Name Ihres Speicherkontos. |
myshare |
Der Name Ihrer Dateifreigabe. |
mydirectorypath |
Der Pfad zum Verzeichnis. |
Ausführliche Informationen zu Pfadbenennungseinschränkungen finden Sie unter Benennen und Verweisen auf Freigaben, Verzeichnisse, Dateien und Metadaten.
URI-Parameter
Sie können die folgenden zusätzlichen Parameter für den URI angeben.
Allgemeine URI-Parameter
Parameter | Beschreibung |
---|---|
prefix |
Wahlfrei. Version 2016-05-31 und höher. Filtert die Ergebnisse so, dass nur Dateien und Verzeichnisse mit Namen zurückgegeben werden, die mit dem angegebenen Präfix beginnen. |
sharesnapshot |
Wahlfrei. Version 2017-04-17 und höher. Der Parameter "Momentaufnahme freigeben" ist ein undurchsichtiger DateTime Wert, der, wenn vorhanden, die Freigabemomentaufnahme angibt, um die Liste der Dateien und Verzeichnisse abzufragen.The share snapshot is anopaque DateTime value that specifies the share snapshot to query for the list of files and directories. |
marker |
Wahlfrei. Ein Zeichenfolgenwert, der den Teil der Liste identifiziert, der mit dem nächsten Listenvorgang zurückgegeben werden soll. Der Vorgang gibt einen Markerwert im Antworttext zurück, wenn die zurückgegebene Liste nicht abgeschlossen wurde. Anschließend können Sie den Markierungswert in einem nachfolgenden Aufruf verwenden, um den nächsten Satz von Listenelementen anzufordern. Der Markerwert ist für den Client nicht transparent. |
maxresults |
Wahlfrei. Gibt die maximale Anzahl der zurückzugebenden Dateien oder Verzeichnisse an. Wenn die Anforderung nicht maxresults angibt oder einen Wert größer als 5.000 angibt, gibt der Server bis zu 5.000 Elemente zurück.Das Festlegen maxresults auf einen Wert kleiner oder gleich Null führt zu Fehlerantwortcode 400 (ungültige Anforderung). |
timeout |
Wahlfrei. Der parameter timeout wird in Sekunden ausgedrückt. Weitere Informationen finden Sie unter Festlegen von Timeouts für Azure Files-Vorgänge. |
Nur SMB-URI-Parameter
Parameter | Beschreibung |
---|---|
include={Timestamps, ETag, Attributes, PermissionKey} |
Optional verfügbar, ab Version 2020-04-08. Gibt eine oder mehrere Eigenschaften an, die in die Antwort eingeschlossen werden sollen:
Um mehrere dieser Optionen für den URI anzugeben, müssen Sie jede Option durch ein URL-codiertes Komma ( %82 ) trennen.Die Header- x-ms-file-extended-info wird implizit als "true" angenommen, wenn dieser Parameter angegeben wird. |
NUR NFS-URI-Parameter
Nichts.
Anforderungsheader
Die erforderlichen und optionalen Anforderungsheader werden in den folgenden Tabellen beschrieben:
Allgemeine Anforderungsheader
Anforderungsheader | Beschreibung |
---|---|
Authorization |
Erforderlich. Gibt das Autorisierungsschema, den Kontonamen und die Signatur an. Weitere Informationen finden Sie unter Autorisieren von Anforderungen an Azure Storage. |
Date oder x-ms-date |
Erforderlich. Gibt die koordinierte Weltzeit (UTC) für die Anforderung an. Weitere Informationen finden Sie unter Autorisieren von Anforderungen an Azure Storage. |
x-ms-version |
Erforderlich für alle autorisierten Anforderungen. Gibt die Version des Vorgangs an, der für diese Anforderung verwendet werden soll. Dieser Vorgang wird in Version 2025-05-05 und höher für Dateifreigaben mit aktiviertem NFS-Protokoll unterstützt. Weitere Informationen finden Sie unter Versionsverwaltung für die Azure Storage-Dienste. |
x-ms-client-request-id |
Wahlfrei. Stellt einen vom Client generierten, undurchsichtigen Wert mit einem 1-Kibibyte-Zeichenlimit (KiB) bereit, der in den Protokollen aufgezeichnet wird, wenn die Protokollierung konfiguriert ist. Es wird dringend empfohlen, diesen Header zu verwenden, um clientseitige Aktivitäten mit Anforderungen zu korrelieren, die der Server empfängt. Weitere Informationen finden Sie unter Überwachen von Azure Files. |
x-ms-file-request-intent |
Erforderlich, wenn Authorization Header ein OAuth-Token angibt. Zulässiger Wert ist backup . Dieser Header gibt an, dass die Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action oder Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action gewährt werden sollen, wenn sie in der RBAC-Richtlinie enthalten sind, die der Identität zugewiesen ist, die mithilfe des Authorization -Headers autorisiert ist. Verfügbar für Version 2022-11-02 und höher. |
x-ms-allow-trailing-dot: { <Boolean> } |
Wahlfrei. Version 2022-11-02 und höher. Der boolesche Wert gibt an, ob ein nachgestellter Punkt in der Anforderungs-URL gekürzt werden soll. Dieser Header wird ignoriert, wenn sich das Ziel auf einer Dateifreigabe mit aktiviertem NFS-Protokoll befindet, das den nachfolgenden Punkt standardmäßig unterstützt. Weitere Informationen finden Sie unter Benennen und Verweisen auf Freigaben, Verzeichnisse, Dateien und Metadaten. |
Nur SMB-Anforderungsheader
Anforderungsheader | Beschreibung |
---|---|
x-ms-file-extended-info: {true} |
Wahlfrei. Version 2020-04-08 und höher. Dieser Header wird implizit als "true" angenommen, wenn der include Abfrageparameter nicht leer ist. Ist "true", ist die eigenschaft Content-Length für Dateien, die die Größe der Datei angibt, auf dem neuesten Stand sein. |
NUR NFS-Anforderungsheader
Nichts.
Anforderungstext
Nichts.
Antwort
Die Antwort enthält einen HTTP-Statuscode, eine Reihe von Antwortheadern und einen Antworttext im XML-Format.
Statuscode
Ein erfolgreicher Vorgang gibt den Statuscode 200 (OK) zurück. Informationen zu Statuscodes finden Sie unter Status- und Fehlercodes.
Antwortheader
Die Antwort für diesen Vorgang enthält die Kopfzeilen in den folgenden Tabellen. Die Antwort kann auch zusätzliche Standard-HTTP-Header enthalten. Alle Standardheader entsprechen der HTTP/1.1-Protokollspezifikation.
Allgemeine Antwortheader
Antwortheader | Beschreibung |
---|---|
Content-Type |
Gibt das Format an, in dem die Ergebnisse zurückgegeben werden. Derzeit ist dieser Wert application/xml . |
x-ms-request-id |
Dieser Header identifiziert die anforderung eindeutig und kann für die Problembehandlung der Anforderung verwendet werden. Weitere Informationen finden Sie unter Problembehandlung für API-Vorgänge. |
x-ms-version |
Gibt die Version von Azure Files an, die zum Ausführen der Anforderung verwendet wird. |
Date oder x-ms-date |
Ein UTC-Datums-/Uhrzeitwert, der die Uhrzeit angibt, zu der die Antwort initiiert wurde. Der Dienst generiert diesen Wert. |
x-ms-client-request-id |
Sie können diesen Header verwenden, um Anfragen und entsprechende Antworten zu behandeln. Der Wert dieses Headers ist gleich dem Wert des x-ms-client-request-id -Headers, wenn er in der Anforderung vorhanden ist. Der Wert beträgt höchstens 1024 sichtbare ASCII-Zeichen. Wenn der x-ms-client-request-id -Header in der Anforderung nicht vorhanden ist, ist dieser Header in der Antwort nicht vorhanden. |
Nur SMB-Antwortheader
Nichts.
NUR NFS-Antwortheader
Nichts.
Antworttext
Das Format der XML-Antwort lautet wie folgt.
Die elemente Marker
, ShareSnapshot
und MaxResults
sind nur vorhanden, wenn Sie sie für den Anforderungs-URI angeben. Das NextMarker
-Element weist nur dann einen Wert auf, wenn die Listenergebnisse nicht abgeschlossen sind.
Das Content-Length
-Element wird in der Auflistung für Dateien zurückgegeben, die die Größe der Datei angibt. Dieser Wert ist jedoch möglicherweise nicht up-to-datum, da ein SMB- oder NFS-Client die Datei möglicherweise lokal geändert hat. Der Wert von Content-Length
spiegelt möglicherweise nicht wider, bis der Handle geschlossen wird, oder die SMB-Op-Sperre ist unterbrochen. Um aktuelle Eigenschaftswerte abzurufen, verwenden Sie x-ms-file-extended-info: true
für ein Verzeichnis, das in einer Dateifreigabe mit aktiviertem SMB-Protokoll gespeichert ist, oder rufen Sie Abrufen von Dateieigenschaften für die jeweilige Datei auf.
In Den Versionen 2021-12-02 und höher codiert List Directory and Files
(pro RFC 2396) alle File
Name
, Directory
Name
, Prefix
oder DirectoryPath
Elementwerte, die Zeichen enthalten, die in XML ungültig sind (insbesondere U+FFFE oder U+FFFF). Wenn codiert, enthält das Name
-, Prefix
- oder EnumerationResults
-Element ein Encoded=true
-Attribut. Dies geschieht nur für die Name
-Elementwerte, die die in XML ungültigen Zeichen enthalten, nicht für die verbleibenden Name
Elemente in der Antwort.
Antworttext für Dateifreigaben mit aktivierten SMB-Protokoll
<?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>
In den Versionen 2020-04-08, 2020-06-12 und 2020-08-04 wird FileId
für Dateien und Verzeichnisse zurückgegeben, wenn der Header x-ms-file-extended-info
wahr ist. In Version 2020-10-02 und höher wird FileId
immer für Dateien und Verzeichnisse zurückgegeben.
In Version 2020-04-08 gibt include={timestamps}
die folgenden Zeitstempeleigenschaften zurück: CreationTime
, LastAccessTime
und LastWriteTime
. In Version 2020-06-12
und höher gibt include={timestamps}
die folgenden Zeitstempeleigenschaften zurück: CreationTime
, LastAccessTime
, LastWriteTime
, ChangeTime
und Last-Modified
.
In Version 2020-10-02 und höher wird DirectoryId
in der Antwort zurückgegeben. Es gibt die FileId
des Verzeichnisses an, für das die API aufgerufen wird.
Antworttext für Dateifreigaben mit aktiviertem NFS-Protokoll
<?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>
Datetime-Format und API-Version für Zeitstempelfelder
Element | Datetime-Format | Beispielwert | API-Version |
---|---|---|---|
CreationTime |
ISO 8601 | 2020-09-17T13:38:03.2740000Z |
2020-04-08 und höher |
LastAccessTime |
ISO 8601 | 2020-09-17T13:38:03.2740000Z |
2020-04-08 und höher |
LastWriteTime |
ISO 8601 | 2020-09-17T13:38:03.2740000Z |
2020-04-08 und höher |
ChangeTime |
ISO 8601 | 2020-09-17T13:38:03.2740000Z |
2020-06-12 und höher |
Last-Modified |
RFC 1123 | Thu, 17 Sep 2020 13:38:07 GMT |
2020-06-12 und höher |
Ermächtigung
Nur der Kontobesitzer kann diesen Vorgang aufrufen.
Bemerkungen
Der im Content-Length
-Element zurückgegebene Wert entspricht dem Wert des x-ms-content-length
Headers der Datei.
Jedes zurückgegebene Directory
-Element zählt zu dem maximalen Ergebnis, genau wie jedes File
Element. Dateien und Verzeichnisse werden in einer lexikalisch sortierten Reihenfolge im Antworttext aufgelistet.
Die Auflistung ist auf eine einzelne Ebene der Verzeichnishierarchie beschränkt. Zum Auflisten mehrerer Ebenen können Sie mehrere Aufrufe iterativ durchführen. Verwenden Sie den von einem Ergebnis zurückgegebenen Directory
Wert in einem nachfolgenden Aufruf von List Directories and Files
.