Get Page Ranges (Получение диапазона страницы)

Статья
04/14/2023

Операция Получить диапазоны страниц возвращает список допустимых диапазонов страниц для страничного BLOB-объекта или snapshot страничного BLOB-объекта.

Запрос

Запрос получить диапазоны страниц можно создать следующим образом. Рекомендуется использовать ПРОТОКОЛ HTTPS. Замените myaccount именем своей учетной записи хранения:

URI запроса метода GET	параметр "Версия HTTP"
`https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=pagelist` `https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=pagelist&snapshot=<DateTime>` `https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=pagelist&snapshot=<DateTime>&prevsnapshot=<DateTime>`	HTTP/1.1

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

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

URI запроса метода GET	параметр "Версия HTTP"
`http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=pagelist`	HTTP/1.1

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

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

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

Параметр	Описание
`marker`	Необязательно, версия 2020-10-02 и более поздние. Определяет часть диапазонов, возвращаемую при следующей операции GetPageRanges. Операция возвращает значение маркера в теле ответа, если возвращенные диапазоны были неполными. Затем значение маркера можно использовать в последующем вызове для запроса следующего набора диапазонов. Значение маркера непрозрачно для клиента.
`maxresults`	Необязательно, версия 2020-10-02 и более поздние. Указывает максимальное количество возвращаемых диапазонов страниц. Если запрос задает значение, превышающее 10 000, сервер возвращает до 10 000 элементов. Если необходимо вернуть дополнительные результаты, служба возвращает маркер продолжения в элементе ответа NextMarker. Если `maxresults` задать значение меньше или равно нулю, вы получите код ответа об ошибке 400 (недопустимый запрос).
`snapshot`	Необязательный элемент. Непрозрачное значение DateTime, указывающее snapshot большого двоичного объекта для получения сведений. Дополнительные сведения о работе с моментальными снимками BLOB-объектов см. в разделе Создание snapshot BLOB-объекта.
`timeout`	Необязательный элемент. Выражается в секундах. Дополнительные сведения см. в разделе Установка времени ожидания для операций с хранилищем BLOB-объектов.
`prevsnapshot`	Необязательно, версия 2015-07-08 и более поздние. Значение DateTime, указывающее, что ответ будет содержать только страницы, которые были изменены между целевым BLOB-объектом и предыдущим snapshot. К измененным страницам относятся обновленные и очищенные страницы. Целевой BLOB-объект может быть snapshot, если snapshot, указанный параметром `prevsnapshot` , является более старым из двух. Примечание. Добавочные моментальные снимки в настоящее время поддерживаются только для BLOB-объектов, созданных 1 января 2016 года или позже.

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

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

Заголовок запроса	Описание
`Authorization`	Обязательный. Указывает схему авторизации, имя учетной записи и подпись. Дополнительные сведения см. в статье Авторизация запросов к Службе хранилища Azure.
`Date` или `x-ms-date`	Обязательный. Задает время запроса в формате UTC. Дополнительные сведения см. в статье Авторизация запросов к Службе хранилища Azure.
`x-ms-version`	Обязательный для всех авторизованных запросов, необязательный для анонимных запросов. Задает версию операции, используемой для этого запроса. Дополнительные сведения см. в разделе Управление версиями для служб хранилища Azure.
`Range`	Необязательный элемент. Указывает диапазон байтов, по которому следует перечислять диапазоны, включительно. Если `Range` параметр опущен, возвращаются все диапазоны для большого двоичного объекта.
`x-ms-range`	Необязательный элемент. Указывает диапазон байтов, по которому следует перечислять диапазоны, включительно. Если заданы оба параметра, `Range` и `x-ms-range`, то служба использует значение `x-ms-range`. Дополнительные сведения см. в разделе Указание заголовка диапазона для операций с хранилищем BLOB-объектов .
`x-ms-lease-id:<ID>`	Необязательный элемент. Если указан этот заголовок, операция выполняется только в том случае, если выполняются оба следующих условия: — Аренда BLOB-объекта в настоящее время активна. — идентификатор аренды, указанный в запросе, соответствует идентификатору аренды большого двоичного объекта. Если указан этот заголовок и любое из условий не выполнено, запрос завершается ошибкой и операция завершается с кодом состояния 412 (сбой предварительного условия).
`x-ms-previous-snapshot-url`	Необязательно, версия 2019-07-07 и более поздние. Указывает`previous-snapshot-url`, что ответ будет содержать только страницы, которые были изменены между целевым blob-объектом и snapshot, расположенными по указанному URI. К измененным страницам относятся обновленные и очищенные страницы. Целевой BLOB-объект может быть snapshot, если snapshot, указанный в этом заголовке, является более старым из двух. Примечание. Добавочные моментальные снимки в настоящее время поддерживаются только для больших двоичных объектов, созданных 1 января 2016 г. или позже, и этот заголовок следует использовать только в сценариях с управляемыми дисками. В противном случае используйте `prevsnapshot` параметр .
`x-ms-client-request-id`	Необязательный элемент. Предоставляет созданное клиентом непрозрачное значение с ограничением в 1 кибибайт (КиБ), которое записывается в журналы аналитики при включении ведения журнала azure Аналитика Службы хранилища. Мы настоятельно рекомендуем использовать этот заголовок при сопоставлении действий на стороне клиента с запросами, полученными сервером. Дополнительные сведения см. в разделах Ведение журнала Аналитика Службы хранилища и Ведение журнала Azure: использование журналов для отслеживания запросов службы хранилища Azure.

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

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

Нет.

Ответ

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

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

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

Дополнительные сведения о кодах состояния см. в разделе Коды состояния и ошибок.

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

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

