Перечисление контейнеров

  • Статья

Операция List Containers возвращает список контейнеров в указанной учетной записи хранения.

Запрос

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

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

Обратите внимание, что URI должен всегда включать косую черту (/) для отделения имени узла от частей пути и запроса URI. В случае операции List Containers часть пути в URI остается пустой.

Запрос службы эмулированного хранилища

При выполнении запроса к эмулированной службе хранилища укажите имя узла эмулятора и порт Хранилище BLOB-объектов Azure в качестве 127.0.0.1:10000, за которым следует эмулированное имя учетной записи хранения.

Метод Универсальный код ресурса (URI) запроса параметр "Версия HTTP"
GET http://127.0.0.1:10000/devstoreaccount1?comp=list HTTP/1.1

Обратите внимание, что эмулированное хранилище поддерживает только большие двоичные объекты размером до 2 ГиБ.

Дополнительные сведения см. в разделах Использование эмулятора Azurite для разработки локальной службы хранилища Azure и Различия между эмулятором хранилища и службами хранилища Azure.

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

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

Параметр Описание
prefix Необязательный элемент. Фильтрует результаты, чтобы вернуть только контейнеры с именем, начинающимся с указанного префикса.
marker Необязательный элемент. Строковое значение, определяющее часть списка контейнеров, возвращаемых при следующей операции перечисления. Операция возвращает NextMarker значение в тексте ответа, если операция перечисления не вернула все контейнеры, оставшиеся для перечисления с текущей страницей. Значение можно использовать NextMarker в качестве значения параметра marker в последующем вызове, чтобы запросить следующую страницу элементов списка.

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

Обратите внимание, что если операция перечисления пересекает границу секции, служба вернет маркер продолжения для получения оставшихся результатов. По этой причине возможно, что служба вернет меньше результатов, чем указано в maxresultsпараметре , или значение по умолчанию 5000.

Если параметр имеет значение меньше или равно нулю, сервер возвращает код состояния 400 (недопустимый запрос).
include={metadata,deleted,system} Необязательный элемент. Задает один или несколько наборов данных для включения в ответ.

-metadata: обратите внимание, что метаданные, запрашиваемые с помощью этого параметра, должны храниться в соответствии с ограничениями именования, установленными в версии 2009-09-19 Хранилища BLOB-объектов. Начиная с этой версии все имена метаданных должны соответствовать соглашениям об именовании для идентификаторов C#.
-deleted: версия 12.12.2019 и более поздние. Указывает, что обратимо удаленные контейнеры должны быть включены в ответ.
-system: версия 2020-10-02 и более поздние. Указывает, следует ли включать системные контейнеры в ответ. Включение этого параметра приведет к выводу списка системных контейнеров, таких как $logs и $changefeed. Обратите внимание, что возвращаемые конкретные системные контейнеры зависят от того, какие функции службы включены в учетной записи хранения.
timeout Необязательный элемент. Параметр timeout указывается в секундах. Дополнительные сведения см. в разделе Настройка времени ожидания для операций с хранилищем BLOB-объектов.

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

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

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

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

Нет.

Ответ

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

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

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

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

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

Заголовок ответа Описание
Content-Type Стандартный заголовок HTTP/1.1. Задает формат, в котором возвращаются результаты. В настоящее время это значение равно application/xml.
x-ms-request-id Этот заголовок однозначно идентифицирует выполненный запрос и может использоваться для устранения неполадок с запросом. Дополнительные сведения см. в разделе Устранение неполадок операций API.
x-ms-version Указывает версию хранилища BLOB-объектов, используемой для выполнения запроса. Этот заголовок возвращается для запросов к версии 2009-09-19 и более поздним версиям.
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 ServiceEndpoint="https://myaccount.blob.core.windows.net">  
  <Prefix>string-value</Prefix>  
  <Marker>string-value</Marker>  
  <MaxResults>int-value</MaxResults>  
  <Containers>  
    <Container>  
      <Name>container-name</Name>  
      <Version>container-version</Version>
      <Deleted>true</Deleted>
      <Properties>  
        <Last-Modified>date/time-value</Last-Modified>  
        <Etag>etag</Etag>  
        <LeaseStatus>locked | unlocked</LeaseStatus>  
        <LeaseState>available | leased | expired | breaking | broken</LeaseState>  
        <LeaseDuration>infinite | fixed</LeaseDuration> 
        <PublicAccess>container | blob</PublicAccess>
        <HasImmutabilityPolicy>true | false</HasImmutabilityPolicy>
        <HasLegalHold>true | false</HasLegalHold>
        <DeletedTime>datetime</DeletedTime>
        <RemainingRetentionDays>no-of-days</RemainingRetentionDays>
      </Properties>  
      <Metadata>  
        <metadata-name>value</metadata-name>  
      </Metadata>  
    </Container>  
  </Containers>  
  <NextMarker>marker-value</NextMarker>  
