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


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

Операция Получить диапазоны страниц возвращает список допустимых диапазонов страниц для страничного 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-объектов см. в разделе Create 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 операцию, как описано ниже.

Важно!

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

Служба хранилища 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 см. в статье Назначение роли Azure для доступа к данным BLOB-объектов.

Комментарии

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

В значительно фрагментированном страничном большом двоичном объекте с большим количеством записей запрос 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-объектов