Freigeben über


Auflisten von Verzeichnissen und Dateien

Der List Directories and Files-Vorgang gibt eine Liste der Dateien oder Verzeichnisse unter der angegebenen Freigabe oder dem angegebenen Verzeichnis zurück. Er führt die Inhalte nur für eine einzelne Ebene der Verzeichnishierarchie auf.

Protokollverfügbarkeit

Aktiviertes Dateifreigabeprotokoll Verfügbar
SMB Ja
NFS Nein

Anforderung

Sie können die List Directories and Files Anforderung wie folgt erstellen. HTTPS wird empfohlen.

Methode Anforderungs-URI HTTP-Version
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

Ersetzen Sie die im Anforderungs-URI angezeigten Pfadkomponenten wie folgt durch Ihre eigenen Angaben:

Pfadkomponente Beschreibung
myaccount Der Name Ihres Speicherkontos.
myshare Der Name der Dateifreigabe.
mydirectorypath Der Pfad zum Verzeichnis.

Ausführliche Informationen zu Einschränkungen bei der Pfadbenennung 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.

Parameter BESCHREIBUNG
prefix Optional. Version 2016-05-31 und höher. Filtert die Ergebnisse, um nur Dateien und Verzeichnisse zurückzugeben, deren Namen mit dem angegebenen Präfix beginnen.
sharesnapshot Optional. Version 2017-04-17 und höher. Der parameter share Momentaufnahme ist ein undurchsichtiger DateTime Wert, der, sofern vorhanden, die freigabe Momentaufnahme angibt, die nach der Liste der Dateien und Verzeichnissen abzufragen ist.
marker Optional. Ein Zeichenfolgenwert, der den Teil der Liste angibt, der mit dem nächsten Auflistungsvorgang zurückgegeben wird. Der Vorgang gibt einen Markerwert innerhalb des Antworttexts zurück, wenn die zurückgegebene Liste nicht vollständig war. Sie können dann den Markerwert in einem nachfolgenden Aufruf verwenden, um den nächsten Satz von Listenelementen anzufordern.

Der Markerwert ist für den Client nicht transparent.
maxresults Optional. Gibt die maximale Anzahl von Dateien oder Verzeichnissen an, die zurückgegeben werden sollen. Wenn die Anforderung nicht angibt maxresultsoder einen Wert größer als 5.000 angibt, gibt der Server bis zu 5.000 Elemente zurück.

Wenn maxresults auf einen Wert kleiner oder gleich 0 festgelegt ist, wird Fehlerantwortcode 400 ausgegeben (ungültige Anforderung).
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.

Der Header x-ms-file-extended-info wird implizit als true angenommen, wenn dieser Parameter angegeben wird.
timeout Optional. Der timeout-Parameter wird in Sekunden angegeben. Weitere Informationen finden Sie unter Festlegen von Timeouts für Azure Files Vorgänge.

Anforderungsheader

