Поставить страницу из URL-адреса

Операция Put Page From URL записывает диапазон страниц в страничный BLOB-объект, в котором содержимое считывается по URL-адресу. Этот API доступен начиная с версии 2018-11-09.

Запрос

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

URI запроса метода PUT Версия HTTP
https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=page HTTP/1.1

Имитированный URI службы хранилища

При построении запроса к эмулированной службе хранилища укажите имя узла эмулятора и порт службы BLOB-объектов как 127.0.0.1:10000, затем укажите имя эмулированной учетной записи хранилища.

URI запроса метода PUT Версия HTTP
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=page HTTP/1.1

Дополнительные сведения см. в разделе "Использование служба хранилища Azure Emulator для разработки и тестирования".

Параметры URI

В URI запроса могут быть заданы следующие дополнительные параметры.

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

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

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

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

Указывает диапазон байтов, записываемых как одна страница. Следует указать начало и конец диапазона. Этот заголовок определяется спецификацией протокола HTTP/1.1.

Для операции обновления страницы диапазон страниц может быть размером до 4 МиБ.

С учетом того, что страницы не должны превышать ограничение в 512 байт, начальная позиция должна быть остатком от деления 512, а конечная — остатком от деления 512 – 1. Примеры допустимых диапазонов байтов: 0–511, 512–1023 и т. д.

Служба BLOB-объектов принимает только один диапазон байтов для заголовкаRange, а диапазон байтов должен быть указан в следующем формате: bytes=startByte-endByte

Если заданы оба параметра, Range и x-ms-range, то служба использует значение x-ms-range. Дополнительные сведения см. в разделе "Указание заголовка диапазона для операций службы BLOB-объектов ".
x-ms-range Требуется Range или x-ms-range.

Указывает диапазон байтов, записываемых как одна страница. Следует указать начало и конец диапазона. Этот заголовок определяется спецификацией протокола HTTP/1.1.

Диапазон страниц может иметь размер до 4 МиБ.

С учетом того, что страницы не должны превышать ограничение в 512 байт, начальная позиция должна быть остатком от деления 512, а конечная — остатком от деления 512 – 1. Примеры допустимых диапазонов байтов: 0–511, 512–1023 и т. д.

Служба BLOB-объектов принимает только один диапазон байтов для заголовкаx-ms-range, а диапазон байтов должен быть указан в следующем формате: bytes=startByte-endByte

Если заданы оба параметра, Range и x-ms-range, то служба использует значение x-ms-range. Дополнительные сведения см. в разделе "Указание заголовка диапазона для операций службы BLOB-объектов ".
Content-Length Обязательный элемент. Указывает число байтов, передаваемых в тексте запроса. Значение этого заголовка должно быть равно нулю. Если длина не равна нулю, операция завершится ошибкой с кодом состояния 400 (недопустимый запрос).
x-ms-copy-source:name Обязательный. Указывает URL-адрес исходного большого двоичного объекта. Значением может быть URL-адрес длиной до 2 КиБ, задающий большой двоичный объект. Значение должно быть закодировано в URL-адресе в том виде, в каком оно указано в запросе URI. Исходный BLOB-объект должен быть общедоступным или должен быть авторизован с помощью подписанного URL-адреса. Если исходный BLOB-объект является общедоступным, для выполнения операции не требуется авторизация. Ниже приведены некоторые примеры URL-адресов исходных объектов:

- https://myaccount.blob.core.windows.net/mycontainer/myblob
- https://myaccount.blob.core.windows.net/mycontainer/myblob?snapshot=<DateTime>
- https://myaccount.blob.core.windows.net/mycontainer/myblob?versionid=<DateTime>
x-ms-copy-source-authorization: <scheme> <signature> Необязательный элемент. Указывает схему авторизации и подпись для источника копирования. Дополнительные сведения см. в разделе "Авторизация запросов к служба хранилища Azure".
Для Azure Active Directory поддерживается только носитель схемы.
Этот заголовок поддерживается в версиях 2020-10-02 и более поздних версиях.
x-ms-source-range Отправляет байты большого двоичного объекта в исходном URL-адресе в указанном диапазоне. Следует указать начало и конец диапазона. Этот заголовок определяется спецификацией протокола HTTP/1.1.

