List Blobs (Отображение списка BLOB-объектов)

Статья
03/16/2023

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

Запрос

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

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

URI эмулированной службы хранилища

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

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

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

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

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

Параметр	Описание
`prefix`	Необязательный элемент. Фильтрует результаты, чтобы возвращать только большие двоичные объекты с именами, начинающимися с указанного префикса. В учетных записях с иерархическим пространством имен возникает ошибка в случаях, когда имя файла отображается в середине пути префикса. Например, можно попытаться найти большие двоичные объекты с именами `readmefile.txt` с помощью пути `folder1/folder2/readme/readmefile.txt`префикса . Если какая-либо вложенная папка содержит файл с именем `readme`, появится ошибка.
`delimiter`	Необязательный элемент. Если запрос включает этот параметр, операция возвращает `BlobPrefix` элемент в тексте ответа. Этот элемент выступает в качестве заполнителя для всех BLOB-объектов с именами, начинающимися с одной и той же подстроки, вплоть до появления символа разделителя. Разделитель может быть одним символом или строкой.
`marker`	Необязательный элемент. Строковое значение, которое определяет часть списка для возвращения со следующей операцией списка. Операция возвращает значение маркера в тексте ответа, если возвращаемый список неполон. Затем можно использовать значение маркера в последующем вызове, чтобы запросить следующий набор элементов списка. Значение маркера непрозрачно для клиента.
`maxresults`	Необязательный элемент. Указывает максимальное количество больших двоичных объектов для возвращения, включая все элементы `BlobPrefix`. Если в запросе не указано `maxresults`значение или указано значение больше 5000, сервер вернет до 5000 элементов. Если необходимо вернуть дополнительные результаты, служба возвращает маркер продолжения в элементе `NextMarker` response. В некоторых случаях служба может возвращать меньше результатов, чем указано в `maxresults`, а также возвращать маркер продолжения. Установка для `maxresults` значения меньше нуля или равного нулю приводит к возвращению кода ошибки 400 (неправильный запрос).
`include={snapshots,metadata,uncommittedblobs,copy,deleted,tags,versions,` `deletedwithversions,immutabilitypolicy,legalhold,permissions}`	Необязательный элемент. Задает один или несколько наборов данных для включения в ответ. - `snapshots`: указывает, что моментальные снимки должны быть включены в перечисление . Моментальные снимки перечисляются в ответе от самых старых к самым новым. - `metadata`: указывает, что метаданные большого двоичного объекта возвращаются в ответе. - `uncommittedblobs`: указывает, что большие двоичные объекты, для которых были отправлены блоки, но которые не были зафиксированы с помощью put block list, включаются в ответ. - `copy`: версия 12.02.2012 и более поздняя. Задает включение в ответ метаданных для любой текущей или предыдущей операции `Copy Blob`. -`deleted`: версия 29.07.2017 и более поздние. Указывает, что обратимо удаленные BLOB-объекты должны быть включены в ответ. -`tags`: версия 12.12.2019 и более поздние. Указывает, что определенные пользователем теги индекса BLOB-объектов должны быть включены в ответ. -`versions`: версия 12.12.2019 и более поздние. Указывает, что версии больших двоичных объектов должны быть включены в перечисление . -`deletedwithversions`: версия 2020-10-02 и более поздние. Указывает, что удаленные BLOB-объекты с любыми версиями (активными или удаленными) должны быть включены в ответ. Элементы, которые вы окончательно удалили, отображаются в ответе до тех пор, пока они не будут обработаны сборкой мусора. Используйте тег `\<HasVersionsOnly\>`и значение `true`. -`immutabilitypolicy`: версия 12.06.2020 и более поздняя. Указывает, что перечисление должно включать политику неизменяемости до даты и режим политики неизменяемости больших двоичных объектов. -`legalhold`: версия 12.06.2020 и более поздняя. Указывает, что перечисление должно включать удержание больших двоичных объектов по юридическим причинам. -`permissions`: версия 12.06.2020 и более поздняя. Поддерживается только для учетных записей с включенным иерархическим пространством имен. Если запрос включает этот параметр, в перечисление будут включены владелец, группа, разрешения и список управления доступом для перечисленных BLOB-объектов или каталогов. Для указания более одного из этих параметров в URI необходимо отделять каждый параметр в URL-представлении запятой (" %82").
`showonly={deleted,files,directories}`	Необязательный элемент. Указывает один из этих наборов данных, возвращаемых в ответе: -`deleted`:Дополнительные. Версия 2020-08-04 и более поздняя. Только для учетных записей, включенных с иерархическим пространством имен. Если запрос включает этот параметр, список содержит только обратимо удаленные BLOB-объекты. Обратите внимание, что резервный вариант авторизации POSIX ACL не поддерживается для перечисления обратимо удаленных BLOB-объектов. Если `include=deleted` также указан параметр , запрос завершается ошибкой с неправильным запросом (400). -`files`:Дополнительные. Версия 2020-12-06 и более поздние версии. Только для учетных записей, включенных с иерархическим пространством имен. Если запрос включает этот параметр, список содержит только файлы. -`directories`:Дополнительные. Версия 2020-12-06 и более поздние версии. Только для учетных записей, включенных с иерархическим пространством имен. Если запрос включает этот параметр, список содержит только каталоги.
`timeout`	Необязательный элемент. Параметр `timeout` указывается в секундах. Дополнительные сведения см. в разделе Настройка времени ожидания для операций с хранилищем BLOB-объектов.

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

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

