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

Статья
03/29/2023

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

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

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

Запрос

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

Метод	Универсальный код ресурса (URI) запроса	параметр "Версия 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

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

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

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

Параметры универсального кода ресурса (URI)

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

Параметр	Описание
`prefix`	Необязательный элемент. Версия 31.05.2016 и более поздняя. Фильтрует результаты, возвращая только файлы и каталоги с именами, начинающимися с указанного префикса.
`sharesnapshot`	Необязательный элемент. Версия 17.04.2017 и более поздняя. Параметр share snapshot является непрозрачным значением`DateTime`, которое при его наличии указывает общий snapshot для запроса списка файлов и каталогов.
`marker`	Необязательный элемент. Строковое значение, которое определяет часть списка для возвращения со следующей операцией списка. Операция возвращает значение маркера в теле ответа, если возвращенный список не был завершен. Затем можно использовать значение маркера в последующем вызове, чтобы запросить следующий набор элементов списка. Значение маркера непрозрачно для клиента.
`maxresults`	Необязательный элемент. Указывает максимальное количество возвращаемых файлов или каталогов. Если в запросе не указано `maxresults`или указано значение больше 5000, сервер вернет до 5000 элементов. Установка для `maxresults` значения меньше нуля или равного нулю приводит к возвращению кода ошибки 400 (неправильный запрос).
`include={Timestamps, ETag, Attributes, PermissionKey}`	При необходимости доступен, начиная с версии 2020-04-08. Указывает одно или несколько свойств для включения в ответ: `Timestamps` `ETag` `Attributes` (Атрибуты файла Win32) `PermissionKey` Чтобы указать несколько этих параметров в URI, необходимо разделить каждый параметр запятой в кодировке URL-адреса (`%82`). При указании этого параметра заголовок `x-ms-file-extended-info` неявно считается истинным.
`timeout`	Необязательный элемент. Параметр `timeout` указывается в секундах. Дополнительные сведения см. в разделе Настройка времени ожидания для Файлы Azure операций.

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

В следующей таблице перечислены обязательные и необязательные заголовки запросов.

Заголовок запроса	Описание
`Authorization`	Обязательный элемент. Указывает схему авторизации, имя учетной записи и подпись. Дополнительные сведения см. в статье Авторизация запросов к Службе хранилища Azure.
`Date` или `x-ms-date`	Обязательный. Задает время запроса в формате UTC. Дополнительные сведения см. в статье Авторизация запросов к Службе хранилища Azure.
`x-ms-version`	Требуется для всех авторизованных запросов, необязательно для анонимных запросов. Задает версию операции, используемой для этого запроса. Дополнительные сведения см. в разделе Управление версиями для служб хранилища Azure.
`x-ms-client-request-id`	Необязательный элемент. Предоставляет созданное клиентом непрозрачное значение с ограничением в 1 кибибайт (КиБ), которое записывается в журналы при настройке ведения журнала. Мы настоятельно рекомендуем использовать этот заголовок для сопоставления действий на стороне клиента с запросами, получаемыми сервером. Дополнительные сведения см. в разделе Мониторинг Файлы Azure.
`x-ms-file-extended-info: {true}`	Необязательный элемент. Версия 2020-04-08 и более поздняя. Этот заголовок неявно считается истинным `include` , если параметр запроса не пуст. Если значение равно true, `Content-Length` свойство будет обновлено. В версиях 2020-04-08, 2020-06-12 и 2020-08-04 возвращается для файлов и каталогов, `FileId` только если этот заголовок имеет значение true. В версиях 2020-10-02 и более поздних `FileId` всегда возвращается для файлов и каталогов.
`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> }`	Необязательный элемент. Версия 02.11.2022 и более поздняя. Логическое значение указывает, следует ли обрезать завершающую точку в URL-адресе запроса. Дополнительные сведения см. в статье Именование общих папок, каталогов, файлов и метаданных и ссылки на нее.

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

Нет.

Ответ

Ответ включает код состояния 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` отсутствует в запросе, он не будет присутствовать в ответе.

Текст ответа

XML-ответ имеет следующий формат.

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

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

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

В версиях 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.

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

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

Элемент	Формат даты и времени	Образец значения	Версия API
`CreationTime`	ISO 8601	`2020-09-17T13:38:03.2740000Z`	08.04.2020 и более поздние версии
`LastAccessTime`	ISO 8601	`2020-09-17T13:38:03.2740000Z`	08.04.2020 и более поздние версии
`LastWriteTime`	ISO 8601	`2020-09-17T13:38:03.2740000Z`	08.04.2020 и более поздние версии
`ChangeTime`	ISO 8601	`2020-09-17T13:38:03.2740000Z`	12.06.2020 и более поздние версии
`Last-Modified`	RFC 1123	`Thu, 17 Sep 2020 13:38:07 GMT`	12.06.2020 и более поздние версии

Авторизация

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

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

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

См. также раздел

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