Диапазон страниц может иметь размер до 4 МиБ.

Служба BLOB-объектов принимает только один диапазон байтов для заголовкаx-ms-source-range, а диапазон байтов должен быть указан в следующем формате: bytes=startByte-endByte

Дополнительные сведения см. в разделе "Указание заголовка диапазона для операций службы BLOB-объектов ".
x-ms-source-content-md5 Необязательный элемент. Хэш MD5 содержимого страницы из URI. Этот хэш используется для проверки целостности страницы во время передачи данных из URI. Если этот заголовок указан, служба хранилища сравнивает хэш содержимого, полученного из источника копирования, с этим значением заголовка.

Обратите внимание, что этот хэш md5 не хранится в большом двоичном объекте.

Если хэш не совпадает, операция завершится с ошибкой и кодом ошибки 400 (неправильный запрос).
x-ms-source-content-crc64 Необязательный элемент. Хэш CRC64 содержимого страницы из URI. Этот хэш используется для проверки целостности страницы во время передачи данных из URI. Если этот заголовок указан, служба хранилища сравнивает хэш содержимого, полученного из источника копирования, с этим значением заголовка.

Обратите внимание, что этот хэш CRC64 не хранится в большом двоичном объекте.

Если хэш не совпадает, операция завершится с ошибкой и кодом ошибки 400 (неправильный запрос).

x-ms-source-content-md5 Если оба заголовка x-ms-source-content-crc64 присутствуют, запрос завершится ошибкой 400 (недопустимый запрос).

Этот заголовок поддерживается в версиях 2019-02-02 или более поздней версии.
x-ms-lease-id:<ID> Требуется, если у большого двоичного объекта имеется активная аренда. Для выполнения этой операции в большом двоичном объекте с активной арендой укажите допустимый идентификатор аренды для этого заголовка.
x-ms-if-sequence-number-le: <num> Необязательный элемент. Если порядковый номер большого двоичного объекта меньше указанного значения или равен ему, то запрос будет выполнен; в противном случае он завершается с ошибкой SequenceNumberConditionNotMet (код состояния HTTP 412 — не выполнено предварительное условие).
x-ms-if-sequence-number-lt: <num> Необязательный элемент. Если порядковый номер большого двоичного объекта меньше указанного значения, то запрос будет выполнен; в противном случае он завершается с ошибкой SequenceNumberConditionNotMet (код состояния HTTP 412 — не выполнено предварительное условие).
x-ms-if-sequence-number-eq: <num> Необязательный элемент. Если порядковый номер большого двоичного объекта равен указанному значению, то запрос будет выполнен; в противном случае он завершается с ошибкой SequenceNumberConditionNotMet (код состояния HTTP 412 — не выполнено предварительное условие).
If-Modified-Since Необязательный элемент. Значение DateTime. Укажите этот условный заголовок для записи страницы только в том случае, если большой двоичный заголовок был изменен с указанных даты и времени. Если большой двоичный объект не был изменен, служба BLOB-объектов возвращает код состояния 412 (предварительное условие не выполнено).
If-Unmodified-Since Необязательный элемент. Значение DateTime. Укажите этот условный заголовок для записи страницы, только если большой двоичный заголовок не был изменен с указанных даты и времени. Если большой двоичный объект был изменен, то служба BLOB-объектов возвращает код состояния 412 (предварительное условие не выполнено).
If-Match Необязательный элемент. Значение ETag. Укажите значение ETag, чтобы этот условный заголовок записал страницу, если значение ETag большого двоичного объекта совпадает с указанным значением. Если значения не совпадают, то служба BLOB-объектов возвращает код состояния 412 (необходимое условие не выполнено).
If-None-Match Необязательный элемент. Значение ETag.