Заголовок запроса	Описание
`Authorization`	Обязательный. Указывает схему авторизации, имя учетной записи и подпись. Дополнительные сведения см. в статье Авторизация запросов к Службе хранилища Azure.
`Date` или `x-ms-date`	Обязательный. Задает время запроса в формате UTC. Дополнительные сведения см. в статье Авторизация запросов к Службе хранилища Azure.
`x-ms-version`	Обязательный параметр для всех авторизованных запросов и необязательный для анонимных запросов. Задает версию операции, используемой для этого запроса. Дополнительные сведения см. в разделе Управление версиями для служб хранилища Azure.
`x-ms-client-request-id`	Необязательный элемент. Предоставляет созданное клиентом непрозрачное значение с ограничением в 1 кибибайт (КиБ), которое записывается в журналы при настройке ведения журнала. Мы настоятельно рекомендуем использовать этот заголовок для сопоставления действий на стороне клиента с запросами, получаемыми сервером. Дополнительные сведения см. в статье Мониторинг хранилища BLOB-объектов Azure.
`x-ms-upn`	Необязательный элемент. Допустимо, только если для учетной записи включено иерархическое пространство имен и `include=permissions` указано в запросе. При `true`значении значения идентификаторов пользователей, возвращаемые в <полях Владелец>, <Группа> и <Список управления> доступом, преобразуются из идентификаторов объектов Microsoft Entra в имена субъектов-пользователей. При `false`значении значения возвращаются в виде идентификаторов объектов Microsoft Entra. Значение по умолчанию — `false`. Обратите внимание, что идентификаторы объектов групп и приложений не переводятся, так как они не имеют уникальных понятных имен.

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

Нет.

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

Пример запроса см. в разделе Перечисление ресурсов BLOB-объектов .

Ответ

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

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

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

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

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

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

Текст ответа

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

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

Моментальные снимки, метаданные больших двоичных объектов и незафиксированные большие двоичные объекты включаются в ответ, только если они указаны параметром include в URI запроса.

В версии 2009-09-19 и более поздних свойства большого двоичного объекта инкапсулируются в элементе Properties .

Начиная с версии 2009-09-19, List Blobs возвращает в тексте ответа следующие переименованные элементы.

Last-Modified (ранее LastModified)
Content-Length (ранее Size)
Content-Type (ранее ContentType)
Content-Encoding (ранее ContentEncoding)
Content-Language (ранее ContentLanguage)

Элемент Content-MD5 отображается для больших двоичных объектов, созданных в версии 2009-09-19 и более поздних. В версии 2012-02-12 и более поздних хранилище BLOB-объектов вычисляет Content-MD5 значение при отправке большого двоичного объекта с помощью put BLOB-объекта. Хранилище BLOB-объектов не вычисляет этот параметр при создании БОЛЬШОго двоичного объекта с помощью функции Поместить список блокировок. Значение можно явно задать при создании большого Content-MD5 двоичного объекта или путем вызова операций Поместить список блокировок или Задать свойства BLOB-объекта .

