Dela via

Lista kataloger och filer

  • Artikel

Åtgärden List Directories and Files returnerar en lista över filer eller kataloger under den angivna resursen eller katalogen. Den visar endast innehållet för en enda nivå i kataloghierarkin. Den här åtgärden stöds i version 2025-05-05 och senare för filresurser med NFS-protokollet aktiverat.

Protokolltillgänglighet

Aktiverat filresursprotokoll Tillgänglig
SMB Ja
NFS Ja

Begäran

Den List Directories and Files begäran skapas på följande sätt. Vi rekommenderar att du använder HTTPS.

Metod Begärande-URI HTTP-version
FÅ https://myaccount.file.core.windows.net/myshare/mydirectorypath?restype=directory&comp=list HTTP/1.1
FÅ https://myaccount.file.core.windows.net/myshare/mydirectorypath?restype=directory&sharesnapshot=<DateTime>&comp=list HTTP/1.1

Ersätt sökvägskomponenterna som visas i begärande-URI:n med dina egna enligt följande:

Sökvägskomponent Beskrivning
myaccount Namnet på ditt lagringskonto.
myshare Namnet på filresursen.
mydirectorypath Sökvägen till katalogen.

Mer information om namngivningsbegränsningar för sökvägar finns i Namngivnings- och referensresurser, kataloger, filer och metadata.

URI-parametrar

Du kan ange följande ytterligare parametrar på URI:n.

Vanliga URI-parametrar

Parameter Beskrivning
prefix Valfri. Version 2016-05-31 och senare. Filtrerar resultatet så att endast filer och kataloger som har namn som börjar med det angivna prefixet returneras.
sharesnapshot Valfri. Version 2017-04-17 och senare. Parametern resursögonblicksbild är ett ogenomskinlig DateTime värde som när det finns anger resursögonblicksbilden för att fråga efter listan över filer och kataloger.
marker Valfri. Ett strängvärde som identifierar den del av listan som ska returneras med nästa liståtgärd. Åtgärden returnerar ett markörvärde i svarstexten om listan som returnerades inte slutfördes. Du kan sedan använda markörvärdet i ett efterföljande anrop för att begära nästa uppsättning listobjekt.

Markörvärdet är ogenomskinlig för klienten.
maxresults Valfri. Anger det maximala antalet filer eller kataloger som ska returneras. Om begäran inte anger maxresults, eller anger ett värde som är större än 5 000, returnerar servern upp till 5 000 objekt.

Om du anger maxresults till ett värde som är mindre än eller lika med noll resulterar det i felsvarskoden 400 (felaktig begäran).
timeout Valfri. Parametern timeout uttrycks i sekunder. Mer information finns i Ställa in tidsgränser för Azure Files-åtgärder.

Endast SMB-URI-parametrar

Parameter Beskrivning
include={Timestamps, ETag, Attributes, PermissionKey} Valfritt tillgängligt, från och med version 2020-04-08. Anger en eller flera egenskaper som ska ingå i svaret:
  • Timestamps
  • ETag
  • Attributes (Win32-filattribut)
  • PermissionKey

Om du vill ange fler än ett av dessa alternativ på URI:n måste du avgränsa varje alternativ med ett URL-kodat kommatecken (%82).

Rubriken x-ms-file-extended-info antas implicit vara sant när den här parametern anges.

Endast NFS-URI-parametrar

Ingen.

Begärandehuvuden

De obligatoriska och valfria begäranderubrikerna beskrivs i följande tabeller:

Vanliga begärandehuvuden

Begärandehuvud Beskrivning
Authorization Krävs. Anger auktoriseringsschema, kontonamn och signatur. Mer information finns i Auktorisera begäranden till Azure Storage.
Date eller x-ms-date Krävs. Anger UTC (Coordinated Universal Time) för begäran. Mer information finns i Auktorisera begäranden till Azure Storage.
x-ms-version Krävs för alla auktoriserade begäranden. Anger vilken version av åtgärden som ska användas för den här begäran. Den här åtgärden stöds i version 2025-05-05 och senare för filresurser med NFS-protokollet aktiverat.

Mer information finns i Versionshantering för Azure Storage-tjänsterna.
x-ms-client-request-id Valfri. Tillhandahåller ett klientgenererat, täckande värde med en kibibytesteckengräns (KiB) som registreras i loggarna när loggningen konfigureras. Vi rekommenderar starkt att du använder det här huvudet för att korrelera aktiviteter på klientsidan med begäranden som servern tar emot. Mer information finns i Övervaka Azure Files-.
x-ms-file-request-intent Krävs om Authorization rubrik anger en OAuth-token. Acceptabelt värde är backup. Det här huvudet anger att Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action eller Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action ska beviljas om de ingår i RBAC-principen som tilldelats den identitet som är auktoriserad med hjälp av Authorization-huvudet. Tillgänglig för version 2022-11-02 och senare.
x-ms-allow-trailing-dot: { <Boolean> } Valfri. Version 2022-11-02 och senare. Det booleska värdet anger om en avslutande punkt som finns i begärande-URL:en ska trimmas eller inte.

Det här huvudet ignoreras om målet finns på en filresurs med NFS-protokollet aktiverat, vilket stöder avslutande punkt som standard.

Mer information finns i Namngivning och referens av resurser, kataloger, filer och metadata.

Endast SMB-begärandehuvuden

