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

Диапазоны списков

  • Статья

Операция List Ranges возвращает список допустимых диапазонов для файла. Эта операция поддерживается в версии 2025-05-05 и более поздних версий для общих папок с включенным протоколом NFS.

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

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

Просьба

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

Метод URI запроса ВЕРСИЯ HTTP
ПОЛУЧИТЬ https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist HTTP/1.1
ПОЛУЧИТЬ https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?sharesnapshot=<DateTime>&comp=rangelist HTTP/1.1
ПОЛУЧИТЬ https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist&snapshot=<DateTime>&prevsharesnapshot=<DateTime> HTTP/1.1
ПОЛУЧИТЬ 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 Необязательный. Версия 2017-04-17 и более поздних версий. Параметр sharesnapshot является непрозрачным DateTime значением, которое при наличии указывает моментальный снимок общего ресурса для запроса к файлу.
timeout Необязательный. Параметр timeout выражается в секундах. Дополнительные сведения см. в разделе Настройка времени ожидания операций с файлами Azure.
prevsharesnapshot Необязательно в версии 2020-02-10 и более поздних версий. Параметр prevsharesnapshot — это непрозрачное DateTime значение, указывающее предыдущий моментальный снимок.

Если этот параметр и sharesnapshot присутствуют, ответ будет содержать только диапазоны страниц, которые были изменены между двумя моментальными снимками. Если присутствует только prevsharesnapshot, ответ будет содержать только диапазоны страниц, которые были изменены между этим моментальным снимком и динамическим ресурсом.

Измененные страницы включают как обновленные, так и очищаемые страницы.

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

Обязательные и необязательные заголовки запросов описаны в следующих таблицах:

Общие заголовки запросов

Заголовок запроса Описание
Authorization Обязательно. Указывает схему авторизации, имя учетной записи и подпись. Дополнительные сведения см. в статье Авторизация запросов к службе хранилища Azure.
Date или x-ms-date Обязательно. Указывает универсальное время (UTC) для запроса. Дополнительные сведения см. в статье Авторизация запросов к службе хранилища Azure.
x-ms-version Требуется для всех авторизованных запросов. Указывает версию операции, используемой для этого запроса. Эта операция поддерживается в версии 2025-05-05 и более поздних версий для общих папок с включенным протоколом NFS.

Дополнительные сведения см. в разделе Управление версиями служб хранилища Azure.
Range Необязательный. Задает диапазон байтов, по которым следует перечислять диапазоны включительно. Если опущено, возвращаются все диапазоны для файла.
x-ms-range Необязательный. Задает диапазон байтов, по которым следует перечислять диапазоны включительно.

Если указаны Range и x-ms-range заголовки, служба использует значение x-ms-range. Дополнительные сведения см. в статье Указание заголовка диапазона для операций с файлами Azure.
x-ms-lease-id:<ID> Необязательный. Версия 2019-02-02 и более поздних версий. Если заголовок указан, операция будет выполнена только в том случае, если аренда файла в данный момент активна, а идентификатор аренды, указанный в запросе, соответствует тому, что в файле. В противном случае операция завершается ошибкой с кодом состояния 412 (сбой предварительных условий).

Этот заголовок игнорируется, если файл находится в общей папке с включенным протоколом NFS, который не поддерживает аренду файлов.
x-ms-client-request-id Необязательный. Предоставляет созданное клиентом непрозрачное значение с ограничением символов 1-kibibyte (KiB), записанным в журналах при настройке ведения журнала. Настоятельно рекомендуется использовать этот заголовок для сопоставления действий на стороне клиента с запросами, получаемыми сервером. Дополнительные сведения см. в статье Monitor Azure Files.
x-ms-file-request-intent Требуется, если заголовок Authorization указывает токен OAuth. Допустимое значение равно backup. Этот заголовок указывает, что Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action или Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action следует предоставить, если они включены в политику RBAC, назначенную удостоверению, авторизованному с помощью заголовка Authorization. Доступно для версии 2022-11-02 и более поздних версий.
x-ms-allow-trailing-dot: { <Boolean> } Необязательный. Версия 2022-11-02 и более поздних версий. Логическое значение указывает, следует ли обрезать конечную точку в URL-адресе запроса.

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

Дополнительные сведения см. в разделе Именование и ссылки на общие папки, каталоги, файлы и метаданные.
x-ms-file-support-rename: { <Boolean> } Необязательный. Поддерживается в версии 2024-05-04 и выше. Этот заголовок допускается только в том случае, если параметр запроса prevsharesnapshot присутствует. Логическое значение определяет, следует ли указать измененные диапазоны для файла, если расположение файла в предыдущем моментальном снимке отличается от расположения в URI запроса, в результате переименования или перемещения. Если значение равно true, будут возвращены допустимые измененные диапазоны для файла. Если значение равно false, операция приведет к сбою с ответом 409 (конфликт). Значение по умолчанию — false.

Только заголовки запросов SMB

Никакой.

Только заголовки запросов NFS

Никакой.

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

Никакой.

Ответ

Ответ включает код состояния 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, этот заголовок не будет присутствовать в ответе.

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

Никакой.

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

Никакой.

Текст ответа

Текст ответа содержит список не перекрывающихся допустимых диапазонов, отсортированных по увеличению диапазона адресов. Формат текста ответа выглядит следующим образом.

<?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, ответ содержит только страницы, которые отличаются между целевым моментальным снимком (или динамическим файлом) и предыдущим моментальным снимком. Возвращаемые диапазоны включают оба диапазона, которые были обновлены или были очищены. Формат этого ответа выглядит следующим образом:

<?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. Это возвращает диапазоны, которые отличаются между динамическим файлом и моментальным снимком или между двумя моментальными снимками файла на моментальных снимках. С помощью этих различий диапазон можно получить добавочный моментальный снимок файла. Добавочные моментальные снимки — это экономичный способ резервного копирования файлов, если вы хотите реализовать собственное решение резервного копирования.

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

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

См. также

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