Для версий от 2009-09-19 и более поздних версий, но до версии 2015-02-21, нельзя вызывать для List Blobs контейнера, включающего добавочные BLOB-объекты. Служба возвращает код состояния 409 (конфликт), если результат перечисления содержит добавочный BLOB-объект.

LeaseState и LeaseDuration отображаются только в версии 2012-02-12 и более поздних версиях.

CopyId, CopyStatus, CopySource, CopyProgress, CopyCompletionTime и CopyStatusDescription появляются только в версии 2012-02-12 и более новой, если эта операция включает параметр include={copy}. Эти элементы не отображаются, если этот BLOB-объект никогда не был назначением Copy Blob в операции. Элементы не отображаются, если большой двоичный объект был изменен после завершения Copy Blob операции с помощью Set Blob Properties, Put Blobили Put Block List. Эти элементы также не отображаются в большом двоичном объекте, созданном при копировании BLOB-объекта до версии 2012-02-12.

В версии 2013-08-15 и более поздних версиях элемент содержит атрибут, EnumerationResults указывающий конечную ServiceEndpoint точку BLOB-объекта. Этот элемент также содержит ContainerName поле, указывающее имя контейнера. В предыдущих версиях эти два атрибута были объединены в ContainerName поле . Кроме того, в версии 2013-08-15 и более поздних Url был удален элемент Blob в .

Для версии 2015-02-21 и более поздних List Blobs возвращает BLOB-объекты всех типов (блочные, страничные и добавочные BLOB-объекты).

Для версии 2015-12-11 и более поздних возвращает List BlobsServerEncrypted элемент . Этот элемент имеет значение , true если метаданные большого двоичного объекта и приложения полностью зашифрованы, и false в противном случае.

Для версии 2016-05-31 и более поздних List Blobs возвращает IncrementalCopy элемент для blob-объектов и моментальных снимков добавочного копирования со значением true.

Для версии 2017-04-17 и более поздних возвращает AccessTier элемент , List Blobs если уровень доступа был явно задан. Список разрешенных уровней страничных BLOB-объектов категории "Премиум" см. в статье Высокопроизводительное хранилище класса Premium и управляемые диски для виртуальных машин. Для учетных записей хранилища BLOB-объектов или учетных записей общего назначения версии 2 допустимые значения: Hot, Coolи Archive. Если большой двоичный объект находится в состоянии ожидания восстановления, возвращается ArchiveStatus элемент с одним из допустимых значений (rehydrate-pending-to-hot, rehydrate-pending-to-cool, или rehydrate-pending-to-cold). Подробные сведения о разных уровнях блочных BLOB-объектов см. в разделе Горячий, холодный и архивный уровни хранилища.

Для версии 2017-04-17 и более поздних List Blobs возвращает AccessTierInferred элемент в учетных записях Хранилища BLOB-объектов или общего назначения версии 2. Если для блочного BLOB-объекта не задан уровень доступа, сведения об уровне выводятся из свойств учетной записи хранения, и для этого значения устанавливается значение true. Этот заголовок присутствует только в том случае, если уровень выводится из свойства учетной записи.

Для версии 2017-04-17 и более поздних List Blobs возвращает AccessTierChangeTime элемент в учетных записях Хранилища BLOB-объектов или общего назначения версии 2. Возвращается только в том случае, если был задан уровень в блочных BLOB-объектах. Дополнительные сведения см. в разделе Представление значений даты и времени в заголовках.

Для версии 2017-07-29 и более поздних , DeletedTimeи RemainingRetentionDays отображаются, Deletedесли эта операция включает include={deleted} параметр . Эти элементы не отображаются, если большой двоичный объект не был удален. Эти элементы отображаются для больших двоичных объектов или моментальных снимков, которые удаляются с DELETE помощью операции, когда включена функция обратимого удаления. Элементу Deleted присваивается значение true для blob-объектов и моментальных снимков, которые удаляются обратимо. Deleted-Time соответствует времени удаления большого двоичного объекта. RemainingRetentionDays указывает количество дней, по истечении которых обратимо удаленный BLOB-объект удаляется без возможности восстановления.

Для версии 2017-11-09 и более поздних Creation-Time возвращает время создания большого двоичного объекта.

