Диапазон Put

Статья
03/29/2023

Операция Put Range записывает диапазон байтов в файл.

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

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

Запрос

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

Метод	Универсальный код ресурса (URI) запроса	параметр "Версия HTTP"
PUT	`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`	Требуется для всех авторизованных запросов. Задает версию операции, используемой для этого запроса. Дополнительные сведения см. в разделе Управление версиями для служб хранилища 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 }`	Обязательный. Необходимо указать один из следующих параметров: `update`. Записывает байты, указанные текстом запроса, в указанный диапазон. Для выполнения обновления заголовки `Range` и `Content-Length` должны совпадать. `clear`. Очищает указанный диапазон и освобождает пространство, используемое в хранилище для этого диапазона. Чтобы очистить диапазон, задайте для заголовка `Content-Length0`значение , а для заголовка `Range` — значение, указывающее диапазон, который нужно очистить, вплоть до максимального размера файла.
`x-ms-lease-id: <ID>`	Требуется, если файл имеет активную аренду. Доступно для версии 2019-02-02 и более поздних версий.
`x-ms-client-request-id`	Необязательный элемент. Предоставляет созданное клиентом непрозрачное значение с ограничением в 1 кибибайт (КиБ), которое записывается в журналы при настройке ведения журнала. Мы настоятельно рекомендуем использовать этот заголовок для сопоставления действий на стороне клиента с запросами, получаемыми сервером. Дополнительные сведения см. в разделе Мониторинг Файлы Azure.
`x-ms-file-last-write-time: { now ¦ preserve }`	Необязательный элемент. Версия 08.06.2021 и более поздняя. Можно указать одно из следующих значений. `now`: значение по умолчанию. Обновления метку времени последней записи к времени запроса. `preserve`: сохраняет существующую метку времени последней записи без изменений.
`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> }`	Необязательный элемент. Версия 02.11.2022 и более поздняя. Логическое значение указывает, следует ли обрезать завершающую точку в URL-адресе запроса. Дополнительные сведения см. в статье Именование общих папок, каталогов, файлов и метаданных и ссылки на нее.

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

Данные, представляющие отправляемый диапазон.

Пример запроса: обновление диапазона байтов

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 }`	Версия 17.04.2017 и более поздняя. Значение этого заголовка устанавливается в , `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`	Версия 08.06.2021 и более поздняя. Время последней записи для файла в формате ISO 8601. Например, `2017-05-10T17:52:33.9551861Z`.

Текст ответа

Нет.

Пример ответа

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 имеет блокировку, перекрывающуюся с диапазоном, заданным операцией Put Range с помощью x-ms-range. Дополнительные сведения см. в разделе Управление блокировками файлов.

Уведомления об изменении каталога клиента SMB

Протокол SMB поддерживает функцию API FindFirstChangeNotification , которая позволяет приложениям обнаруживать, когда происходят изменения в файловой системе. Он может определять, когда добавляется, изменяется или удаляется файл или каталог, а также изменяется размер, атрибуты или дескрипторы безопасности файла. Клиенты SMB, использующие этот API, не будут получать уведомления при изменении файла или каталога через ФАЙЛЫ AZURE REST API. Однако изменения, вызванные другими клиентами SMB, распространяются уведомления.

Пример несровненного четкого диапазона

Предположим, что файл создается с помощью команды Create File и один диапазон записывается с 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

При выполнении операции List Ranges в файле возвращается следующий текст ответа:

<?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=

Последующая операция List Ranges в файле возвращает следующий текст ответа:

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

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

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

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