Укажите значение ETag, чтобы этот условный заголовок записал страницу, если значение ETag большого двоичного объекта не совпадает с указанным значением. Если значения совпадают, то служба BLOB-объектов возвращает код состояния 412 (необходимое условие не выполнено).
x-ms-encryption-scope Необязательный элемент. Указывает область шифрования, используемую для шифрования исходного содержимого. Этот заголовок поддерживается в версиях 2019-02-02 или более поздней версии.
x-ms-client-request-id Необязательный элемент. Предоставляет созданное клиентом непрозрачное значение с ограничением на 1 КиБ, которое записывается в журналы аналитики при включении ведения журнала аналитики хранилища. Мы настоятельно рекомендуем использовать этот заголовок для сопоставления операций на стороне клиента с запросами, которые получает сервер. Дополнительные сведения см. в статье "Сведения о Аналитика Службы хранилища ведения журнала и ведения журнала Azure: использование журналов для отслеживания запросов служба хранилища".

Эта операция также поддерживает использование условных заголовков для выполнения операции при выполнении определенного условия. Дополнительные сведения см. в статье Указание условных заголовков для операций службы BLOB-объектов.

Заголовки запросов (ключи шифрования, предоставленные клиентом)

Начиная с версии 2019-02-02, в запросе можно указать следующие заголовки, чтобы зашифровать большой двоичный объект, зашифрованный с помощью предоставленного клиентом ключа. Шифрование с помощью предоставленного клиентом ключа (и соответствующего набора заголовков) является необязательным.

Заголовок запроса Описание
x-ms-encryption-key Обязательный. Ключ шифрования AES-256 в кодировке Base64.
x-ms-encryption-key-sha256 Обязательный. Хэш sha256 в кодировке Base64 ключа шифрования.
x-ms-encryption-algorithm: AES256 Обязательный. Указывает алгоритм, используемый для шифрования. Для этого заголовка должно быть установлено значение AES256.

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

Текст запроса содержит страницу.

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

  
Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=page HTTP/1.1  
  
Request Headers:   
x-ms-date: Fri, 16 Sep 2011 22:15:50 GMT  
x-ms-version: 2018-11-09  
x-ms-range: bytes=0-65535  
x-ms-copy-source: https://myaccount.blob.core.windows.net/mycontainer/myblob
x-ms-source-range: bytes=0-65535
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=  
Content-Length: 0  
  

Ответ

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

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

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

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

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

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

Синтаксис Описание
ETag ETag BLOB-объекта. Если версия запроса 2011-08-18 или более поздняя, то значение ETag будет указано в кавычках. ETag можно использовать для выполнения условной операции Put Page From URL путем указания значения в заголовке запроса If-Match или If-None-Match.
Last-Modified Дата и время последнего изменения большого двоичного объекта. Дата в формате согласно RFC 1123. Дополнительные сведения см. в разделе "Представление значений Date-Time" в заголовках.

Любая операция записи в большой двоичный объект, включая обновления метаданных или свойств, изменяет время последнего изменения большого двоичного объекта.
Content-MD5 Этот заголовок возвращается для того, чтобы клиент мог проверить целостность содержимого сообщения. Значение этого заголовка вычисляется службой BLOB-объектов. Значение может не совпадать с указанным в заголовках запроса. Для версий 2019-02-02 или более поздней версии этот заголовок возвращается только в том случае, если запрос содержит этот заголовок.
x-ms-content-crc64 Для версий 2019-02-02 или более поздней версии возвращается этот заголовок, чтобы клиент смог проверить целостность содержимого сообщения. Значение этого заголовка вычисляется службой BLOB-объектов. Значение может не совпадать с указанным в заголовках запроса.