Для версии 2019-02-02 и более поздних возвращает CustomerProvidedKeySha256 элемент , List Blobs если большой двоичный объект зашифрован с помощью ключа, предоставленного клиентом. В качестве значения будет задан хэш SHA-256 ключа, используемого для шифрования большого двоичного объекта. Кроме того, если операция включает include={metadata} параметр и в большом двоичном объекте присутствуют метаданные приложения, зашифрованные с помощью ключа, предоставленного Metadata клиентом Encrypted="true" , элемент будет иметь атрибут . Этот атрибут указывает, что большой двоичный объект содержит метаданные, которые не могут быть расшифрованы в List Blobs рамках операции. Чтобы получить доступ к метаданным для этих BLOB-объектов, вызовите метод Get Blob Properties или Get Blob Metadata with the customer-provided key .

Для версии 2019-02-02 и более поздних возвращает EncryptionScope элемент , List Blobs если большой двоичный объект зашифрован с помощью области шифрования. В качестве значения будет задано имя области шифрования, используемой для шифрования большого двоичного объекта. Если операция включает include={metadata} параметр , метаданные приложения в большом двоичном объекте прозрачно расшифровываются и доступны в элементе Metadata .

Для версии 2019-12-12 и более поздних List Blobs возвращает RehydratePriority элемент в учетных записях хранилища BLOB-объектов или общего назначения версии 2, если объект находится в rehydrate pending состоянии . Допустимые значения: High и Standard.

Для версии 2019-12-12 и более поздних List Blobs возвращает VersionId элемент для больших двоичных объектов и созданных версий BLOB-объектов, если управление версиями в учетной записи включено.

Для версии 2019-12-12 и более поздних List Blobs возвращает IsCurrentVersion элемент для текущей версии большого двоичного объекта. Присвоено значение true. Этот элемент позволяет отличать текущую версию от автоматически создаваемых версий только для чтения.

Для версии 2019-12-12 и более поздних List Blobs возвращает TagCount элемент для больших двоичных объектов с любыми тегами. Элемент Tags отображается только в том случае, если эта операция включает include={tags} параметр . Эти элементы не отображаются, если в большом двоичном объекте нет тегов.

Для версии 2019-12-12 и более поздних List Blobs возвращает Sealed элемент для добавочных BLOB-объектов. Элемент Sealed отображается только в том случае, если добавочный BLOB-объект запечатан. Эти элементы не отображаются, если добавочный BLOB-объект не запечатан.

Для версии 2020-02-10 и более поздних List Blobs возвращает LastAccessTime элемент . Элемент показывает время последнего доступа к данным BLOB-объекта в соответствии с политикой отслеживания времени последнего доступа учетной записи хранения. Элемент не возвращается, если учетная запись хранения не имеет этой политики или политика отключена. Сведения о настройке политики отслеживания времени последнего доступа учетной записи см. в разделе API службы BLOB-объектов. Элемент LastAccessTime не отслеживает последний раз, когда осуществляется доступ к метаданным BLOB-объекта.

Для версии 2020-06-12 и более поздних List Blobs возвращает ImmutabilityPolicyUntilDate элементы и ImmutabilityPolicyMode , если эта операция включает include={immutabilitypolicy} параметр .

Для версии 2020-06-12 и более поздних List Blobs возвращает LegalHold элемент , если эта операция включает include={legalhold} параметр .

Для версии 2020-06-12 и более поздних для учетных записей с включенным List Blobs иерархическим пространством имен возвращает Ownerэлементы , Group, Permissionsи Acl . Запрос должен содержать include={permissions} параметр . Обратите внимание, что Acl элемент представляет собой объединенный список списков управления доступом и управления доступом по умолчанию, заданных для файла или каталога.

Для версии 2020-06-12 и более поздних для учетных записей с включенным List Blobs иерархическим пространством имен с разделителем возвращает Properties элемент в элементе BlobPrefix . Это соответствует свойствам каталога.

Для версии 2020-08-04 и более поздних версий для учетных записей с включенным List Blobs иерархическим пространством имен возвращает DeletionId элемент для удаленных BLOB-объектов. DeletionId — 64-разрядный идентификатор без знака. Элемент однозначно идентифицирует обратимо удаленный путь, чтобы отличать его от других удаленных BLOB-объектов с таким же путем.

Для версии 2020-10-02 и более поздних версий для учетных записей с включенным List Blobs иерархическим пространством имен возвращает ResourceType элемент свойства для пути. Это может быть либо file, либо directory.

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

