Udostępnij za pośrednictwem

Wyświetlanie listy katalogów i plików

  • Artykuł

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 pojedynczego poziomu hierarchii katalogów. Ta operacja jest obsługiwana w wersji 2025-05-05 i nowszych dla udziałów plików z włączonym protokołem NFS.

Dostępność protokołu

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

Prosić

Żądanie List Directories and Files jest konstruowane w następujący sposób. Zalecamy używanie protokołu HTTPS.

Metoda Identyfikator URI żądania Wersja PROTOKOŁU HTTP
POBIERZ https://myaccount.file.core.windows.net/myshare/mydirectorypath?restype=directory&comp=list HTTP/1.1
POBIERZ 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 we własnym identyfikatorze URI żądania, 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.

Typowe parametry identyfikatora URI

Parametr Opis
prefix Fakultatywny. 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 Fakultatywny. Wersja 2017-04-17 lub nowsza. Parametr migawki udziału jest nieprzezroczystą wartością DateTime, która w chwili obecnej określa migawkę udziału, aby wykonać zapytanie dotyczące listy plików i katalogów.
marker Fakultatywny. 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 Fakultatywny. Określa maksymalną liczbę plików lub katalogów do zwrócenia. Jeśli żądanie nie określi maxresultslub określa wartość większą niż 5000, serwer zwraca maksymalnie 5000 elementów.

Ustawienie maxresults wartości mniejszej lub równej zero powoduje wyświetlenie kodu odpowiedzi błędu 400 (nieprawidłowe żądanie).
timeout Fakultatywny. Parametr timeout jest wyrażony w sekundach. Aby uzyskać więcej informacji, zobacz Ustawianie limitów czasu dla operacji usługi Azure Files.

Parametry identyfikatora URI tylko protokołu SMB

Parametr Opis
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 przyjmuje się, że x-ms-file-extended-info nagłówka ma wartość true.

Tylko parametry identyfikatora URI systemu plików NFS

Żaden.

Nagłówki żądań

Wymagane i opcjonalne nagłówki żądań są opisane w następujących tabelach:

Typowe 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 uniwersalny czas koordynowany (UTC) dla żądania. Aby uzyskać więcej informacji, zobacz Autoryzowanie żądań do usługi Azure Storage.
x-ms-version Wymagane dla wszystkich autoryzowanych żądań. Określa wersję operacji do użycia dla tego żądania. Ta operacja jest obsługiwana w wersji 2025-05-05 i nowszych dla udziałów plików z włączonym protokołem NFS.

Aby uzyskać więcej informacji, zobacz Przechowywanie wersji dla usług Azure Storage.
x-ms-client-request-id Fakultatywny. Zapewnia nieprzezroczystą wartość wygenerowaną przez klienta z limitem znaków 1-kibibyte (KiB), który jest rejestrowany 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 Monitor Azure Files.
x-ms-file-request-intent Wymagane, jeśli nagłówek Authorization określa token OAuth. Akceptowalna wartość to backup. Ten nagłówek określa, że Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action lub Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action należy przyznać, jeśli są one uwzględnione w zasadach RBAC przypisanych do tożsamości autoryzowanej przy użyciu nagłówka Authorization. Dostępne dla wersji 2022-11-02 lub nowszej.
x-ms-allow-trailing-dot: { <Boolean> } Fakultatywny. 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.

Ten nagłówek jest ignorowany, jeśli element docelowy znajduje się w udziale plików z włączonym protokołem NFS, który domyślnie obsługuje kropkę końcową.

Aby uzyskać więcej informacji, zobacz Nazewnictwo i odwoływanie się do udziałów, katalogów, plików i metadanych.

Tylko nagłówki żądań protokołu SMB

Nagłówek żądania Opis
x-ms-file-extended-info: {true} Fakultatywny. Wersja 2020-04-08 lub nowsza. Ten nagłówek jest niejawnie zakładany jako true, jeśli parametr zapytania include nie jest pusty. Jeśli wartość true, właściwość Content-Length dla plików, która wskazuje, że rozmiar pliku będzie aktualny.

