Wyświetlanie listy katalogów i plików

Artykuł
03/29/2023

Operacja List Directories and Files zwraca listę plików lub katalogów w określonym udziale lub katalogu. Wyświetla on listę zawartości tylko dla jednego poziomu hierarchii katalogów.

Dostępność protokołu

Włączony protokół udziału plików	Dostępne
SMB
NFS

Żądanie

Żądanie można skonstruować List Directories and Files w następujący sposób. Zalecane jest użycie protokołu HTTPS.

Metoda	Identyfikator URI żądania	Wersja PROTOKOŁU HTTP
`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

Zastąp składniki ścieżki wyświetlane w identyfikatorze URI żądania własnymi elementami w następujący sposób:

Składnik ścieżki	Opis
`myaccount`	Nazwa konta magazynu.
`myshare`	Nazwa udziału plików.
`mydirectorypath`	Ścieżka do katalogu.

Aby uzyskać szczegółowe informacje na temat ograniczeń nazewnictwa ścieżek, zobacz Nazewnictwo i odwoływanie się do udziałów, katalogów, plików i metadanych.

Parametry identyfikatora URI

W identyfikatorze URI można określić następujące dodatkowe parametry.

Parametr	Opis
`prefix`	Opcjonalny. Wersja 2016-05-31 lub nowsza. Filtruje wyniki, aby zwracać tylko pliki i katalogi, które mają nazwy rozpoczynające się od określonego prefiksu.
`sharesnapshot`	Opcjonalny. Wersja 2017-04-17 lub nowsza. Parametr migawki udziału jest nieprzezroczystą `DateTime` wartością, która w chwili obecnej określa migawkę udziału, która będzie wysyłać zapytania o listę plików i katalogów.
`marker`	Opcjonalny. Wartość ciągu identyfikującą część listy, która ma zostać zwrócona przy użyciu następnej operacji listy. Operacja zwraca wartość znacznika w treści odpowiedzi, jeśli zwrócona lista nie została ukończona. Następnie możesz użyć wartości znacznika w kolejnym wywołaniu, aby zażądać następnego zestawu elementów listy. Wartość znacznika jest nieprzezroczysta dla klienta.
`maxresults`	Opcjonalny. Określa maksymalną liczbę plików lub katalogów do zwrócenia. Jeśli żądanie nie określi `maxresults`wartości lub określa wartość większą niż 5000, serwer zwróci do 5000 elementów. Ustawienie `maxresults` wartości mniejszej lub równej zero powoduje wyświetlenie kodu odpowiedzi błędu 400 (Nieprawidłowe żądanie).
`include={Timestamps, ETag, Attributes, PermissionKey}`	Opcjonalnie dostępne, począwszy od wersji 2020-04-08. Określa co najmniej jedną właściwość do uwzględnienia w odpowiedzi: `Timestamps` `ETag` `Attributes` (Atrybuty pliku Win32) `PermissionKey` Aby określić więcej niż jedną z tych opcji w identyfikatorze URI, należy oddzielić każdą opcję przecinkiem zakodowanym pod adresem URL (`%82`). W przypadku określenia tego parametru nagłówek `x-ms-file-extended-info` jest niejawnie zakładany jako true.
`timeout`	Opcjonalny. Parametr jest wyrażony `timeout` w sekundach. Aby uzyskać więcej informacji, zobacz Ustawianie limitów czasu dla operacji Azure Files.

Nagłówki żądań

W poniższej tabeli opisano wymagane i opcjonalne nagłówki żądań.

Nagłówek żądania	Opis
`Authorization`	Wymagane. Określa schemat autoryzacji, nazwę konta i podpis. Aby uzyskać więcej informacji, zobacz Autoryzowanie żądań do usługi Azure Storage.
`Date` lub `x-ms-date`	Wymagane. Określa dla żądania godzinę w formacie uniwersalnego czasu koordynowanego (UTC). Aby uzyskać więcej informacji, zobacz Autoryzowanie żądań do usługi Azure Storage.
`x-ms-version`	Wymagane dla wszystkich autoryzowanych żądań, opcjonalnie dla żądań anonimowych. Określa wersję operacji do użycia dla tego żądania. Aby uzyskać więcej informacji, zobacz Przechowywanie wersji dla usług Azure Storage.
`x-ms-client-request-id`	Opcjonalny. Zapewnia nieprzezroczystą wartość wygenerowaną przez klienta z limitem znaków 1-kibibyte (KiB) rejestrowanym w dziennikach podczas konfigurowania rejestrowania. Zdecydowanie zalecamy używanie tego nagłówka do korelowania działań po stronie klienta z żądaniami odbieranymi przez serwer. Aby uzyskać więcej informacji, zobacz Monitorowanie Azure Files.
`x-ms-file-extended-info: {true}`	Opcjonalny. Wersja 2020-04-08 lub nowsza. Zakłada się, że ten nagłówek ma wartość true, jeśli `include` parametr zapytania nie jest pusty. Jeśli wartość true, `Content-Length` właściwość będzie aktualna. W wersjach 2020-04-08, 2020-06-12 i 2020-08-04 jest zwracany dla plików i katalogów tylko wtedy, `FileId` gdy ten nagłówek ma wartość true. W wersjach 2020-10-02 i nowszych `FileId` są zawsze zwracane dla plików i katalogów.
`x-ms-file-request-intent`	Wymagane, jeśli `Authorization` nagłówek określa token OAuth. Akceptowalna wartość to `backup`. Ten nagłówek określa, czy `Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action` element lub `Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action` ma zostać przyznany, jeśli są one uwzględnione w zasadach RBAC przypisanych do tożsamości, która jest autoryzowana przy użyciu nagłówka `Authorization` . Dostępne dla wersji 2022-11-02 lub nowszej.
`x-ms-allow-trailing-dot: { <Boolean> }`	Opcjonalny. Wersja 2022-11-02 lub nowsza. Wartość logiczna określa, czy końcowa kropka obecna w adresie URL żądania powinna zostać przycięta, czy nie. Aby uzyskać więcej informacji, zobacz Nazewnictwo i odwoływanie się do udziałów, katalogów, plików i metadanych.

Treść żądania

Brak.

Reakcja

Odpowiedź zawiera kod stanu HTTP, zestaw nagłówków odpowiedzi i treść odpowiedzi w formacie XML.

Kod stanu

Pomyślna operacja zwraca kod stanu 200 (OK). Aby uzyskać informacje o kodach stanu, zobacz Kody stanu i błędów.

Nagłówki odpowiedzi

Odpowiedź na tę operację zawiera następujące nagłówki. Odpowiedź może również zawierać dodatkowe standardowe nagłówki HTTP. Wszystkie standardowe nagłówki są zgodne ze specyfikacją protokołu HTTP/1.1.

Nagłówek odpowiedzi	Opis
`Content-Type`	Określa format, w którym są zwracane wyniki. Obecnie ta wartość to `application/xml`.
`x-ms-request-id`	Ten nagłówek jednoznacznie identyfikuje wykonane żądanie i może służyć do rozwiązywania problemów z żądaniem. Aby uzyskać więcej informacji, zobacz Rozwiązywanie problemów z operacjami interfejsu API.
`x-ms-version`	Wskazuje wersję Azure Files użytą do uruchomienia żądania.
`Date` lub `x-ms-date`	Wartość daty/godziny UTC wskazująca godzinę, w której zainicjowano odpowiedź. Usługa generuje tę wartość.
`x-ms-client-request-id`	Ten nagłówek służy do rozwiązywania problemów z żądaniami i odpowiadającymi im odpowiedziami. Wartość tego nagłówka jest równa wartości `x-ms-client-request-id` nagłówka, jeśli jest obecna w żądaniu. Wartość wynosi co najwyżej 1024 widoczne znaki ASCII. `x-ms-client-request-id` Jeśli nagłówek nie znajduje się w żądaniu, ten nagłówek nie będzie obecny w odpowiedzi.

Treść odpowiedzi

Format odpowiedzi XML jest następujący.

Należy pamiętać, że Markerelementy , ShareSnapshoti MaxResults są obecne tylko wtedy, gdy określisz je na identyfikatorze URI żądania. Element NextMarker ma wartość tylko wtedy, gdy wyniki listy nie zostaną ukończone.

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

Należy pamiętać, że Content-Length element jest zwracany na liście. Jednak ta wartość może nie być aktualna, ponieważ klient SMB mógł lokalnie zmodyfikować plik. Wartość może Content-Length nie odzwierciedlać tego faktu, dopóki uchwyt nie zostanie zamknięty lub blokada op-lock zostanie przerwana. Aby pobrać bieżące wartości właściwości, użyj metody x-ms-file-extended-info: truelub wywołaj polecenie Pobierz właściwości pliku.

W wersjach 2020-04-08, 2020-06-12 i 2020-08-04 jest zwracany dla plików i katalogów, FileId jeśli nagłówek x-ms-file-extended-info ma wartość true. W wersji 2020-10-02 i nowszej FileId zawsze jest zwracany dla plików i katalogów.

W wersji 2020-04-08 include={timestamps} zwraca następujące właściwości znacznika czasu: CreationTime, LastAccessTimei LastWriteTime. W wersji i nowszych 2020-06-12include={timestamps} zwraca następujące właściwości znacznika czasu: CreationTime, LastAccessTime, LastWriteTime, ChangeTimei Last-Modified.

W wersji 2020-10-02 i nowszej DirectoryId zostanie zwrócona w odpowiedzi. Określa FileId katalog, w którym jest wywoływany interfejs API.

W wersjach 2021-12-02 i nowszych List Directory and Files koduje procent (na RFC 2396) wszystkieNameFile wartości , DirectoryNamelub PrefixDirectoryPath elementu, które zawierają znaki nieprawidłowe w xml (w szczególności U+FFFE lub U+FFFF). W przypadku kodowania Nameelement lub PrefixEnumerationResults będzie zawierać Encoded=true atrybut . Należy pamiętać, że wystąpi to tylko dla Name wartości elementów zawierających znaki nieprawidłowe w formacie XML, a nie pozostałych Name elementów w odpowiedzi.

Format daty/godziny i wersja interfejsu API dla pól znacznika czasu

Element	Format daty/godziny	Wartość przykładowa	Wersja interfejsu API
`CreationTime`	ISO 8601	`2020-09-17T13:38:03.2740000Z`	2020-04-08 i nowsze
`LastAccessTime`	ISO 8601	`2020-09-17T13:38:03.2740000Z`	2020-04-08 i nowsze
`LastWriteTime`	ISO 8601	`2020-09-17T13:38:03.2740000Z`	2020-04-08 i nowsze
`ChangeTime`	ISO 8601	`2020-09-17T13:38:03.2740000Z`	2020-06-12 i nowsze
`Last-Modified`	RFC 1123	`Thu, 17 Sep 2020 13:38:07 GMT`	2020-06-12 i nowsze

Autoryzacja

Tylko właściciel konta może wywołać tę operację.

Uwagi

Wartość zwrócona w Content-Length elemecie odpowiada wartości nagłówka x-ms-content-length pliku.

Należy pamiętać, że każdy Directory element zwracany jest zliczany do maksymalnego wyniku, tak jak każdy File element. Pliki i katalogi są wymieniane w kolejności leksykalnie posortowanej w treści odpowiedzi.

Lista jest ograniczona do jednego poziomu hierarchii katalogów. Aby wyświetlić listę wielu poziomów, można wykonać wiele wywołań w sposób iteracyjny. Directory Użyj wartości zwróconej z jednego wyniku w kolejnym wywołaniu metody List Directories and Files.

Zobacz też

Operacje na katalogach

Udostępnij za pośrednictwem