Для версии 2021-06-08 и более поздних версий для учетных записей с включенным List Blobs иерархическим пространством имен возвращает Placeholder элемент properties. Он возвращает этот элемент в элементе BlobPrefix для каталогов-заполнителей при перечислении удаленных BLOB-объектов с разделителем. Эти каталоги-заполнители существуют для упрощения навигации по обратимо удаленным BLOB-объектам.

Для версии 2021-06-08 и более поздних версий для учетных записей с включенным List Blobs иерархическим пространством имен возвращает EncryptionContext элемент . Если задано значение свойства контекста шифрования, возвращается заданное значение.

Для версии 2020-02-10 и более поздних для учетных записей с включенным List Blobs иерархическим пространством имен возвращает Expiry-Time элемент для удаленных BLOB-объектов. Expiry-Time — это время истечения срока действия файла, и возвращается для файла, если срок действия совпадает.

<?xml version="1.0" encoding="utf-8"?>  
<EnumerationResults ServiceEndpoint="http://myaccount.blob.core.windows.net/"  ContainerName="mycontainer">  
  <Prefix>string-value</Prefix>  
  <Marker>string-value</Marker>  
  <MaxResults>int-value</MaxResults>  
  <Delimiter>string-value</Delimiter>  
  <Blobs>  
    <Blob>  
      <Name>blob-name</name>  
      <Snapshot>date-time-value</Snapshot>  
      <VersionId>date-time-vlue</VersionId>
      <IsCurrentVersion>true</IsCurrentVersion>
      <Deleted>true</Deleted>
      <Properties> 
        <Creation-Time>date-time-value</Creation-Time>
        <Last-Modified>date-time-value</Last-Modified>  
        <Etag>etag</Etag>
        <Owner>owner user id</Owner>
        <Group>owning group id</Group>
        <Permissions>permission string</Permissions>
        <Acl>access control list</Acl>
        <ResourceType>file | directory</ResourceType>
        <Placeholder>true</Placeholder>
        <Content-Length>size-in-bytes</Content-Length>  
        <Content-Type>blob-content-type</Content-Type>  
        <Content-Encoding />  
        <Content-Language />  
        <Content-MD5 />  
        <Cache-Control />  
        <x-ms-blob-sequence-number>sequence-number</x-ms-blob-sequence-number>  
        <BlobType>BlockBlob|PageBlob|AppendBlob</BlobType>  
        <AccessTier>tier</AccessTier>  
        <LeaseStatus>locked|unlocked</LeaseStatus>  
        <LeaseState>available | leased | expired | breaking | broken</LeaseState>  
        <LeaseDuration>infinite | fixed</LeaseDuration>  
        <CopyId>id</CopyId>  
        <CopyStatus>pending | success | aborted | failed </CopyStatus>  
        <CopySource>source url</CopySource>  
        <CopyProgress>bytes copied/bytes total</CopyProgress>  
        <CopyCompletionTime>datetime</CopyCompletionTime>  
        <CopyStatusDescription>error string</CopyStatusDescription>  
        <ServerEncrypted>true</ServerEncrypted> 
        <CustomerProvidedKeySha256>encryption-key-sha256</CustomerProvidedKeySha256>
        <EncryptionContext>encryption-context<EncryptionContext>
        <EncryptionScope>encryption-scope-name</EncryptionScope>
        <IncrementalCopy>true</IncrementalCopy>
        <AccessTierInferred>true</AccessTierInferred>
        <AccessTierChangeTime>datetime</AccessTierChangeTime>
        <DeletedTime>datetime</DeletedTime>
        <RemainingRetentionDays>no-of-days</RemainingRetentionDays>
        <TagCount>number of tags between 1 to 10</TagCount>
        <RehydratePriority>rehydrate priority</RehydratePriority>
        <Expiry-Time>date-time-value</Expiry-Time>
      </Properties>  
      <Metadata>     
        <Name>value</Name>  
      </Metadata>  
      <Tags>
          <TagSet>
              <Tag>
                  <Key>TagName</Key>
                  <Value>TagValue</Value>
              </Tag>
          </TagSet>
      </Tags>
      <OrMetadata />
    </Blob>  
    <BlobPrefix>  
      <Name>blob-prefix</Name>  
    </BlobPrefix>  
  </Blobs>  
  <NextMarker />  
