Список общих папок

Статья
07/19/2023

Операция List Shares возвращает список общих папок и моментальных снимков общих папок в указанной учетной записи. Этот API полностью поддерживается, но это устаревший API управления. Вместо этого используйте общие папки — список, предоставляемые поставщиком ресурсов хранилища (Microsoft.Storage). Дополнительные сведения о программном взаимодействии с FileShare ресурсами с помощью поставщика ресурсов хранилища см. в разделе Операции с общими папками.

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

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

Запрос

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

Метод	Универсальный код ресурса (URI) запроса	параметр "Версия HTTP"
`GET`	`https://myaccount.file.core.windows.net/?comp=list`	HTTP/1.1

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

Компонент path	Описание
`myaccount`	Имя учетной записи хранения.

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

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

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

Параметр	Описание
`prefix`	Необязательный элемент. Фильтрует результаты для возврата только общих папок с именами, начинающимися с указанного префикса.
`marker`	Необязательный элемент. Строковое значение, которое определяет часть списка для возвращения со следующей операцией списка. Операция возвращает значение маркера в тексте ответа, если возвращенный список не был завершен. Затем можно использовать значение маркера в последующем вызове, чтобы запросить следующий набор элементов списка. Значение маркера непрозрачно для клиента.
`maxresults`	Необязательный элемент. Указывает максимальное количество возвращаемых общих ресурсов. Если в запросе не указано `maxresults`значение или указано значение больше 5000, сервер вернет до 5000 элементов. Если для параметра задано значение ниже нуля или равное нулю, сервер возвращает код состояния 400 (неправильный запрос).
`include=metadata,snapshots,deleted`	Необязательный элемент. Задает один или несколько наборов данных для включения в ответ. - `snapshots`: версия 17.04.2017 и более поздние. Указывает, что моментальные снимки общих ресурсов должны быть включены в ответ. Моментальные снимки общих ресурсов перечислены в ответе от самых старых к новым. - `metadata`: указывает, что в ответе должны быть возвращены метаданные общего ресурса. - `deleted`: указывает, что удаленные общие папки должны быть включены в ответ. Для указания более одного из этих параметров в URI необходимо отделять каждый параметр в URL-представлении запятой (" %82"). Все имена метаданных должны соответствовать соглашениям об именовании для идентификаторов C#.
`timeout`	Необязательный элемент. Параметр `timeout` указывается в секундах. Дополнительные сведения см. в разделе Настройка времени ожидания для Файлы Azure операций.

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

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

Заголовок запроса	Описание
`Authorization`	Обязательный. Указывает схему авторизации, имя учетной записи и подпись. Дополнительные сведения см. в статье Авторизация запросов к Службе хранилища Azure.
`Date` или `x-ms-date`	Обязательный. Задает время запроса в формате UTC. Дополнительные сведения см. в статье Авторизация запросов к Службе хранилища Azure.
`x-ms-version`	Требуется для всех авторизованных запросов. Задает версию операции, используемой для этого запроса. Дополнительные сведения см. в разделе Управление версиями для служб хранилища Azure.
`x-ms-client-request-id`	Необязательный элемент. Предоставляет созданное клиентом непрозрачное значение с ограничением в 1 кибибайт (КиБ), которое записывается в журналы при настройке ведения журнала. Мы настоятельно рекомендуем использовать этот заголовок для сопоставления действий на стороне клиента с запросами, получаемыми сервером. Дополнительные сведения см. в разделе Мониторинг Файлы Azure.

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

Нет.

Ответ

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

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

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

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

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