Begärandehuvud Beskrivning
x-ms-file-extended-info: {true} Valfri. Version 2020-04-08 och senare. Det här huvudet antas implicit vara sant om include frågeparametern inte är tom. Om det är sant är egenskapen Content-Length för filer som anger filens storlek uppdaterad.

Endast NFS-begärandehuvuden

Ingen.

Begärandetext

Ingen.

Svar

Svaret innehåller en HTTP-statuskod, en uppsättning svarshuvuden och en svarstext i XML-format.

Statuskod

En lyckad åtgärd returnerar statuskod 200 (OK). Information om statuskoder finns i Status och felkoder.

Svarshuvuden

Svaret för den här åtgärden innehåller rubrikerna i följande tabeller. Svaret kan också innehålla ytterligare HTTP-standardhuvuden. Alla standardhuvuden överensstämmer med HTTP/1.1-protokollspecifikationen.

Vanliga svarshuvuden

Svarsrubrik Beskrivning
Content-Type Anger i vilket format resultatet returneras. För närvarande är det här värdet application/xml.
x-ms-request-id Det här huvudet identifierar unikt den begäran som gjordes och kan användas för att felsöka begäran. Mer information finns i Felsökning av API-åtgärder.
x-ms-version Anger vilken version av Azure Files som används för att köra begäran.
Date eller x-ms-date Ett UTC-datum/tid-värde som anger den tid då svaret initierades. Tjänsten genererar det här värdet.
x-ms-client-request-id Du kan använda den här rubriken för att felsöka begäranden och motsvarande svar. Värdet för det här huvudet är lika med värdet för x-ms-client-request-id-huvudet, om det finns i begäran. Värdet är högst 1 024 synliga ASCII-tecken. Om x-ms-client-request-id-huvudet inte finns i begäran visas inte det här huvudet i svaret.

Endast SMB-svarshuvuden

Ingen.

Endast NFS-svarshuvuden

Ingen.

Svarstext

Formatet för XML-svaret är följande.

Elementen Marker, ShareSnapshotoch MaxResults finns bara om du anger dem på begärande-URI:n. Elementet NextMarker har bara ett värde om listresultatet inte är slutfört.

Elementet Content-Length returneras i listan för filer, vilket anger filens storlek. Det här värdet kanske dock inte är up-to-date, eftersom en SMB- eller NFS-klient kan ha ändrat filen lokalt. Värdet för Content-Length kanske inte återspeglar det faktumet förrän handtaget har stängts eller SMB op-lock har brutits. Om du vill hämta aktuella egenskapsvärden använder du x-ms-file-extended-info: true för en katalog som finns på en filresurs med SMB-protokollet aktiverat eller anropar Hämta filegenskaper mot den specifika filen.

I versionerna 2021-12-02 och senare kommer List Directory and Files procentkoda (per RFC 2396) alla FileName, DirectoryName, Prefix eller DirectoryPath elementvärden som innehåller tecken som är ogiltiga i XML (specifikt U+FFFE eller U+FFFF). Om det kodas innehåller elementet Name, Prefix eller EnumerationResults ett Encoded=true-attribut. Detta inträffar bara för Name elementvärden som innehåller tecknen som är ogiltiga i XML, inte de återstående Name elementen i svaret.

Svarstext för filresurser med SMB-protokoll aktiverat

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

I versionerna 2020-04-08, 2020-06-12 och 2020-08-04 returneras FileId för filer och kataloger om rubriken x-ms-file-extended-info är sant. I version 2020-10-02 och senare returneras alltid FileId för filer och kataloger.

I version 2020-04-08 returnerar include={timestamps} följande tidsstämpelegenskaper: CreationTime, LastAccessTimeoch LastWriteTime. I version 2020-06-12 och senare returnerar include={timestamps} följande tidsstämpelegenskaper: CreationTime, LastAccessTime, LastWriteTime, ChangeTimeoch Last-Modified.

I version 2020-10-02 och senare returneras DirectoryId i svaret. Den anger FileId för katalogen där API:et anropas.

Svarstext för filresurser med NFS-protokoll aktiverat

<?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 och API-version för tidsstämpelfält

Element Datetime-format Exempelvärde API-version
CreationTime ISO 8601 2020-09-17T13:38:03.2740000Z 2020-04-08 och senare
LastAccessTime ISO 8601 2020-09-17T13:38:03.2740000Z 2020-04-08 och senare
LastWriteTime ISO 8601 2020-09-17T13:38:03.2740000Z 2020-04-08 och senare
ChangeTime ISO 8601 2020-09-17T13:38:03.2740000Z 2020-06-12 och senare
Last-Modified RFC 1123 Thu, 17 Sep 2020 13:38:07 GMT 2020-06-12 och senare

Tillstånd

Endast kontoägaren kan anropa den här åtgärden.

Anmärkningar

Värdet som returneras i elementet Content-Length motsvarar värdet för filens x-ms-content-length-huvud.

Varje Directory element som returneras räknas mot det maximala resultatet, precis som varje File element gör. Filer och kataloger listas i lexikal sorterad ordning i svarstexten.

Listan är begränsad till en enda nivå i kataloghierarkin. Om du vill visa en lista över flera nivåer kan du göra flera anrop på ett iterativt sätt. Använd värdet Directory som returneras från ett resultat i ett efterföljande anrop till List Directories and Files.

Se även

åtgärder för kataloger