Поделиться через

Список каталогов и файлов

  • Статья

Операция List Directories and Files возвращает список файлов или каталогов в указанной общей папке или каталоге. Он содержит содержимое только для одного уровня иерархии каталогов. Эта операция поддерживается в версии 2025-05-05 и более поздних версий для общих папок с включенным протоколом NFS.

Доступность протокола

Протокол общей папки с включенным доступом Доступный
SMB Да
NFS Да

Просьба

Запрос List Directories and Files создается следующим образом. Рекомендуется использовать ПРОТОКОЛ HTTPS.

Метод URI запроса ВЕРСИЯ HTTP
ПОЛУЧИТЬ https://myaccount.file.core.windows.net/myshare/mydirectorypath?restype=directory&comp=list HTTP/1.1
ПОЛУЧИТЬ https://myaccount.file.core.windows.net/myshare/mydirectorypath?restype=directory&sharesnapshot=<DateTime>&comp=list HTTP/1.1

Замените компоненты пути, отображаемые в URI запроса собственным, следующим образом:

Компонент path Описание
myaccount Имя учетной записи хранения.
myshare Имя общей папки.
mydirectorypath Путь к каталогу.

Дополнительные сведения об ограничениях именования путей см. в разделе Именование и ссылка на общие папки, каталоги, файлы и метаданные.

Параметры URI

В URI можно указать следующие дополнительные параметры.

Общие параметры URI

Параметр Описание
prefix Необязательный. Версия 2016-05-31 и более поздних версий. Фильтрует результаты, чтобы возвращать только файлы и каталоги с именами, начинающимися с указанного префикса.
sharesnapshot Необязательный. Версия 2017-04-17 и более поздних версий. Параметр моментального снимка общего ресурса — это непрозрачное DateTime значение, указывающее моментальный снимок общего ресурса для запроса списка файлов и каталогов.
marker Необязательный. Строковое значение, определяющее часть списка, возвращаемую с помощью следующей операции списка. Операция возвращает значение маркера в теле ответа, если возвращенный список не был завершен. Затем можно использовать значение маркера в последующем вызове для запроса следующего набора элементов списка.

Значение маркера непрозрачно для клиента.
maxresults Необязательный. Указывает максимальное количество возвращаемых файлов или каталогов. Если запрос не указывает maxresultsили задает значение, превышающее 5000, сервер возвращает до 5000 элементов.

Задание maxresults значением меньше или равно нулю приводит к коду ответа об ошибке 400 (недопустимый запрос).
timeout Необязательный. Параметр timeout выражается в секундах. Дополнительные сведения см. в разделе Настройка времени ожидания операций с файлами Azure.

Параметры SMB только URI

Параметр Описание
include={Timestamps, ETag, Attributes, PermissionKey} При необходимости доступно начиная с версии 2020-04-08. Указывает одно или несколько свойств для включения в ответ:
  • Timestamps
  • ETag
  • Attributes (атрибуты файла Win32)
  • PermissionKey

Чтобы указать несколько этих параметров в URI, необходимо разделить каждый параметр с запятой (%82).

Предполагается, что заголовок x-ms-file-extended-info неявно имеет значение true при указании этого параметра.

Только параметры URI NFS

Никакой.

Заголовки запросов

Обязательные и необязательные заголовки запросов описаны в следующих таблицах:

Общие заголовки запросов

Заголовок запроса Описание
Authorization Обязательно. Указывает схему авторизации, имя учетной записи и подпись. Дополнительные сведения см. в статье Авторизация запросов к службе хранилища Azure.
Date или x-ms-date Обязательно. Указывает универсальное время (UTC) для запроса. Дополнительные сведения см. в статье Авторизация запросов к службе хранилища Azure.
x-ms-version Требуется для всех авторизованных запросов. Указывает версию операции, используемой для этого запроса. Эта операция поддерживается в версии 2025-05-05 и более поздних версий для общих папок с включенным протоколом NFS.

Дополнительные сведения см. в разделе Управление версиями служб хранилища Azure.
x-ms-client-request-id Необязательный. Предоставляет созданное клиентом непрозрачное значение с ограничением символов 1-kibibyte (KiB), записанным в журналах при настройке ведения журнала. Настоятельно рекомендуется использовать этот заголовок для сопоставления действий на стороне клиента с запросами, получаемыми сервером. Дополнительные сведения см. в статье Monitor Azure Files.
x-ms-file-request-intent Требуется, если заголовок Authorization указывает токен OAuth. Допустимое значение равно backup. Этот заголовок указывает, что Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action или Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action следует предоставить, если они включены в политику RBAC, назначенную удостоверению, авторизованному с помощью заголовка Authorization. Доступно для версии 2022-11-02 и более поздних версий.
x-ms-allow-trailing-dot: { <Boolean> } Необязательный. Версия 2022-11-02 и более поздних версий. Логическое значение указывает, следует ли обрезать конечную точку в URL-адресе запроса.

Этот заголовок игнорируется, если целевой объект находится в общей папке с включенным протоколом NFS, который поддерживает конечную точку по умолчанию.

Дополнительные сведения см. в разделе Именование и ссылки на общие папки, каталоги, файлы и метаданные.

Только заголовки запросов SMB

