Lista kataloger och filer

Artikel
03/29/2023

Å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.

Protokolltillgänglighet

Aktiverat filresursprotokoll	Tillgängligt
SMB
NFS

Förfrågan

Du kan skapa begäran på List Directories and Files följande sätt. HTTPS rekommenderas.

Metod	URI för förfrågan	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

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

Sökvägskomponent	Description
`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 Namnge och referera till resurser, kataloger, filer och metadata.

URI-parametrar

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

Parameter	Beskrivning
`prefix`	Valfritt. 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`	Valfritt. Version 2017-04-17 och senare. Resursögonblicksparametern är ett täckande `DateTime` värde som när det finns anger resursögonblicksbilden för att fråga efter listan över filer och kataloger.
`marker`	Valfritt. 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`	Valfritt. 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` ett värde som är mindre än eller lika med noll resulterar det i felsvarskoden 400 (felaktig begäran).
`include={Timestamps, ETag, Attributes, PermissionKey}`	Valfritt tillgängligt, med början i 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`). Huvudet `x-ms-file-extended-info` antas implicit vara sant när den här parametern anges.
`timeout`	Valfritt. Parametern `timeout` uttrycks i sekunder. Mer information finns i Ange tidsgränser för Azure Files åtgärder.

Begärandehuvuden

I följande tabell beskrivs obligatoriska och valfria 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 Coordinated Universal Time (UTC) 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, valfritt för anonyma begäranden. Anger vilken version av åtgärden som ska användas för den här begäran. Mer information finns i Versionshantering för Azure Storage-tjänsterna.
`x-ms-client-request-id`	Valfritt. Tillhandahåller ett klientgenererat, täckande värde med en teckengräns på 1 kibibyte (KiB) som registreras i loggarna när loggningen har konfigurerats. 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-extended-info: {true}`	Valfritt. 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` uppdaterad. I versionerna 2020-04-08, 2020-06-12 och 2020-08-04 `FileId` returneras endast för filer och kataloger om det här huvudet är sant. I versionerna 2020-10-02 och senare `FileId` returneras alltid för filer och kataloger.
`x-ms-file-request-intent`	Krävs om `Authorization` huvudet 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 har behörighet med huvudet `Authorization` . Tillgänglig för version 2022-11-02 och senare.
`x-ms-allow-trailing-dot: { <Boolean> }`	Valfritt. 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. Mer information finns i Namnge och referera till resurser, kataloger, filer och metadata.

Begärandetext

Inga.

Svarsåtgärder

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

Statuskod

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

Svarshuvuden

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

Svarsrubrik	Description
`Content-Type`	Anger i vilket format resultaten returneras. För närvarande är `application/xml`det här värdet .
`x-ms-request-id`	Det här huvudet identifierar unikt den begäran som har gjorts och kan användas för att felsöka begäran. Mer information finns i Felsöka 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 det här huvudet 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. `x-ms-client-request-id` Om rubriken inte finns i begäran visas inte det här huvudet i svaret.

Själva svaret

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

Observera att elementen Marker, ShareSnapshotoch MaxResults endast finns om du anger dem på begärande-URI:n. Elementet NextMarker har bara ett värde om listresultatet inte är klart.

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

Observera att elementet Content-Length returneras i listan. Det här värdet kanske dock inte är uppdaterat eftersom en SMB-klient kan ha ändrat filen lokalt. Värdet för Content-Length kanske inte återspeglar detta förrän handtaget har stängts, eller så är op-låset brutet. Om du vill hämta aktuella egenskapsvärden använder du x-ms-file-extended-info: trueeller anropar Hämta filegenskaper.

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

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

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

I versionerna 2021-12-02 och senare List Directory and Files kodas procentkodning (per RFC 2396) allaNameFile , PrefixDirectoryNameeller DirectoryPath elementvärden som innehåller ogiltiga tecken i XML (specifikt U+FFFE eller U+FFFF). Om det kodas innehåller elementet Name, Prefix eller EnumerationResults ett Encoded=true attribut. Observera att detta endast sker för de Name elementvärden som innehåller tecknen som är ogiltiga i XML, inte för de återstående Name elementen i svaret.

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

Auktorisering

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

Kommentarer

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

Observera att varje Directory element som returneras räknas mot det maximala resultatet, precis som varje File element gör. Filer och kataloger visas i intermingled, i lexikaliskt sorterad ordning i svarstexten.

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

Se även

Åtgärder på kataloger