Nagłówki żądań NFS

Żaden.

Treść żądania

Żaden.

Odpowiedź

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 Stan i kody błędów.

Nagłówki odpowiedzi

Odpowiedź dla tej operacji zawiera nagłówki w poniższych tabelach. Odpowiedź może również zawierać dodatkowe standardowe nagłówki HTTP. Wszystkie standardowe nagłówki są zgodne ze specyfikacją protokołu HTTP/1.1 .

Typowe nagłówki odpowiedzi

Nagłówek odpowiedzi Opis
Content-Type Określa format, w którym są zwracane wyniki. Obecnie ta wartość jest 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ę usługi Azure Files używaną do uruchomienia żądania.
Date lub x-ms-date Wartość daty/godziny UTC wskazująca godzinę, o 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 odpowiedziami. Wartość tego nagłówka jest równa wartości nagłówka x-ms-client-request-id, jeśli jest obecna w żądaniu. Wartość jest najwyżej 1024 widocznymi znakami ASCII. Jeśli nagłówek x-ms-client-request-id nie znajduje się w żądaniu, ten nagłówek nie będzie obecny w odpowiedzi.

Tylko nagłówki odpowiedzi protokołu SMB

Żaden.

Nagłówki odpowiedzi tylko systemu plików NFS

Żaden.

Treść odpowiedzi

Format odpowiedzi XML jest następujący.

Elementy Marker, 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.

Element Content-Length jest zwracany na liście plików, co wskazuje rozmiar pliku. Jednak ta wartość może nie być up-to-date, ponieważ klient SMB lub NFS mógł zmodyfikować plik lokalnie. Wartość Content-Length może nie odzwierciedlać tego faktu do momentu zamknięcia uchwytu lub przerwania blokady operacji SMB. Aby pobrać bieżące wartości właściwości, użyj x-ms-file-extended-info: true dla katalogu znajdującego się w udziale plików z włączonym protokołem SMB lub wywołaj Pobierz właściwości pliku względem określonego pliku.

W wersjach 2021-12-02 i nowszych List Directory and Files będzie kodować procent (na RFC 2396) wszystkie FileName, DirectoryName, Prefix lub DirectoryPath wartości elementów, które zawierają nieprawidłowe znaki w XML (w szczególności U+FFFE lub U+FFFF). W przypadku kodowania element Name, Prefix lub EnumerationResults będzie zawierać atrybut Encoded=true. Dzieje się tak tylko w przypadku wartości elementu Name zawierającego nieprawidłowe znaki w pliku XML, a nie pozostałych Name elementów w odpowiedzi.

Treść odpowiedzi dla udziałów plików z włączonym protokołem SMB

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

W wersjach 2020-04-08, 2020-06-12 i 2020-08-04 FileId jest zwracany dla plików i katalogów, jeśli nagłówek x-ms-file-extended-info ma wartość true. W wersji 2020-10-02 lub nowszej FileId jest zawsze 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 2020-06-12 i nowszych program include={timestamps} zwraca następujące właściwości znacznika czasu: CreationTime, LastAccessTime, LastWriteTime, ChangeTimei Last-Modified.

W wersji 2020-10-02 lub nowszej DirectoryId jest zwracana w odpowiedzi. Określa FileId katalogu, w którym jest wywoływany interfejs API.

Treść odpowiedzi dla udziałów plików z włączonym protokołem NFS

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

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

Pierwiastek Format daty/godziny Przykładowa wartość 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 elemektorze Content-Length odpowiada wartości nagłówka x-ms-content-length pliku.

Każdy element Directory zwracany jest w kierunku maksymalnego wyniku, podobnie jak każdy element File. Pliki i katalogi są wymienione w kolejności posortowanej leksycznie w treści odpowiedzi.

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

Zobacz też

operacje w katalogach