</EnumerationResults>

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

Пример ответа см. в разделе Перечисление ресурсов BLOB-объектов .

Авторизация

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

Служба хранилища 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 Blobs операции, а также встроенная роль Azure RBAC с наименьшими привилегиями, которая включает это действие:

Действие Azure RBAC:Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read
Встроенная роль с наименьшими привилегиями:читатель данных BLOB-объектов хранилища

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

Подписанный URL-адрес (SAS) обеспечивает безопасный делегированный доступ к ресурсам в учетной записи хранения. С помощью SAS вы можете детально контролировать, как клиент может получить доступ к данным. Вы можете указать, к какому ресурсу может обращаться клиент, какие разрешения у него есть для этих ресурсов, а также срок действия SAS.

Операция List Blobs поддерживает три типа подписанных URL-адресов: SAS делегирования пользователей, SAS службы и SAS учетной записи.

Для обеспечения безопасности рекомендуется использовать Microsoft Entra учетные данные, а не ключ учетной записи хранения, который может быть проще скомпрометирован. Если для разработки приложения требуются подписанные URL-адреса, по возможности используйте учетные данные Microsoft Entra, чтобы создать SAS для делегирования пользователей.

Если доступ к общему ключу запрещен для учетной записи хранения, маркер SAS службы или маркер SAS учетной записи не будет разрешен при запросе к Хранилищу BLOB-объектов. Дополнительные сведения см. в статье Общие сведения о том, как запрет общего ключа влияет на маркеры SAS.

SAS для делегирования пользователей

SAS для делегирования пользователей защищен с помощью учетных данных Microsoft Entra, а также разрешений, указанных для SAS.

List Blobs Для вызова операции с помощью маркера SAS, делегированного ресурсу контейнера, требуется разрешение List (l) как часть маркера SAS делегирования пользователя.

Дополнительные сведения о SAS для делегирования пользователей см. в статье Создание SAS для делегирования пользователей.

SAS для службы

SAS для службы защищен с помощью ключа учетной записи хранения. SAS службы делегирует доступ к ресурсу в одной службе хранилища Azure, например в хранилище BLOB-объектов.

List Blobs Для вызова операции с использованием маркера SAS, делегированного ресурсу контейнера, требуется разрешение List (l) в составе маркера SAS службы.

Дополнительные сведения о SAS службы см. в статье Создание SAS службы.

SAS для учетной записи

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

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

Операция	Подписанная служба	Подписанный тип ресурса	Подписанное разрешение
List Blobs (Отображение списка BLOB-объектов)	Большой двоичный объект (b)	Контейнер (c)	List (l)

Дополнительные сведения о SAS учетной записи см. в статье Создание SAS учетной записи.

Операция List Blobs поддерживает авторизацию с помощью общего ключа. Авторизация с помощью ключей учетной записи не рекомендуется в большинстве сценариев, так как она менее безопасна.

Корпорация Майкрософт рекомендует по возможности запретить авторизацию с общим ключом для учетной записи хранения. Дополнительные сведения см. в статье Предотвращение авторизации с помощью общего ключа.

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

Элемент x-ms-blob-sequence-number возвращается только для страничных BLOB-объектов.

Элемент OrMetadata возвращается только для блочных BLOB-объектов.

Для страничных BLOB-объектов значение, возвращаемое в элементе Content-Length, соответствует значению заголовка x-ms-blob-content-length BLOB-объекта.

Элемент Content-MD5 отображается в тексте отклика, только если он был задан в большом двоичном объекте с помощью версии 2009-09-19 или более поздней. Свойство можно задать Content-MD5 при создании большого двоичного объекта или путем вызова метода Set BLOB-объекта Properties. В версии 2012-02-12 и более поздних Put Blob задает значение MD5 блочного BLOB-объекта, даже если Put Blob запрос не содержит заголовка MD5.

Метаданные в ответе

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

Обратите внимание, что метаданные, запрашиваемые с этим параметром, должны храниться в соответствии с ограничениями именования, установленными в версии 2009-09-19 Хранилища BLOB-объектов. Начиная с этой версии все имена метаданных должны соответствовать соглашениям об именовании для идентификаторов C#.

