Auflisten von Verzeichnissen und Dateien

Artikel
03/29/2023

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
NFS

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 `maxresults`oder 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

Freigeben über