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

Статья
08/07/2024

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

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

Протокол общей папки с включенным доступом	Доступный
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, сервер вернет до 5 000 элементов. Если для параметра задано значение меньше нуля или равно нулю, сервер вернет код состояния 400 (недопустимый запрос).
`include=metadata,snapshots,deleted`	Необязательный. Указывает один или несколько наборов данных для включения в ответ: - `snapshots`: версия 2017-04-17 и более поздних версий. Указывает, что моментальные снимки общего ресурса должны быть включены в ответ. Моментальные снимки общего доступа перечислены от старых до самых новых в ответе. - `metadata`. Указывает, что метаданные общего ресурса должны быть возвращены в ответе. - `deleted`. Указывает, что удаленные общие папки должны быть включены в ответ. Чтобы указать несколько этих параметров в URI, необходимо разделить каждый параметр с запятой ("%82"). Все имена метаданных должны соответствовать соглашениям об именовании для идентификаторов C#.
`timeout`	Необязательный. Параметр `timeout` выражается в секундах. Дополнительные сведения см. в разделе Настройка времени ожидания операций с файлами Azure.

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

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

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

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

Никакой.

Ответ

Ответ включает код состояния 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>
        <PaidBurstingEnabled>true</PaidBurstingEnabled>
        <PaidBurstingMaxIops>20000</PaidBurstingMaxIops>
        <PaidBurstingMaxBandwidthMibps>4000</PaidBurstingMaxBandwidthMibps>
      </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 значение каждой пары name-value указывается в элементе, соответствующем имени пары.
Моментальные снимки включаются в ответ только в том случае, если указать параметрinclude=snapshots с параметром include в URI запроса.
Элемент AccessTier содержит уровень общей папки. Если уровень общей папки не был изменен, это свойство будет уровнем по умолчанию TransactionOptimized в учетных записях хранения общего назначения 2 (GPv2). В учетных записях хранения файлов Azure свойство будет Premium, которое является единственным поддерживаемым уровнем.
Элемент AccessTierChangeTime присутствует только в том случае, если вы явно задали уровень доступа в общей папке.
Элемент AccessTierTransitionState присутствует только в том случае, если общая папка переходит с одного уровня на другой. Он указывает уровень, с который он переходит.
Элемент ProvisionedIngressMBps присутствует только для учетных записей Premium службы "Файлы Azure" и версии 2019-07-07 или более поздней. В нем показаны подготовленные входящий трафик в MiB/s.
Элемент ProvisionedEgressMBps присутствует только для учетных записей Premium службы "Файлы Azure" и версии 2019-07-07 или более поздней. В нем показаны подготовленные исходящие данные в MiB/s.
Элемент ProvisionedBandwidthMiBps присутствует только для учетных записей Premium файлов Azure и версии 2021-02-12 или более поздней. В нем показана подготовленная пропускная способность (входящего и исходящего трафика) в MiB/s.
Элемент EnableSnapshotVirtualDirectoryAccess отображается в тексте ответа только в версии 2024-08-04 и более поздних версиях, если включенные протоколы содержат NFS. Этот элемент будет возвращен только для общих папок, а не для моментальных снимков.
Элемент PaidBurstingEnabled присутствует только для учетных записей службы "Файлы Azure" Premium версии 2024-11-04 или более поздней. Этот элемент будет возвращен только для общих папок, а не для моментальных снимков.
Элемент PaidBurstingMaxIops присутствует только для учетных записей службы "Файлы Azure" Premium версии 2024-11-04 или более поздней. Он будет возвращен только в том случае, если для общей папки имеет значение PaidBurstingEnabled. Этот элемент будет возвращен только для общих папок, а не для моментальных снимков.
Элемент PaidBurstingMaxBandwidthMibps присутствует только для учетных записей службы "Файлы Azure" Premium версии 2024-11-04 или более поздней. Он будет возвращен только в том случае, если для общей папки имеет значение PaidBurstingEnabled. Этот элемент будет возвращен только для общих папок, а не для моментальных снимков.

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

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

Авторизация

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

Замечания

Если указать значение параметра 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>
      </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

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