Заголовок запроса Описание
x-ms-file-extended-info: {true} Необязательный. Версия 2020-04-08 и более поздних версий. Этот заголовок неявно предполагается, что он имеет значение true, если параметр запроса include не пуст. Если значение true, свойство Content-Length для файлов, указывающее, что размер файла будет обновлен.

Только заголовки запросов NFS

Никакой.

Текст запроса

Никакой.

Ответ

Ответ включает код состояния HTTP, набор заголовков ответов и текст ответа в формате XML.

Код состояния

Успешная операция возвращает код состояния 200 (ОК). Сведения о кодах состояния см. в коды состояния и коды ошибок.

Заголовки ответа

Ответ для этой операции содержит заголовки в следующих таблицах. Ответ также может включать дополнительные стандартные заголовки HTTP. Все стандартные заголовки соответствуют спецификации протокола HTTP/1.1.

Общие заголовки ответов

Заголовок ответа Описание
Content-Type Указывает формат, в котором возвращаются результаты. В настоящее время это значение application/xml.
x-ms-request-id Этот заголовок однозначно идентифицирует выполненный запрос и может использоваться для устранения неполадок запроса. Дополнительные сведения см. в операций API устранения неполадок.
x-ms-version Указывает версию файлов Azure, используемую для выполнения запроса.
Date или x-ms-date Значение даты и времени в формате UTC, указывающее время, в течение которого был инициирован ответ. Служба создает это значение.
x-ms-client-request-id Этот заголовок можно использовать для устранения неполадок запросов и соответствующих ответов. Значение этого заголовка равно значению заголовка x-ms-client-request-id, если он присутствует в запросе. Значение не более 1024 видимых символов ASCII. Если в запросе отсутствует заголовок x-ms-client-request-id, этот заголовок не будет присутствовать в ответе.

Заголовки ответов SMB только

Никакой.

Заголовки ответов NFS только

Никакой.

Текст ответа

Формат XML-ответа выглядит следующим образом.

Элементы Marker, ShareSnapshotи MaxResults присутствуют только в том случае, если указать их в URI запроса. Элемент NextMarker имеет значение, только если результаты списка не завершены.

Элемент Content-Length возвращается в списке для файлов, указывающий размер файла. Однако это значение может не быть up-to-date, так как клиент SMB или NFS, возможно, изменил файл локально. Значение Content-Length может не отражать тот факт, пока дескриптор не будет закрыт, или блокировка операции SMB не будет нарушена. Чтобы получить текущие значения свойств, используйте x-ms-file-extended-info: true для каталога, расположенного в общей папке с включенным протоколом SMB, или вызовите Get File Properties для конкретного файла.

В версиях 2021-12-02 и более поздних версиях List Directory and Files будет кодировать процент (на RFC 2396) все FileName, DirectoryName, Prefix или DirectoryPath значения элементов, которые содержат символы, недопустимые в XML (в частности, U+FFFE или U+FFFF). При кодировании элемент NamePrefix или EnumerationResults будет включать атрибут Encoded=true. Это происходит только для значений элементов Name, содержащих символы, недопустимые в XML, а не остальные Name элементы в ответе.

Текст ответа для общих папок с включенным протоколом 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>

В версиях 2020-04-08, 2020-06-12 и 2020-08-04 FileId возвращается для файлов и каталогов, если заголовок x-ms-file-extended-info имеет значение true. В версии 2020-10-02 и более поздних версий FileId всегда возвращается для файлов и каталогов.

В версии 2020-04-08 include={timestamps} возвращает следующие свойства метки времени: CreationTime, LastAccessTimeи LastWriteTime. В версиях 2020-06-12 и более поздних версиях include={timestamps} возвращает следующие свойства метки времени: CreationTime, LastAccessTime, LastWriteTime, ChangeTimeи Last-Modified.

В версии 2020-10-02 и более поздних версий DirectoryId возвращается в ответе. Он задает FileId каталога, в котором вызывается API.

Текст ответа для общих папок с включенным протоколом 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>

Формат datetime и версия API для полей метки времени

Элемент Формат datetime Пример значения Версия API
CreationTime ISO 8601 2020-09-17T13:38:03.2740000Z 2020-04-08 и более поздних версий
LastAccessTime ISO 8601 2020-09-17T13:38:03.2740000Z 2020-04-08 и более поздних версий
LastWriteTime ISO 8601 2020-09-17T13:38:03.2740000Z 2020-04-08 и более поздних версий
ChangeTime ISO 8601 2020-09-17T13:38:03.2740000Z 2020-06-12 и более поздних версий
Last-Modified RFC 1123 Thu, 17 Sep 2020 13:38:07 GMT 2020-06-12 и более поздних версий

Авторизация

Только владелец учетной записи может вызвать эту операцию.

Замечания

Значение, возвращаемое в элементе Content-Length, соответствует значению заголовка x-ms-content-length файла.

Каждый элемент Directory возвращается к максимальному результату, так же, как и каждый элемент File. Файлы и каталоги перечислены между собой в лексическом порядке в тексте ответа.

Перечисление ограничено одним уровнем иерархии каталогов. Для перечисления нескольких уровней можно выполнять несколько вызовов в итеративном режиме. Используйте значение Directory, возвращаемое из одного результата при последующем вызове List Directories and Files.

См. также

операции с каталогами