Если пара "имя-значение" метаданных нарушает эти ограничения именования, текст ответа указывает на проблемное имя в элементе 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>  
…

Теги в ответе

Элемент Tags присутствует только в include=tags том случае, если параметр был указан в URI и если в большом двоичном объекте есть теги. В элементе TagSet возвращается до 10 Tag элементов, каждый из которых содержит key и value определенных пользователем тегов индекса BLOB-объектов. Порядок тегов не гарантируется в ответе.

Элементы Tags и TagCount не возвращаются, если в большом двоичном объекте нет тегов.

Служба хранилища поддерживает строгое согласованность между большим двоичным объектом и его тегами, но вторичный индекс в конечном итоге является согласованным. Теги могут быть видны в ответе, List Blobs прежде чем они станут видимыми для Find Blobs by Tags операций.

Моментальные снимки в ответе

Моментальные снимки перечисляются в ответе, только если в URI был указан параметр include=snapshots. Моментальные снимки, перечисленные в ответе LeaseStatus , не включают элемент , так как моментальные снимки не могут иметь активных аренд.

С помощью службы версии 2021-06-08 и более поздних можно вызывать List Blobs с разделителем и включать моментальные снимки в перечисление. Для версий служб, предшествующих 2021-06-08, запрос, который включает оба варианта, возвращает ошибку InvalidQueryParameter (код состояния HTTP 400 — недопустимый запрос).

Незафиксированные BLOB-объекты в ответе

Незафиксированные большие двоичные объекты перечисляются в ответе, только если в URI был указан параметр include=uncommittedblobs. Незафиксированные BLOB-объекты, перечисленные в ответе, не содержат ни одного из следующих элементов:

Last-Modified
Etag
Content-Type
Content-Encoding
Content-Language
Content-MD5
Cache-Control
Metadata

Удаленные BLOB-объекты в ответе

Удаленные BLOB-объекты отображаются в ответе только в том случае, include=deleted если параметр был указан в URI. Удаленные BLOB-объекты, перечисленные в ответе, не включают элементы Аренды , так как удаленные BLOB-объекты не могут иметь активных аренд.

Удаленные моментальные снимки включаются в ответ списка, если include=deleted,snapshot был указан в URI.

Метаданные репликации объектов в ответе

Элемент OrMetadata присутствует при оценке политики репликации объектов в большом двоичном объекте, а List Blobs вызов был выполнен с помощью версии 2019-12-12 или более поздней. В элементе OrMetadata значение для каждой пары "имя-значение" приводится с элементом, соответствующим имени в паре. Формат имени — or-{policy-id}_{rule-id}, где {policy-id} — guid, представляющий идентификатор политики репликации объектов в учетной записи хранения. {rule-id} — это GUID, представляющий идентификатор правила в контейнере хранилища. Допустимые значения: complete или failed.

  
…  
<OrMetadata>  
  <or-e524bba7-4323-4b93-91f8-d09d5d0b7057_d86c51de-ef02-4264-bdcf-dcd389a6c7ac>complete</or-e524bba7-4323-4b93-91f8-d09d5d0b7057_d86c51de-ef02-4264-bdcf-dcd389a6c7ac>  
  <or-2b302b5d-fcd5-44d6-a5ed-455bf27e17ea_4a398ff5-2a89-4090-879b-10248f23428e>failed</or-2b302b5d-fcd5-44d6-a5ed-455bf27e17ea_4a398ff5-2a89-4090-879b-10248f23428e>  
</OrMetadata>  
…

Политика неизменяемости в ответе

Элементы ImmutabilityPolicyUntilDate и ImmutabilityPolicyMode присутствуют только в том случае, include=immutabilitypolicy если параметр был указан в URI.

<Properties> 
   <ImmutabilityPolicyUntilDate>date-time-value</ImmutabilityPolicyUntilDate>   
   <ImmutabilityPolicyMode>unlocked | locked </ImmutabilityPolicyMode>  
</Properties>

Удержание по юридическим причинам в ответе

Элемент LegalHold присутствует, только если параметр include=legalhold был указан в URI.

<Properties> 
  <LegalHold>true | false </LegalHold>  
</Properties>

Возврат результирующих наборов с помощью значения маркера

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

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

Использование разделителя для обхода пространства имен BLOB-объекта