Этот заголовок возвращается, если x-ms-source-content-md5 заголовок отсутствует в запросе.
x-ms-blob-sequence-number Текущий порядковый номер для страничного большого двоичного объекта.
x-ms-request-id Этот заголовок однозначно определяет выполненный запрос, его также можно использовать для устранения связанных с запросом неполадок. Дополнительные сведения см. в разделе "Устранение неполадок операций API".
x-ms-version Указывает версию службы BLOB-объектов, используемую для выполнения запроса. Этот заголовок возвращается для запросов к версии 2009-09-19 и более поздним версиям.
Date Значение даты и времени в формате UTC, сформированное службой и указывающее время, когда был инициирован ответ.
x-ms-request-server-encrypted: true/false Версия 2015-12-11 или более позднюю. Значение этого заголовка задается true , если содержимое запроса успешно зашифровано с помощью указанного алгоритма и false в противном случае.
x-ms-encryption-key-sha256 Версия 2019-02-02 или более позднюю. Этот заголовок возвращается, если запрос использовал предоставленный клиентом ключ для шифрования, чтобы клиент смог убедиться, что содержимое запроса успешно зашифровано с помощью предоставленного ключа.
x-ms-encryption-scope Версия 2019-02-02 или более позднюю. Этот заголовок возвращается, если запрос использовал область шифрования, чтобы клиент смог убедиться, что содержимое запроса успешно зашифровано с помощью области шифрования.
x-ms-client-request-id Этот заголовок можно использовать для устранения неполадок запросов и соответствующих ответов. Значение этого заголовка равно значению заголовка x-ms-client-request-id , если оно присутствует в запросе, а значение не более 1024 видимых символов ASCII. x-ms-client-request-id Если заголовок отсутствует в запросе, этот заголовок не будет присутствовать в ответе.

Текст ответа

Нет.

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

Response Status:  
HTTP/1.1 201 Created  
  
Response Headers:  
Transfer-Encoding: chunked  
x-ms-content-crc64: 77uWZTolTHU  
Date: Sun, 25 Sep 2011 22:33:35 GMT  
ETag: "0x8CB171BA9E94B0B"  
Last-Modified: Sun, 25 Sep 2011 12:13:31 GMT  
x-ms-version: 2011-08-18  
x-ms-blob-sequence-number: 0  
Content-Length: 0  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0  
  

Авторизация

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

Комментарии

Операция Put Page From URL записывает диапазон страниц в страничный большой двоичный объект. Эта операция может быть вызвана только для существующего страничного большого двоичного объекта. Ее нельзя вызывать для создания нового страничного или блочного большого двоичного объекта. Вызов метода Put Page From URL с именем большого двоичного объекта, который в настоящий момент не существует, возвращает ошибку «Объект не найден» (код состояния HTTP 404 — не найдено).

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

Чтобы создать новый страничный BLOB-объект, вызовите put BLOB-объект и укажите тип большого двоичного объекта для создания в качестве страничного BLOB-объекта. Размер страничного BLOB-объекта может составлять до 8 ТиБ.

Если большой двоичный объект имеет активную аренду, то клиент должен указать в запросе идентификатор аренды для записи страницы.

Операции обновления страницы

Вызов Put Page From URL выполняет запись на месте на указанном страничном BLOB-объекте. Содержимое на указанной странице будет перезаписано в результате обновления.

Важно!

Если время ожидания сервера истекло или соединение закрыто во время операции Put Page From URL, то страница может не быть обновлена. Поэтому необходимо продолжить попытки обновления до получения ответа с указанием успешной операции.

Каждый диапазон страниц, отправленных Put Page From URL для операции обновления, может иметь размер до 4 МиБ. Начальный и конечный диапазон страницы не должны превышать ограничение в 512 байт. Если попробовать загрузить диапазон страниц более 4 MБ, то служба возвращает код состояния 413 (слишком большая сущность запроса).

Решение проблем параллелизма

