Перечисление диапазонов

Статья
03/29/2023

Операция List Ranges возвращает список допустимых диапазонов для файла.

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

Включенный протокол общей папки	Доступно
SMB
NFS

Запрос

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

Метод	Универсальный код ресурса (URI) запроса	параметр "Версия HTTP"
GET	`https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist`	HTTP/1.1
GET	`https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?sharesnapshot=<DateTime>&comp=rangelist`	HTTP/1.1
GET	`https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist&snapshot=<DateTime>&prevsharesnapshot=<DateTime>`	HTTP/1.1
GET	`https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist&prevsharesnapshot=<DateTime>`	HTTP/1.1

Замените компоненты пути, показанный в URI запроса, следующим образом:

Компонент path	Описание
`myaccount`	Имя учетной записи хранения.
`myshare`	Имя файлового ресурса.
`mydirectorypath`	Необязательный элемент. Родительский каталог файла.
`myfile`	Имя файла.

Дополнительные сведения об ограничениях именования путей см. в статье Именование общих папок, каталогов, файлов и метаданных и ссылки на нее.

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

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

Параметр	Описание
`sharesnapshot`	Необязательный элемент. Версия 17.04.2017 и более поздняя. Параметр `sharesnapshot` является непрозрачным `DateTime` значением, которое при его наличии указывает общий snapshot для запроса файла.
`timeout`	Необязательный элемент. Параметр `timeout` указывается в секундах. Дополнительные сведения см. в разделе Настройка времени ожидания для операций Файлы Azure.
`prevsharesnapshot`	Необязательный параметр в версии 2020-02-10 и более поздних. Параметр `prevsharesnapshot` является непрозрачным `DateTime` значением, которое при его наличии указывает предыдущий snapshot. Если оба параметра и `sharesnapshot` присутствуют, ответ будет содержать только диапазоны страниц, которые были изменены между двумя моментальными снимками. Если присутствует только `prevsharesnapshot` параметр , ответ будет содержать только диапазоны страниц, которые были изменены между этой snapshot и динамической общей папкой. К измененным страницам относятся обновленные и очищенные страницы.

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

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

Заголовок запроса	Описание
`Authorization`	Обязательный. Указывает схему авторизации, имя учетной записи и подпись. Дополнительные сведения см. в статье Авторизация запросов к Службе хранилища Azure.
`Date` или `x-ms-date`	Обязательный. Задает время запроса в формате UTC. Дополнительные сведения см. в статье Авторизация запросов к Службе хранилища Azure.
`x-ms-version`	Требуется для всех авторизованных запросов. Задает версию операции, используемой для этого запроса. Дополнительные сведения см. в разделе Управление версиями для служб хранилища Azure.
`Range`	Необязательный элемент. Указывает диапазон байтов, по которому следует перечислять диапазоны, включительно. Если параметр пропущен, то возвращаются все диапазоны для файла.
`x-ms-range`	Необязательный элемент. Указывает диапазон байтов, по которому следует перечислять диапазоны, включительно. Если заданы оба заголовка, `Range` и `x-ms-range`, то служба использует значение `x-ms-range`. Дополнительные сведения см. в разделе Указание заголовка диапазона для операций Файлы Azure.
`x-ms-lease-id:<ID>`	Необязательный элемент. Версия 2019-02-02 и более поздние. Если указан заголовок, операция будет выполняться только в том случае, если аренда файла в данный момент активна, а идентификатор аренды, указанный в запросе, соответствует идентификатору файла. В противном случае операция завершается ошибкой с кодом состояния 412 (сбой предварительного условия).
`x-ms-client-request-id`	Необязательный элемент. Предоставляет созданное клиентом непрозрачное значение с ограничением в 1 кибибайт (КиБ), которое записывается в журналы при настройке ведения журнала. Мы настоятельно рекомендуем использовать этот заголовок для сопоставления действий на стороне клиента с запросами, получаемыми сервером. Дополнительные сведения см. в разделе Мониторинг Файлы Azure.
`x-ms-file-request-intent`	Требуется, если `Authorization` заголовок указывает токен OAuth. Допустимое значение — `backup`. Этот заголовок указывает, что `Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/actionMicrosoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action` или должны быть предоставлены, если они включены в политику RBAC, назначенную удостоверению, которое авторизовано с помощью заголовка `Authorization` . Доступно для версии 2022-11-02 и более поздних версий.
`x-ms-allow-trailing-dot: { <Boolean> }`	Необязательный элемент. Версия 2022-11-02 и более поздние. Логическое значение указывает, следует ли обрезать завершающую точку в URL-адресе запроса. Дополнительные сведения см. в разделе Именование общих папок, каталогов, файлов и метаданных и ссылки на нее.

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

Нет.

Ответ

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

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

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

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

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

Заголовок ответа	Описание
`Last-Modified`	Дата и время последнего изменения файла. Любая операция, которая изменяет файл, включая обновление метаданных или свойств файла, изменяет время последнего изменения файла.
`ETag`	Содержит `ETag` значение, представляющее версию файла в кавычках.
`x-ms-content-length`	Размер файла в байтах. При `prevsharesnapshot` наличии значение описывает размер файла в `sharesnapshot` (если `sharesnapshot` параметр запроса присутствует). В противном случае он описывает размер динамического файла.
`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"?>  
<Ranges>  
  <Range>  
    <Start>Start Byte</Start>  
    <End>End Byte</End>  
  </Range>  
  <Range>  
    <Start>Start Byte</Start>  
    <End>End Byte</End>  
  </Range>  
</Ranges>

Если весь набор диапазонов файла был очищен, текст ответа не будет включать диапазоны.

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

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

Если весь набор страниц файла был очищен, а prevsharesnapshot параметр не указан, текст ответа не будет включать диапазоны.

Авторизация

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

Смещения начального и конечного байтов для каждого из диапазонов рассматриваются, как включающие. См. примеры операций обновления диапазона и операций очистки диапазона для параметра Put Range. В этих примерах показано, какие диапазоны возвращаются при записи или очистке 512-неровного диапазона байтов из файла.

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

Начиная с версии 2020-02-10, можно вызывать List Ranges с параметром prevsharesnapshot . При этом возвращаются диапазоны, которые различаются между динамическим файлом и snapshot или между двумя моментальными снимками файла в моментальных снимках. Используя эти различия в диапазоне, можно получить добавочный snapshot файла. Добавочные моментальные снимки — это экономичный способ резервного копирования файлов, если вы хотите реализовать собственное решение резервного копирования.

Некоторые операции с файлом приводят List Ranges к сбою при вызове для получения добавочного snapshot. Служба возвращает:

404 (не найдено), если вы вызываете файл, который не существует в одном из моментальных снимков (или динамический, если sharesnapshot не указан).
409 (конфликт) при вызове для файла, который был целевым объектом перезаписи copy после snapshot, заданного параметром prevsharesnapshot.
409 (конфликт), если вы вызываете для файла, который был удален и создан повторно с тем же именем и расположением, после snapshot, указанного параметром prevsharesnapshot .

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

Операции с файлами