Синтаксис	Описание
`Last-Modified`	Дата и время последнего изменения BLOB-объекта. Дата в формате согласно RFC 1123. Любая операция, которая изменяет большой двоичный объект, в том числе обновление метаданных или свойств большого двоичного объекта, меняет время последнего изменения этого объекта.
`ETag`	Содержит значение, которое клиент может использовать для условного выполнения операции. Если версия запроса — 2011-08-18 или более поздняя, значение ETag заключается в кавычки.
`x-ms-blob-content-length`	Размер большого двоичного объекта в байтах.
`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 version="1.0" encoding="utf-8"?>  
<PageList>  
   <PageRange>  
      <Start>Start Byte</Start>  
      <End>End Byte</End>  
   </PageRange>  
   <PageRange>  
      <Start>Start Byte</Start>  
      <End>End Byte</End>  
   </PageRange>  
</PageList>

Если весь набор страниц большого двоичного объекта был очищен, текст ответа не включает диапазоны страниц.

prevsnapshot Если указан параметр, ответ будет содержать только страницы, которые отличаются между целевым snapshot или BLOB-объектом и предыдущим snapshot. Возвращенные страницы включают обе страницы, которые были обновлены или очищены. Этот текст ответа имеет следующий формат:

<?xml version="1.0" encoding="utf-8"?>  
<PageList>  
   <PageRange>  
      <Start>Start Byte</Start>  
      <End>End Byte</End>  
   </PageRange>  
   <ClearRange>  
      <Start>Start Byte</Start>  
      <End>End Byte</End>  
   </ClearRange>  
   <PageRange>  
      <Start>Start Byte</Start>  
      <End>End Byte</End>  
   </PageRange>  
</PageList>

Если весь набор страниц большого двоичного объекта был очищен, а prevsnapshot параметр не указан, текст ответа не включает диапазоны страниц.

maxresults Если параметр указан, ответ включает только указанное количество диапазонов с маркером продолжения в теге NextMarker . Маркер продолжения пуст, если нет ожидающих диапазонов или содержит непрозрачное значение, которое необходимо отправить в качестве marker параметра в следующем запросе. Этот текст ответа имеет следующий формат:

<?xml version="1.0" encoding="utf-8"?>  
<PageList>  
   <PageRange>  
      <Start>Start Byte</Start>  
      <End>End Byte</End>  
   </PageRange>  
   <ClearRange>  
      <Start>Start Byte</Start>  
      <End>End Byte</End>  
   </ClearRange>  
   <PageRange>  
      <Start>Start Byte</Start>  
      <End>End Byte</End>  
   </PageRange>
   <NextMarker/>
</PageList>

Авторизация

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

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

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

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

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

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

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

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

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

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

Get Page Ranges Для вызова операции с использованием маркера SAS, делегированного контейнеру или ресурсу BLOB-объекта, требуется разрешение на чтение (r) в составе маркера SAS делегирования пользователя.

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

SAS для службы

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

Get Page Ranges Для вызова операции с помощью маркера SAS, делегированного контейнеру или ресурсу BLOB-объекта, требуется разрешение на чтение (r) в составе маркера SAS службы.

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

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

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

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

Операция	Подписанная служба	Подписанный тип ресурса	Подписанное разрешение
Get Page Ranges (Получение диапазона страницы)	Большой двоичный объект (b)	Объект (o)	Чтение (r)

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

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

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

В значительно фрагментированном страничном большом двоичном объекте с большим количеством записей запрос Get Page Ranges может завершиться ошибкой в связи с истечением внутреннего времени ожидания на сервере. Приложения, получающие диапазоны страничного большого двоичного объекта со значительным числом операций записи, должны извлекать за раз подмножество диапазонов страниц.

Начиная с версии 2015-07-08, можно вызывать Get Page Ranges с параметром prevsnapshot , чтобы вернуть страницы, которые отличаются между базовым BLOB-объектом и snapshot, или между двумя моментальными снимками большого двоичного объекта. Используя эти различия страниц, можно сохранить добавочный snapshot страничного BLOB-объекта. Добавочные моментальные снимки — это экономичный способ резервного копирования дисков виртуальных машин, если вы хотите реализовать собственное решение для резервного копирования.

Вызов Get Page Ranges с параметром prevsnapshot возвращает страницы, которые были обновлены или очищены с момента выполнения snapshot, указанного параметром prevsnapshot . Затем можно скопировать страницы, возвращаемые в резервный страничный BLOB-объект в другой учетной записи хранения, с помощью команды Поместить страницу.

Начиная с версии 2019-07-07, заголовок можно использовать x-ms-previous-snapshot-url для указания моментальных снимков в учетных записях управляемых дисков для добавочных моментальных снимков. Если вы не используете управляемые диски, используйте prevsnapshot параметр запроса .

Некоторые операции с большим двоичным объектом приводят Get Page Ranges к сбою при вызове для возврата добавочного snapshot. Get Pages Rangesзавершается ошибкой с кодом 409 (конфликт), если он вызывается для большого двоичного объекта, который был целевым объектом запроса Put BLOB-объект или Copy BLOB-объект после выполнения snapshot, указанного параметром prevsnapshot . Если целевой Get Page Ranges объект операции сам по себе является snapshot, вызов выполняется успешно, если snapshot, указанный параметром , является более старымprevsnapshot, и Put Blob операция или Copy Blob не была вызвана в интервале между двумя моментальными снимками.

Примечание

Добавочные моментальные снимки в настоящее время поддерживаются только для больших двоичных объектов, созданных 1 января 2016 года или позже. Попытки использовать эту функцию в более старом BLOB-объекте приведут к BlobOverwritten ошибке с кодом ошибки HTTP 409 (конфликт).

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

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