Заголовок ответа	Описание
`Content-Type`	Стандартный заголовок HTTP/1.1. Задает формат, в котором возвращаются результаты. В настоящее время это значение равно `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 version="1.0" encoding="utf-8"?>  
<EnumerationResults AccountName="https://myaccount.file.core.windows.net">  
  <Prefix>string-value</Prefix>  
  <Marker>string-value</Marker>  
  <MaxResults>int-value</MaxResults>  
  <Shares>  
    <Share>  
      <Name>share-name</Name>  
      <Snapshot>Date-Time Value</Snapshot>
      <Version>01D2AC0C18EDFE36</Version> 
      <Deleted>true</Deleted>  
      <Properties>  
        <Last-Modified>date/time-value</Last-Modified>  
        <Etag>etag</Etag>  
        <Quota>max-share-size</Quota>
        <DeletedTime>Mon, 24 Aug 2020 04:56:10 GMT</DeletedTime>  
        <RemainingRetentionDays>360</RemainingRetentionDays>
        <AccessTier>TransactionOptimized</AccessTier>
        <AccessTierChangeTime>Mon, 24 Aug 2020 03:56:10 GMT</AccessTierChangeTime>
        <AccessTierTransitionState>pending-from-cool</AccessTierTransitionState>
        <EnabledProtocols>SMB</EnabledProtocols>
      </Properties>  
      <Metadata>  
        <metadata-name>value</metadata-name>  
      </Metadata>  
    </Share>  
  </Shares>  
  <NextMarker>marker-value</NextMarker>  
</EnumerationResults>

Элемент EnabledProtocols отображается в тексте ответа только в версии 2020-02-10 и более поздних.
Элемент RootSquash отображается в тексте ответа только в версии 2020-02-10 и более поздних, если включенные протоколы содержат NFS.
Элемент Quota отображается в тексте ответа только в версии 2015-02-21 и более поздних версиях.
Элементы Version, Deleted, DeletedTimeи RemainingRetentionDays отображаются в тексте ответа только в версии 2019-12-12 и более поздних версиях.
Элементы Prefix, Markerи MaxResults присутствуют только в том случае, если они указаны в универсальном коде ресурса (URI). Элемент NextMarker имеет значение только в том случае, если результаты списка не завершены.
Элемент Metadata присутствует только в том случае, если вы указали include=metadata параметр в URI. В элементе Metadata значение для каждой пары "имя-значение" приводится с элементом, соответствующим имени в паре.
Моментальные снимки включаются в ответ только в том случае, если в URI запроса указанinclude=snapshots параметр с параметром include .
Элемент AccessTier содержит уровень общей папки. Если уровень общей папки не был изменен, это свойство будет уровнем TransactionOptimized по умолчанию для учетных записей хранения общего назначения версии 2 (GPv2). В Файлы Azure учетных записей хранения свойство будет иметь значение Premium, которое является единственным поддерживаемым уровнем.
Элемент AccessTierChangeTime присутствует только в том случае, если вы явно задали уровень доступа в общей папке.
Элемент AccessTierTransitionState присутствует только в том случае, если общая папка переходит с одного уровня на другой. Он указывает уровень, с который выполняется переход.
Элемент ProvisionedIngressMBps присутствует только для Premium Файлы Azure учетных записей и версии 2019-07-07 или более поздней. В нем отображается подготовленный входящий трафик в МиБ/с.
Элемент ProvisionedEgressMBps присутствует только для Premium Файлы Azure учетных записей и версии 2019-07-07 или более поздней. В нем отображается подготовленный исходящий трафик в МиБ/с.
Элемент ProvisionedBandwidthMiBps присутствует только для Premium Файлы Azure учетных записей и версии 2021-02-12 или более поздней. Здесь отображается подготовленная пропускная способность (входящий и исходящий трафик вместе взятые) в МиБ/с.

Пример ответа

См. раздел Пример запроса и ответа далее в этом разделе.

Авторизация

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

Если задано значение для maxresults параметра , а количество возвращаемых общих папок превышает это значение или превышает значение по умолчанию для maxresults, текст ответа содержит NextMarker элемент . Этот элемент указывает следующую общую папку, возвращаемую при последующем запросе. Чтобы вернуть следующий набор элементов, укажите значение NextMarker в качестве параметра маркера в URI в последующем запросе.

Обратите внимание, что значение NextMarker должно обрабатываться как непрозрачное.

Общие ресурсы в тексте ответа перечисляются в алфавитном порядке.

Время ожидания для операции List Shares истекает через 30 секунд.

Пример запроса и ответа

Следующий пример URI запрашивает список общих папок для учетной записи. Он задает для начальной операции максимальное количество возвращаемых результатов в три.

GET https://myaccount.file.core.windows.net/?comp=list&maxresults=3&include=snapshots HTTP/1.1

Запрос отправлен с такими заголовками.

x-ms-version: 2020-02-10  
x-ms-date: <date>  
Authorization: SharedKey myaccount:CY1OP3O3jGFpYFbTCBimLn0Xov0vt0khH/D5Gy0fXvg=

Возвращены следующие код состояния и заголовки ответа.

HTTP/1.1 200 OK  
Transfer-Encoding: chunked  
Content-Type: application/xml  
Date: <date>  
x-ms-version: 2020-02-10  
Server: Windows-Azure-File/1.0 Microsoft-HTTPAPI/2.0

XML ответа для этого запроса будет следующим. Обратите внимание, что NextMarker элемент следует за набором общих папок и включает имя следующего возвращаемого общего ресурса.

<?xml version="1.0" encoding="utf-8"?>  
<EnumerationResults ServiceEndpoint=" https://myaccount.file.core.windows.net">  
  <MaxResults>3</MaxResults>  
  <Shares>  
    <Share>  
      <Name>audio</Name>  
      <Properties>  
        <Last-Modified><date></Last-Modified>  
        <Etag>0x8CACB9BD7C6B1B2</Etag>  
        <Quota>55</Quota>
        <AccessTier>Premium</AccessTier>
        <EnabledProtocols>SMB</EnabledProtocols>
      </Properties>  
    </Share>  
    <Share>  
      <Name>images</Name>  
      <Properties>  
        <Last-Modified><date></Last-Modified>  
        <Etag>0x8CACB9BD7C1EEEC</Etag>
        <AccessTier>Premium</AccessTier>
        <EnabledProtocols>SMB</EnabledProtocols>
      </Properties>  
    </Share>  
    <Share>
      <Name>textfiles</Name>
      <Snapshot>2017-05-12T20:52:22.0000000Z</Snapshot>
      <Properties>
        <Last-Modified><date></Last-Modified>
        <Etag>0x8D3F2E1A9D14700</Etag>
        <Quota>30</Quota>
        <AccessTier>Premium</AccessTier>
        <EnabledProtocols>NFS</EnabledProtocols>
        <RootSquash>RootSquash</RootSquash>
      </Properties>
    </Share>
    <Share>  
      <Name>textfiles</Name>  
      <Properties>  
        <Last-Modified><date></Last-Modified>  
        <Etag>0x8CACB9BD7BACAC3</Etag>  
        <Quota>30</Quota>
        <AccessTier>Premium</AccessTier>
        <EnabledProtocols>NFS</EnabledProtocols>
        <RootSquash>AllSquash</RootSquash>  
      </Properties>  
    </Share>
  </Shares>  
  <NextMarker>video</NextMarker>  
</EnumerationResults>

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

https://myaccount.file.core.windows.net/?comp=list&maxresults=3&marker=video

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

REST API для Файлов Azure

Share via