Поместить диапазон
Операция Put Range записывает в файл диапазон байтов. Эта операция поддерживается в версии 2025-05-05 и более поздних версий для общих папок с включенным протоколом NFS.
Доступность протокола
| Протокол общей папки с включенным доступом | Доступный |
|---|---|
| SMB |
|
| NFS |
|
Просьба
Запрос Put Range создается следующим образом. Рекомендуется использовать ПРОТОКОЛ HTTPS.
| Метод | URI запроса | ВЕРСИЯ HTTP |
|---|---|---|
| КЛАСТЬ | https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=range |
HTTP/1.1 |
Замените компоненты пути, отображаемые в URI запроса собственным, следующим образом:
| Компонент path | Описание |
|---|---|
myaccount |
Имя учетной записи хранения. |
myshare |
Имя общей папки. |
mydirectorypath |
Необязательный. Путь к родительскому каталогу. |
myfile |
Имя файла. |
Сведения об ограничениях именования путей см. в разделе Имя и справочные ресурсы, каталоги, файлы и метаданные.
Параметры URI
Следующие дополнительные параметры можно указать в URI запроса.
| Параметр | Описание |
|---|---|
timeout |
Необязательный. Параметр timeout выражается в секундах. Дополнительные сведения см. в разделе Настройка времени ожидания операций службы файлов. |
Заголовки запросов
Обязательные и необязательные заголовки запросов описаны в следующих таблицах:
Общие заголовки запросов
| Заголовок запроса | Описание |
|---|---|
Authorization |
Обязательно. Указывает схему авторизации, имя учетной записи и подпись. Дополнительные сведения см. в статье Авторизация запросов к службе хранилища Azure. |
Date или x-ms-date |
Обязательно. Указывает универсальное время (UTC) для запроса. Дополнительные сведения см. в статье Авторизация запросов к службе хранилища Azure. |
x-ms-version |
Требуется для всех авторизованных запросов. Указывает версию операции, используемой для этого запроса. Эта операция поддерживается в версии 2025-05-05 и более поздних версий для общих папок с включенным протоколом NFS. Дополнительные сведения см. в разделе Управление версиями служб хранилища Azure. |
Range или x-ms-range |
Требуется Range или x-ms-range.Указывает диапазон записываемых байтов. Необходимо указать начало и конец диапазона. Этот заголовок определяется спецификацией протокола HTTP/1.1 . Для операции обновления диапазон может быть размером до 4 МиБ. Для четкой операции диапазон может быть до значения полного размера файла. Служба файлов принимает только один диапазон байтов для заголовков Range и x-ms-range, а диапазон байтов должен быть указан в следующем формате: bytes=startByte-endByte.Если указаны оба Range и x-ms-range, служба использует значение x-ms-range. Дополнительные сведения см. в разделе Указание заголовка диапазона для операций службы файлов. |
Content-Length |
Обязательно. Указывает количество байтов, передаваемых в тексте запроса. Если для заголовка x-ms-write задано значение clear, значение этого заголовка должно иметь значение 0. |
Content-MD5 |
Необязательный. Хэш MD5 содержимого. Этот хэш используется для проверки целостности данных во время транспорта. При указании заголовка Content-MD5 файлы Azure сравнивают хэш содержимого, которое прибыло со значением заголовка, которое было отправлено. Если два хэша не соответствуют, операция завершается ошибкой с кодом 400 (недопустимый запрос).Заголовок Content-MD5 не допускается, если для заголовка x-ms-write задано значение clear. Если он включен в запрос, служба файлов возвращает код состояния 400 (недопустимый запрос). |
x-ms-write: { update ¦ clear } |
Обязательно. Необходимо указать один из следующих параметров:
|
x-ms-lease-id:<ID> |
Требуется, если файл имеет активную аренду. Доступно для версии 2019-02-02 и более поздних версий. Этот заголовок игнорируется, если файл находится в общей папке с включенным протоколом NFS, который не поддерживает аренду файлов. |
x-ms-client-request-id |
Необязательный. Предоставляет созданное клиентом непрозрачное значение с ограничением символов 1-kibibyte (KiB), записанным в журналах при настройке ведения журнала. Настоятельно рекомендуется использовать этот заголовок для сопоставления действий на стороне клиента с запросами, получаемыми сервером. Дополнительные сведения см. в статье Monitor Azure Files. |
x-ms-file-last-write-time: { now ¦ preserve } |
Необязательный. Версия 2021-06-08 и более поздних версий. Можно указать один из следующих вариантов:
|
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, который поддерживает конечную точку по умолчанию. Дополнительные сведения см. в разделе Именование и ссылки на общие папки, каталоги, файлы и метаданные. |
Только заголовки запросов SMB
Никакой.
Только заголовки запросов NFS
Никакой.
Текст запроса
Данные, представляющие диапазон для отправки.
Пример запроса: обновление диапазона байтов
Request Syntax:
PUT https://myaccount.file.core.windows.net/myshare/myfile?comp=range HTTP/1.1
Request Headers:
x-ms-write: update
x-ms-date: Mon, 27 Jan 2014 22:15:50 GMT
x-ms-version: 2014-02-14
x-ms-range: bytes=0-65535
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=
Content-Length: 65536
Пример запроса: очистить диапазон байтов
Request Syntax:
PUT https://myaccount.file.core.windows.net/myshare/myfile?comp=range HTTP/1.1
Request Headers:
Range: bytes=1024-2048
x-ms-write: clear
x-ms-date: Mon, 27 Jan 2014 23:37:35 GMT
x-ms-version: 2014-02-14
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=
Ответ
Ответ включает код состояния HTTP и набор заголовков ответа.
Код состояния
Успешная операция возвращает код состояния 201 (создан). Дополнительные сведения о кодах состояния см. в коды состояния и коды ошибок.
Заголовки ответа
Ответ для этой операции содержит заголовки в следующих таблицах. Ответ также может включать дополнительные стандартные заголовки HTTP. Все стандартные заголовки соответствуют спецификации протокола HTTP/1.1.
Общие заголовки ответов
| Заголовок ответа | Описание |
|---|---|
ETag |
ETag содержит значение, представляющее версию файла. Значение заключено в кавычки. |
Last-Modified |
Возвращает дату и время последнего изменения каталога. Формат даты следует RFC 1123. Дополнительные сведения см. в разделе Представление значений даты и времени в заголовках. Любая операция, которая изменяет общую папку или ее свойства или метаданные, обновляет время последнего изменения. Операции с файлами не влияют на время последнего изменения общей папки. |
Content-MD5 |
Этот заголовок возвращается, чтобы клиент смог проверить целостность содержимого сообщения. Значение этого заголовка вычисляется службой файлов. Это не обязательно совпадает со значением, указанным в заголовках запроса. |
x-ms-request-id |
Уникально идентифицирует выполненный запрос и может использоваться для устранения неполадок запроса. Дополнительные сведения см. в статье Устранение неполадок с операциями API. |
x-ms-version |
Указывает версию службы файлов, которая использовалась для выполнения запроса. |
Date |
Значение даты и времени в формате UTC, созданное службой, указывающее время, когда был инициирован ответ. |
x-ms-request-server-encrypted: { true ¦ false } |
Версия 2017-04-17 и более поздних версий. Для этого заголовка задано значение true, если содержимое запроса успешно зашифровано с помощью указанного алгоритма. В противном случае значение равно false. |
x-ms-client-request-id |
Этот заголовок можно использовать для устранения неполадок запросов и соответствующих ответов. Значение этого заголовка равно значению заголовка x-ms-client-request-id, если оно присутствует в запросе, а значение содержит не более 1024 видимых символов ASCII. Если в запросе отсутствует заголовок x-ms-client-request-id, он отсутствует в ответе. |
x-ms-file-last-write-time |
Версия 2021-06-08 и более поздних версий. Время последней записи файла в формате ISO 8601. Пример: 2017-05-10T17:52:33.9551861Z. |
Заголовки ответов SMB только
Никакой.
Заголовки ответов NFS только
Никакой.
Текст ответа
Никакой.
Пример ответа
Response Status:
HTTP/1.1 201 Created
Response Headers:
Transfer-Encoding: chunked
Content-MD5: sQqNsWTgdUEFt6mb5y4/5Q==
Date:Mon, 27 Jan 2014 22:33:35 GMT
ETag: "0x8CB171BA9E94B0B"
Last-Modified: Mon, 27 Jan 2014 12:13:31 GMT
x-ms-version: 2014-02-14
Content-Length: 0
Server: Windows-Azure-File/1.0 Microsoft-HTTPAPI/2.0
Авторизация
Только владелец учетной записи может вызвать эту операцию.
Замечания
Операция Put Range записывает в файл диапазон байтов. Эту операцию можно вызвать только в существующем файле. Его нельзя вызвать для создания нового файла. Вызов Put Range с именем файла, который в настоящее время не существует, возвращает код состояния 404 (не найден).
Чтобы создать файл, вызовите создать файл. Размер файла может составлять до 4 ТиБ.
Для завершения операции Put Range разрешено 10 минут на МиБ. Если операция занимает более 10 минут на МиБ в среднем, время ожидания истекает.
Если файл имеет активную аренду, клиент должен указать действительный идентификатор аренды в запросе для записи диапазона.
операции обновления диапазона
Вызов Put Range с параметром Update выполняет запись на месте в указанном файле. Любое содержимое в указанном диапазоне перезаписывается с помощью обновления. Каждый диапазон, отправленный с Put Range для операции обновления, может быть размером до 4 МиБ. Если вы пытаетесь отправить диапазон размером более 4 МиБ, служба возвращает код состояния 413 (слишком большая сущность запроса).
операции очистки диапазона
Вызов Put Range с параметром Clear освобождает место в хранилище, если указанный диапазон равен 512 байтам. Диапазоны, которые были удалены, больше не отслеживаются как часть файла и не возвращаются в ответе диапазон списков. Если указанный диапазон не равен 512 байтам, операция записывает нули в начало или конец диапазона, который не равен 512 байтам, выровнен и освобождает остальную часть диапазона внутри 512-байтов.
Все диапазоны, которые не были удалены, возвращаются в ответе списков. Пример см. в разделе "Пример неуправляемого диапазона очистки", который приведен ниже.
аренды файлов
Вы можете вызвать файл аренды, чтобы получить монопольную блокировку записи в файл для других операций записи в течение бесконечной длительности.
блокировки диапазона байтов клиента SMB
Протокол SMB позволяет блокировать диапазон байтов для управления доступом на чтение и запись к регионам файла. Это означает, что Put Range в файле, расположенном в общей папке с включенным протоколом SMB, завершается ошибкой, если у клиента SMB есть блокировка, перекрывающая диапазон, заданный операцией Put Range с помощью x-ms-range. Дополнительные сведения см. в статье Управление блокировками файлов.
блокировки диапазона байтов клиента NFS
Блоки диапазона байтов POSIX протокола NFS являются консультативными, поэтому Put Range файла, расположенного в общей папке с включенным протоколом NFS, не завершится ошибкой, даже если конфликтующая блокировка диапазона байтов, удерживаемая клиентом NFS.
уведомления об изменении клиентского каталога SMB
Протокол SMB поддерживает функцию API FindFirstChangeNotification FindFirstChangeNotification, которая позволяет приложениям обнаруживать, когда изменения происходят в файловой системе. Он может определить, когда файл или каталог добавляется, изменяется или удаляется, а также при изменении размера, атрибутов или дескрипторов безопасности. Клиенты SMB, использующие этот API, не получат уведомления об изменении файла или каталога через REST API файлов Azure. Однако изменения, вызванные другими клиентами SMB, распространяют уведомления.
Пример неуправляемого диапазона
Предположим, что файл создается с помощью создания файла, а один диапазон записывается с помощью Put Rangeследующим образом:
Request Syntax:
PUT https://myaccount.file.core.windows.net/myshare/myfile?comp=range HTTP/1.1
Request Headers:
x-ms-write: updte
x-ms-date: Mon, 27 Jan 2014 22:15:50 GMT
x-ms-version: 2014-02-14
x-ms-range: bytes=0-65536
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=
Content-Length: 65536
Выполнение операции диапазонов списков в файле возвращает следующий текст ответа:
<?xml version="1.0" ecoding="utf-8"?>
<Ranges>
<Range>
<Start>0</Start>
<End>65536</End>
</Range>
</Ranges>
Теперь предположим, что выполняется неуправляемая операция диапазона байтов диапазона байтов:
Request Syntax:
PUT https://myaccount.file.core.windows.net/myshare/myfile?comp=range HTTP/1.1
Request Headers:
Range: bytes=768-2304
x-ms-write: clear
x-ms-date: Mon, 27 Jan 2014 23:37:35 GMT
x-ms-version: 2014-02-14
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=
Следующая операция диапазонов списков в файле возвращает следующий текст ответа:
<?xml version="1.0" encoding="utf-8"?>
<Ranges>
<Range>
<Start>0</Start>
<End>1024</End>
</Range>
<Range>
<Start>2048</Start>
<End>65535</End>
</Range>
</Ranges>
Обратите внимание, что нули были записаны в неуправляемое пространство с 768-1024 и 2048-2304.
Put Range не поддерживается в моментальном снимке общего ресурса, который является копией общего ресурса только для чтения. Попытка выполнить эту операцию на моментальном снимке общего ресурса завершается ошибкой 400 (InvalidQueryParameterValue).