Freigeben über

Verzeichnisse und Dateien auflisten

  • Artikel

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 Ja
NFS Ja

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 maxresultsangibt 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:
  • Timestamps
  • ETag
  • Attributes (Win32-Dateiattribute)
  • PermissionKey

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, ShareSnapshotund 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 FileName, DirectoryName, 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, LastAccessTimeund LastWriteTime. In Version 2020-06-12 und höher gibt include={timestamps} die folgenden Zeitstempeleigenschaften zurück: CreationTime, LastAccessTime, LastWriteTime, ChangeTimeund 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.

Siehe auch

Vorgänge in Verzeichnissen