Put Range From URL

Статья
03/29/2023

Операция Put Range From URL создает новый диапазон, который будет зафиксирован как часть файла, в котором содержимое считывается из URL-адреса. Этот API доступен с версии 2019-02-02.

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

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

Запрос

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

Метод	Универсальный код ресурса (URI) запроса	параметр "Версия HTTP"
`PUT`	`https://myaccount.file.core.windows.net/myshare/myfile?comp=range`	HTTP/1.1

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

Параметр	Описание
`timeout`	Необязательный элемент. Параметр `timeout` указывается в секундах. Дополнительные сведения см. в разделе Настройка времени ожидания для операций Файлы Azure.

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

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

Заголовок запроса	Описание
`Authorization`	Обязательный элемент. Указывает схему авторизации, имя учетной записи и подпись. Дополнительные сведения см. в статье Авторизация запросов к службе хранилища Azure .
`Date` или `x-ms-date`	Обязательный. Задает время запроса в формате UTC. Дополнительные сведения см. в статье Авторизация запросов к Службе хранилища Azure.
`x-ms-version`	Требуется для всех авторизованных запросов. Задает версию операции, используемой для этого запроса. Дополнительные сведения см. в разделе Управление версиями для служб хранилища Azure. Для `Put Range From URL`должна быть версия 2019-02-02 или более поздняя.
`x-ms-copy-source:name`	Обязательный элемент. Указывает URL-адрес исходного файла. Значением может быть URL-адрес длиной до 2 КиБ, указывающий файл. Значение должно быть закодировано в URL-адресе в том виде, в каком оно указано в запросе URI. Исходный файл должен быть общедоступным или должен быть авторизован с помощью подписанного URL-адреса. Если исходный файл является общедоступным, для выполнения операции авторизация не требуется. Ниже приведены некоторые примеры URL-адресов исходного объекта: `https://myaccount.file.core.windows.net/myshare/mydir/myfile` `https://myaccount.file.core.windows.net/myshare/mydir/myfile?<sastoken>`
`x-ms-copy-source-authorization: <scheme> <signature>`	Необязательный элемент. Указывает схему авторизации и подпись для источника копирования. Дополнительные сведения см. в статье Авторизация запросов к Службе хранилища Azure. Для Azure Active Directory поддерживается только носитель схемы. Этот заголовок поддерживается в версии 2020-10-02 и более поздних версиях.
`x-ms-write: { update }`	Обязательный. Необходимо указать только `update`. Запрос завершается ошибкой, если он вызывается с `clear`помощью . Значение `update` записывает байты, указанные текстом запроса, в указанные диапазоны.
`Range` или `x-ms-range`	Обязательный. Требуется `Range` или `x-ms-range`. Указывает диапазон байтов, который будет записан. Следует указать начало и конец диапазона. Этот заголовок определяется спецификацией протокола HTTP/1.1. Для операции обновления размер диапазона может составлять до 4 МиБ. Файлы Azure принимает только один байтовый диапазон для `Range` заголовков и `x-ms-range` , а диапазон байтов должен быть указан в следующем формате: `bytes=startByte-endByte`. Если заданы оба параметра, `Range` и `x-ms-range`, то служба использует значение `x-ms-range`. Дополнительные сведения см. в разделе Указание заголовка диапазона для операций Файлы Azure.
`x-ms-source-range`	Обязательный элемент. Указывает диапазон байтов, считываемых из источника. Следует указать начало и конец диапазона. Файлы Azure принимает только один байтовый диапазон для `Range` заголовков и `x-ms-range` , а диапазон байтов должен быть указан в следующем формате: `bytes=startByte-endByte`. Исходный диапазон может иметь размер до 4 МиБ. Если размер исходного диапазона превышает 4 МиБ, Файлы Azure возвращает код состояния 413 (слишком большой объект запроса). Если размер исходного диапазона не соответствует размеру диапазона (целевого диапазона), служба возвращает код состояния 400 (недопустимый запрос).
`Content-Length`	Обязательный. Указывает число байтов, передаваемых в тексте запроса. У этого заголовка должно быть значение `0`. Если длина не `0`равна , операция завершается ошибкой с кодом состояния 400 (недопустимый запрос).
`x-ms-client-request-id`	Необязательный элемент. Предоставляет созданное клиентом непрозрачное значение с ограничением в 1 кибибайт (КиБ), которое записывается в журналы при настройке ведения журнала. Мы настоятельно рекомендуем использовать этот заголовок для сопоставления действий на стороне клиента с запросами, получаемыми сервером. Дополнительные сведения см. в разделе Мониторинг Файлы Azure.
`x-ms-source-content-crc64`	Необязательный элемент. Хэш CRC64 указанного диапазона из URI. Этот хэш используется для проверки целостности диапазона во время передачи данных из URI. Если указан этот заголовок, Файлы Azure сравнивает хэш содержимого, полученного из источника копирования, с этим значением заголовка. Примечание. Этот хэш CRC64 не хранится в файле . Если два хэша не совпадают, операция завершается ошибкой с кодом 400 (недопустимый запрос).
`x-ms-source-if-match-crc64`	Необязательный элемент. Значение контрольной суммы CRC64. Укажите этот заголовок для выполнения операции только в том случае, если контрольная сумма заданного диапазона, считываемая из источника, совпадает с указанной контрольной суммой. Если указанное условие не выполняется, Файлы Azure возвращает код состояния 412 (сбой предварительного условия).
`x-ms-source-if-none-match-crc64`	Необязательный элемент. Значение контрольной суммы CRC64. Укажите этот заголовок для выполнения операции только в том случае, если контрольная сумма заданного диапазона, считываемого из источника, отличается от указанной контрольной суммы. Если указанное условие не выполняется, Файлы Azure возвращает код состояния 412 (сбой предварительного условия).
`x-ms-lease-id:<ID>`	Требуется, если файл имеет активную аренду. Чтобы выполнить эту операцию с файлом с активной арендой, укажите допустимый идентификатор аренды для этого заголовка.
`x-ms-client-request-id`	Необязательный элемент. Предоставляет созданное клиентом непрозрачное значение с ограничением в 1 кибибайт (КиБ), которое записывается в журналы аналитики при включении ведения журнала Azure Аналитика Службы хранилища. Мы настоятельно рекомендуем использовать этот заголовок при сопоставлении действий на стороне клиента с запросами, полученными сервером. Дополнительные сведения см. в разделе Мониторинг хранилища BLOB-объектов.
`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/actionMicrosoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action` или должны быть предоставлены, если они включены в политику RBAC, назначенную удостоверению, которое авторизовано с помощью заголовка `Authorization` . Доступно для версии 2022-11-02 и более поздних версий.
`x-ms-allow-trailing-dot: { <Boolean> }`	Необязательный элемент. Версия 2022-11-02 и более поздние. Логическое значение указывает, следует ли обрезать завершающую точку в URL-адресе запроса. Дополнительные сведения см. в разделе Именование общих папок, каталогов, файлов и метаданных и ссылки на нее.
`x-ms-source-allow-trailing-dot: { <Boolean> }`	Необязательный элемент. Версия 2022-11-02 и более поздние. Логическое значение указывает, следует ли обрезать конечную точку в исходном URL-адресе. Этот заголовок следует указывать только в том случае, если источником копирования является файл Azure. Этот заголовок не поддерживается для любого другого типа источника копирования. Дополнительные сведения см. в разделе Именование общих папок, каталогов, файлов и метаданных и ссылки на нее.

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