</EnumerationResults>

LeaseStatus, LeaseState и LeaseDuration появляются только в версии 2012-02-12 и позднее.

Начиная с версии 2013-08-15, атрибут AccountName для элемента EnumerationResults переименован в ServiceEndpoint. Элемент URL также был удален из элемента Container. Для версий, предшествующих 2013-08-15, URL-адрес контейнера, как указано в URL поле , не включает restype=container параметр . Если это значение используется для последующих запросов к перечисленным контейнерам, то следует обязательно добавлять этот параметр, чтобы указать, что тип ресурса — контейнер.

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

Элемент Metadata присутствует только в том случае, если вы указали include=metadata параметр в URI. В элементе Metadata значение для каждой пары "имя-значение" приводится с элементом, соответствующим имени в паре.

Если пара "имя-значение" метаданных нарушает ограничения именования, применяемые в версии 2009-09-19, текст ответа указывает на проблемное имя в элементе x-ms-invalid-name . Это показано в следующем фрагменте XML:

  
<Metadata>  
  <MyMetadata1>first value</MyMetadata1>  
  <MyMetadata2>second value</MyMetadata2>  
  <x-ms-invalid-name>invalid-metadata-name</x-ms-invalid-name>  
</Metadata>

Начиная с версии 31.05.2016 открытые разрешения контейнера предоставляются в свойстве PublicAccess . Он указывает, можно ли получить общий доступ к данным в контейнере, а также уровень доступа. Возможные значения:

  • container: указывает полный общий доступ на чтение для данных контейнера и BLOB-объектов. Клиенты могут перечислять большие двоичные объекты в контейнере с помощью анонимного запроса, но не могут перечислять контейнеры в учетной записи хранения.
  • blob: указывает общий доступ на чтение для BLOB-объектов. Данные BLOB-объектов в этом контейнере можно считывать с помощью анонимного запроса, но данные контейнера недоступны. Клиенты не могут перечислять большие двоичные объекты в контейнере с помощью анонимного запроса.

Если это свойство не указано в <properties> разделе, контейнер является частным для владельца учетной записи.

HasImmutabilityPolicy и HasLegalHold отображаются только в версии 2017-11-09 и более поздних версиях. HasImmutabilityPolicy Имеет значение , true если для контейнера задана политика неизменяемости, и false в противном случае. HasLegalHold Имеет значение , true если контейнер имеет один или несколько удержаний по юридическим причинам, и false в противном случае.

Примечание

Начиная с версии 2009-09-19, текст ответа для List Containers возвращает время последнего изменения контейнера в элементе с именем Last-Modified. В предыдущих версиях этот элемент назывался LastModified.

Элементы Version, Deleted, DeletedTimeи RemainingRetentiondays отображаются только в версии 2019-12-12 и более поздних, если указано deleted значение параметра includeзапроса . Эти элементы отображаются только в том случае, если контейнер обратимо удален и может быть восстановлен. Элементы Version, Deleted, DeletedTimeи RemainingRetentiondays отображаются только в версии 2019-12-12 и более поздних, если для параметра запроса указано include удаленное значение, а контейнер обратимо удален и допускает восстановление.

Авторизация

При вызове любой операции доступа к данным в службе хранилища Azure требуется авторизация. Вы можете авторизовать List Containers операцию, как описано ниже.

Служба хранилища Azure поддерживает использование Microsoft Entra ID для авторизации запросов к данным BLOB-объектов. С помощью Microsoft Entra ID можно использовать управление доступом на основе ролей Azure (Azure RBAC) для предоставления разрешений субъекту безопасности. Субъект безопасности может быть пользователем, группой, субъектом-службой приложения или управляемым удостоверением Azure. Субъект безопасности проходит проверку подлинности с помощью Microsoft Entra ID для возврата маркера OAuth 2.0. Затем маркер можно использовать для авторизации запроса к службе BLOB-объектов.