In der folgenden Tabelle werden erforderliche und optionale Anforderungsheader beschrieben.

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 (Coordinated Universal Time, 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, optional für anonyme Anforderungen. Gibt die Version des für die Anforderung zu verwendenden Vorgangs an. Weitere Informationen finden Sie unter Versionsverwaltung für die Azure-Speicherdienste.
x-ms-client-request-id Optional. Stellt einen vom Client generierten, undurchsichtigen Wert mit einem Zeichenlimit von 1 Kibibyte (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 Azure Files.
x-ms-file-extended-info: {true} Optional. Version 2020-04-08 und höher. Dieser Header wird implizit als true angenommen, wenn der include Abfrageparameter nicht leer ist. Wenn true, ist die Content-Length Eigenschaft auf dem neuesten Stand. In den Versionen 2020-04-08, 2020-06-12 und 2020-08-04 wird für Dateien und Verzeichnisse nur zurückgegeben, FileId wenn dieser Header true ist. In Den Versionen 2020-10-02 und höher FileId wird immer für Dateien und Verzeichnisse zurückgegeben.
x-ms-file-request-intent Erforderlich, wenn Authorization der Header ein OAuth-Token angibt. Zulässiger Wert ist backup. Dieser Header gibt an, dass oder Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/actionMicrosoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action gewährt werden soll, 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> } Optional. Version 2022-11-02 und höher. Der boolesche Wert gibt an, ob ein nachgestellter Punkt in der Anforderungs-URL gekürzt werden soll. Weitere Informationen finden Sie unter Benennen und Verweisen auf Freigaben, Verzeichnisse, Dateien und Metadaten.

Anforderungstext

Keine.

Antwort

Die Antwort enthält den HTTP-Statuscode, einen Satz von Antwortheadern und einen Antworttext im XML-Format.

Statuscode

Bei einem erfolgreichen Vorgang wird der Statuscode 200 (OK) zurückgegeben. Informationen zu status Codes finden Sie unter Status- und Fehlercodes.

Antwortheader

Die Antwort für diesen Vorgang umfasst die folgenden Header. Die Antwort kann auch zusätzliche HTTP-Standardheader enthalten. Alle Standardheader entsprechen der HTTP/1.1-Protokollspezifikation.

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 eindeutig die Anforderung, die gestellt wurde, 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 Probleme mit Anforderungen und entsprechenden Antworten zu beheben. Der Wert dieses Headers entspricht dem Wert des x-ms-client-request-id Headers, wenn er in der Anforderung vorhanden ist. Der Wert ist 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.

Antworttext

Die XML-Antwort weist das folgende Format auf:

Beachten Sie, dass die MarkerElemente , ShareSnapshotund MaxResults nur vorhanden sind, wenn Sie sie im Anforderungs-URI angeben. Das NextMarker Element verfügt nur dann über einen Wert, wenn die Listenergebnisse nicht vollständig sind.

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

Beachten Sie, dass das Element Content-Length in der Liste zurückgegeben wird. Dieser Wert ist jedoch möglicherweise nicht auf dem neuesten Stand, da die Datei möglicherweise von einem SMB-Client lokal geändert wurde. Der Wert von Content-Length spiegelt diese Tatsache möglicherweise erst wider, wenn der Handle geschlossen oder die Betriebssperre unterbrochen ist. Um aktuelle Eigenschaftswerte abzurufen, verwenden Sie x-ms-file-extended-info: true, oder rufen Sie Dateieigenschaften abrufen auf.

In den Versionen 2020-04-08, 2020-06-12 und 2020-08-04 wird für Dateien und Verzeichnisse zurückgegeben, FileId wenn der Header x-ms-file-extended-info true ist. In Version 2020-10-02 und höher FileId wird immer für Dateien und Verzeichnisse zurückgegeben.

In Version 2020-04-08 include={timestamps} werden die folgenden Zeitstempeleigenschaften zurückgegeben: CreationTime, LastAccessTimeund LastWriteTime. In version 2020-06-12 und höher include={timestamps} gibt die folgenden Zeitstempeleigenschaften zurück: CreationTime, LastAccessTime, LastWriteTime, ChangeTimeund Last-Modified.

In Version 2020-10-02 und höher DirectoryId wird in der Antwort zurückgegeben. Es gibt den FileId des Verzeichnisses an, in dem die API aufgerufen wird.

In den Versionen 2021-12-02 und höher List Directory and Files werden alleNameFile Elementwerte PrefixDirectoryNameDirectoryPath prozentual codiert (gemäß RFC 2396), die ungültige Zeichen in XML enthalten (insbesondere U+FFFE oder U+FFFF). Wenn es codiert ist, enthält das Name- Prefix oder EnumerationResults -Element ein Encoded=true -Attribut. Beachten Sie, dass dies nur für die Name Elementwerte auftritt, die die ungültigen Zeichen in XML enthalten, nicht für die restlichen Name Elemente in der Antwort.

Datetime-Format und API-Version für Zeitstempelfelder

Element Datetime-Format Beispielwert API-Version
CreationTime ISO 8601 2020-09-17T13:38:03.2740000Z 08.04.2020 und höher
LastAccessTime ISO 8601 2020-09-17T13:38:03.2740000Z 08.04.2020 und höher
LastWriteTime ISO 8601 2020-09-17T13:38:03.2740000Z 08.04.2020 und höher
ChangeTime ISO 8601 2020-09-17T13:38:03.2740000Z 12.06.2020 und höher
Last-Modified RFC 1123 Thu, 17 Sep 2020 13:38:07 GMT 12.06.2020 und höher

Autorisierung

Nur der Kontobesitzer kann diesen Vorgang aufrufen.

Hinweise

Der im Content-Length -Element zurückgegebene Wert entspricht dem Wert des Headers x-ms-content-length der Datei.

Beachten Sie, dass jedes zurückgegebene Directory-Element in das maximale Ergebnis eingerechnet wird, ebenso wie jedes File-Element. Dateien und Verzeichnisse werden in lexisch sortierter Reihenfolge im Antworttext vermischt aufgeführt.

Die Auflistung ist auf eine einzelne Ebene der Verzeichnishierarchie beschränkt. Um mehrere Ebenen aufzulisten, können Sie mehrere Aufrufe iterativ tätigen. Verwenden Sie den Directory von einem Ergebnis zurückgegebenen Wert in einem nachfolgenden Aufruf von List Directories and Files.

Weitere Informationen

Vorgänge in Verzeichnissen