Диапазоны списков
Операция 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.
Общие заголовки ответов
Заголовки ответов 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
.