Дополнительные сведения об авторизации с помощью Microsoft Entra ID см. в статье Авторизация доступа к BLOB-объектам с помощью Microsoft Entra ID.

Разрешения

Ниже перечислены действия RBAC, необходимые для Microsoft Entra пользователя, группы или субъекта-службы для вызова List Containers операции, а также встроенная роль Azure RBAC с наименьшими привилегиями, которая включает это действие:

Дополнительные сведения о назначении ролей с помощью Azure RBAC см. в статье Назначение роли Azure для доступа к данным BLOB-объектов.

Комментарии

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

NextMarker указывает следующий контейнер, возвращаемый при последующем запросе. Чтобы вернуть следующий набор элементов, укажите значение NextMarker параметра marker в универсальном коде ресурса (URI) для последующего запроса. Обратите внимание, что значение NextMarker должно обрабатываться как непрозрачное.

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

Контейнеры в тексте ответа перечисляются в алфавитном порядке.

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

Выставление счетов

Запросы на ценообразование могут исходить от клиентов, использующих API хранилища BLOB-объектов, напрямую через REST API хранилища BLOB-объектов или из клиентской библиотеки службы хранилища Azure. Эти запросы начисляют плату за каждую транзакцию. Тип транзакции влияет на способ оплаты учетной записи. Например, транзакции чтения начисляются на категорию выставления счетов, отличную от категории операций записи. В следующей таблице показана категория выставления счетов для List Containers запросов на основе типа учетной записи хранения.

Операция Тип учетной записи хранения Категория выставления счетов
Перечисление контейнеров Блочный BLOB-объект (ценовая категории "Премиум")
Общего назначения версии 2 (цен. категория "Стандартный")
Стандартная общего назначения версии 1		 Операции перечисления и создания контейнеров

Дополнительные сведения о ценах для указанной категории выставления счетов см. в разделе Цены на Хранилище BLOB-объектов Azure.

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

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

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

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

x-ms-version: 2016-05-31  
x-ms-date: Wed, 26 Oct 2016 22:08:44 GMT  
Authorization: SharedKey myaccount:CY1OP3O3jGFpYFbTCBimLn0Xov0vt0khH/D5Gy0fXvg=

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

HTTP/1.1 200 OK  
Transfer-Encoding: chunked  
Content-Type: application/xml  
Date: Wed, 26 Oct 2016 22:08:54 GMT  
x-ms-version: 2016-05-31  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0

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

<?xml version="1.0" encoding="utf-8"?>  
<EnumerationResults ServiceEndpoint="https://myaccount.blob.core.windows.net/">  
  <MaxResults>3</MaxResults>  
  <Containers>  
    <Container>  
      <Name>audio</Name>  
      <Properties>  
        <Last-Modified>Wed, 26 Oct 2016 20:39:39 GMT</Last-Modified>  
        <Etag>0x8CACB9BD7C6B1B2</Etag> 
        <PublicAccess>container</PublicAccess> 
      </Properties>  
    </Container>  
    <Container>  
      <Name>images</Name>  
      <Properties>  
        <Last-Modified>Wed, 26 Oct 2016 20:39:39 GMT</Last-Modified>  
        <Etag>0x8CACB9BD7C1EEEC</Etag>  
      </Properties>  
    </Container>  
    <Container>  
      <Name>textfiles</Name>  
      <Properties>  
        <Last-Modified>Wed, 26 Oct 2016 20:39:39 GMT</Last-Modified>  
        <Etag>0x8CACB9BD7BACAC3</Etag>  
      </Properties>  
    </Container>  
  </Containers>  
  <NextMarker>video</NextMarker>  
</EnumerationResults>

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

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

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

Авторизация запросов к службе хранилища Azure
Коды состояний и ошибок
Коды ошибок хранилища BLOB-объектов
Перечисление ресурсов BLOB-объектов
Использование эмулятора службы хранилища Azure для разработки и тестирования
Установка времени ожидания для операций с хранилищем BLOB-объектов