Текст запроса отсутствует.

Пример запроса

Request Syntax:  
PUT https://myaccount.file.core.windows.net/myshare/mydir/myfile?comp=range HTTP/1.1  
  
Request Headers:  
x-ms-page-write: update  
x-ms-copy-source: http://myaccount2.file.core.windows.net/myshare2/mydirectory2/myfile2?sv=2018-11-09&sp=r&sr=s&se=2018-08-22T09%3A59%3A28.2185790Z&sig=Qn6QEET3Gn%2FhCEVcXuwG7ssatIYiYRM5pNIy4Q3N0cQ%3D 
x-ms-date: Fri, 22 Aug 2018 01:15:50 GMT  
x-ms-version: 2019-02-02 
x-ms-range: bytes=100-1023  
x-ms-source-range: bytes=200-1123  
x-ms-source-content-crc64: 3bedb8b3730fc205 
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=  
Content-Length: 0

Ответ

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

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

Успешная операция возвращает код состояния 201 (создано).

Дополнительные сведения о кодах состояния см. в разделе Коды состояния и ошибок.

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

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

Заголовок ответа	Описание
`ETag`	Содержит значение, которое можно использовать для условного выполнения операций. Значение заключено в кавычки.
`Last-Modified`	Дата и время последнего изменения файла. Дата в формате согласно RFC 1123. Дополнительные сведения см. в разделе Представление значений даты и времени в заголовках. Любая операция записи в файл, включая обновление метаданных или свойств файла, изменяет время последнего изменения файла.
`x-ms-request-id`	Уникально идентифицирует выполненный запрос, и его можно использовать для устранения неполадок с запросом. Дополнительные сведения см. в разделе Устранение неполадок с операциями API.
`x-ms-version`	Указывает версию API FileREST, которая использовалась для выполнения запроса.
`Date`	Значение даты и времени в формате UTC, созданное службой, указывающее время, когда был инициирован ответ.
`x-ms-content-crc64`	Возвращается, чтобы клиент проверка для целостности содержимого сообщения. Значение этого заголовка вычисляется Файлы Azure. Оно не обязательно совпадает со значением, указанным в заголовках запроса.
`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:
Date: Sun, 22 Aug 2020 01:33:35 GMT  
ETag: "0x8CB171BA9E94B0B"  
Last-Modified: Wed, 22 Aug 2020 01:13:31 GMT  
x-ms-version: 2019-02-02
x-ms-content-crc64: 3bedb8b3730fc205 
Content-Length: 0  
Server: Windows-Azure-File/1.0 Microsoft-HTTPAPI/2.0

Авторизация

Эту операцию может вызвать владелец учетной записи и любой пользователь с подписанным URL-адресом с разрешениями на запись в этот файл или общую папку Azure.

Операция Put Range From URL записывает диапазон данных в файл. Если API вызывается для несуществующего файла в целевом объекте, API возвращает код состояния HTTP 404 (Не найдено).

В версии 2020-10-02 и более поздних версиях авторизация Azure Active Directory поддерживается для источника операции копирования.

Чтобы создать файл, вызовите Create File.

Put Range From URL Операция возвращает успешное выполнение 201 (создано), только если указанный диапазон записан в файл.

Операция чтения файла
Put Range From URL использует Get File для чтения данных и метаданных, атрибутов и списков управления доступом из источника.

Операция обновления файла
Вызов Put Range From URL с параметром update выполняет запись на месте для указанного файла. Любое содержимое в указанном файле перезаписывается с помощью обновления.  

Размер диапазона в Put Range From URL операции обновления может составлять до 4 МиБ. При попытке отправить диапазон размером более 4 МиБ Файлы Azure возвращает код состояния 413 (RequestEntityTooLarge).