Параметр delimiter позволяет вызывающему объекту обойти пространство имен BLOB-объектов с помощью настроенного пользователем разделителя. Таким образом, можно переходить по виртуальной иерархии BLOB-объектов, как если бы это была файловая система. Разделитель может быть одним символом или строкой.

Когда запрос включает этот параметр, операция возвращает элемент BlobPrefix. Элемент BlobPrefix возвращается вместо всех BLOB-объектов с именами, начинающимися с одной подстроки, вплоть до появления символа разделителя. Значение BlobPrefix элемента — substring+delimiter, где подстрока — это общая подстрока, начинающаяся с одного или нескольких имен BLOB-объектов, а разделитель — это значение delimiter параметра.

Можно использовать значение BlobPrefix , чтобы выполнить последующий вызов для вывода списка больших двоичных объектов, которые начинаются с этого префикса. Для этого необходимо указать значение BlobPrefix параметра в prefix URI запроса.

Обратите внимание, что каждый возвращенный элемент BlobPrefix засчитывается в максимальный результат, как и каждый элемент Blob.

Большие двоичные объекты перечисляются в тексте ответа в алфавитном порядке, где буквы верхнего регистра идут первыми.

Ошибки копирования в описании состояния копирования

CopyStatusDescription содержит сведения об ошибке Copy Blob.

Если попытка копирования завершается неудачно, устанавливается значение pending , CopyStatus если хранилище BLOB-объектов по-прежнему повторяет операцию. В тексте CopyStatusDescription описывается сбой, который мог возникнуть во время последней попытки копирования.
Если аргумент CopyStatus имеет значение failed, текст CopyStatusDescription содержит описание ошибки, вызвавшей неудачу операции копирования.

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

Компонент	Описание
Код состояния HTTP	Стандартное трехзначное целое число, указывающее сбой.
Код ошибки	Ключевое слово, описывающее ошибку. Он предоставляется Azure в элементе <ErrorCode> . Если элемент ErrorCode> не <отображается, служба возвращает ключевое слово, содержащий стандартный текст ошибки, связанный с трехзначным кодом состояния HTTP в спецификации HTTP. Дополнительные сведения см. в статье Общие коды ошибок REST API.
Сведения	Подробное описание сбоя в кавычках.

В следующей таблице описаны значения CopyStatus и CopyStatusDescription распространенных ошибок.

Важно!

Приведенный здесь текст описания может изменяться без предупреждения, даже без изменения версии. Не полагайтесь на сопоставление этого точного текста.

Сценарий	Значение состояния копирования	Значение описания состояния копирования
Операция копирования успешно завершена.	Успешное завершение	пустых
Пользователь прервал операцию копирования до ее завершения.	aborted	пустых
Произошел сбой при чтении из исходного BLOB-объекта во время операции копирования. Операция будет запущена повторно.	ожидание	502 (неверный шлюз). «Во время чтения данных из источника возникла ошибка, предполагающая повтор операции. Попытка будет повторена. Время сбоя: <время>"
Ошибка при записи в целевой BLOB-объект операции копирования. Операция будет запущена повторно.	ожидание	500 (внутренняя ошибка сервера). «Обнаружена ошибка, предполагающая повтор операции. Попытка будет повторена. Время сбоя: <время>"
Во время считывания данных из исходного большого двоичного объекта возникла неустранимая ошибка операции копирования.	сбой	404 ResourceNotFound "Сбой копирования при чтении источника". Когда служба сообщает об этой базовой ошибке, она возвращается `ResourceNotFound` в элементе <ErrorCode> . Если в ответе не <отображается элемент ErrorCode> , отображается стандартное строковое представление состояния HTTP, например `NotFound`, .
Время ожидания, ограничивающее все операции копирования, истекло. (В настоящее время период ожидания составляет две недели.)	сбой	500 (операция отменена). «Копирование превысило максимально допустимое время».
Во время чтения из источника операция копирования слишком часто завершалась ошибкой и не удовлетворила допустимому количеству попыток. (Это время ожидания предотвращает повторную попытку очень плохого источника в течение двух недель до сбоя).	сбой	500 (операция отменена). «Копирование завершилось ошибкой во время чтения данных из источника».

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

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

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

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

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

Коды состояний и ошибок
Коды ошибок хранилища BLOB-объектов