Служба BLOB-объектов обрабатывает одновременные операции записи на перекрывающиеся страницы последовательно: последняя страница, обработанная службой, определяет содержимое большого двоичного объекта. Таким образом, для обеспечения целостности содержимого большого двоичного объекта клиент должен обрабатывать операции записи в пересекающиеся страницы следующим образом.

  • Можно проверить значение заголовка ответа Last-Modified для каждого успешного вызова Put Page From URL. Порядок ответов, возвращенных службой BLOB-объектов, может не соответствовать порядку, в котором они выполнялись службой. Однако значение Last-Modified всегда указывает порядок, в котором служба обрабатывала запросы.

  • Обновления можно выполнять условно, исходя из значения ETag большого двоичного объекта или времени последнего изменения, опираясь на оптимистичный параллелизм. Этот подход хорошо работает для относительно небольшого числа параллельных операций записи. Для этой цели нужно использовать условные заголовки If-Match, If-None-Match, If-Modified-Since и If-Unmodified-Since.

  • Blob-объект аренды можно вызвать для блокировки большого двоичного объекта на другие операции записи в течение одной минуты или дольше, если аренда продлена.

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

Использование порядкового номера страничного большого двоичного объекта для повторов запроса

Если истекло время ожидания для метода Put Page From URL, а метод не вернул ответ, то не существует возможности узнать наверняка, был ли выполнен запрос. Поэтому запрос нужно выполнить повторно. Однако в силу распределенной природы служб хранилища Azure может получиться так, что первоначальный запрос будет обработан после успешного выполнения повторного запроса. Отложенный первоначальный запрос может перезаписать другие обновления и привести к непредвиденному результату. На следующей схеме показано, как это может случиться.

  1. Истекает время ожидания для запроса Put Page From URL на запись значения X в страницу 0, или запрос не возвращает ответ.

  2. Повторный запрос на запись значения X в страницу 0 завершается успешно.

  3. Запрос на запись значения Y в страницу 0 завершается успешно.

  4. Первоначальный запрос завершается успешно и записывает значение X в страницу 0.

  5. Операция чтения страницы 0 возвращает значение X, тогда как клиент ожидал получить значение Y.

Такого рода конфликт может возникнуть, если первоначальный запрос не вернул код состояния в диапазоне 100–499 или 503 (сервер занят). Если возвращается один из этих кодов, то можно быть уверенным, завершился ли запрос успешно. Однако если служба возвращает код состояния за пределами этого диапазона, то нет возможности узнать состояние первоначального запроса.

Чтобы предотвратить такого рода конфликт, можно использовать порядковый номер страничного большого двоичного объекта. В результате при повторе запроса первоначальный запрос не сможет завершиться успешно. Для этого, прежде чем повторять первоначальный запрос, необходимо увеличить порядковый номер. Затем нужно указать порядковый номер в условных заголовках, чтобы запрос завершился ошибкой, если его порядковый номер не соответствует ожидаемому. Этот подход показан на следующей схеме.

  1. Клиент создает страничный BLOB-объект с put BLOB-объект и устанавливает для его порядкового номера значение 0.

  2. Запрос Put Page From URL на запись значения "X" на страницу 0 с заголовком if-sequence-number-lt , установленным для 1 ожидания ожидания, или не возвращает ответ.

  3. Клиент вызывает метод установки свойств большого двоичного объекта, чтобы обновить порядковый номер до 1.

  4. Повторный запрос на запись значения "X" на страницу 0 с if-sequence-number-lt установленным значением 2 успешно.

  5. Запрос на запись значения "Y" на страницу 0 с if-sequence-number-lt установленным значением 2 успешно.

  6. Исходный запрос, наконец, обрабатывается, но он завершается ошибкой, так как указывает условие, которое порядковый номер должен быть меньше 1 (то есть if-sequence-num-lt заголовок имеет значение 1). Возникает ошибка SequenceNumberConditionNotMet (код состояния HTTP 412 — не выполнено предварительное условие).

  7. Чтение страницы 0 возвращает ожидаемое значение Y.

См. также

Авторизация запросов на служба хранилища Azure
Коды состояний и ошибок
Задание времени ожидания для операций службы BLOB-объектов