Копирование BLOB-объекта из URL-адреса

  • Статья

Операция Copy Blob From URL синхронно копирует BLOB-объект в место назначения в учетной записи хранения для исходных размеров BLOB-объектов до 256 мебибайт (МиБ). Этот API доступен начиная с версии 2018-03-28.

Источником для операции может быть любой Copy Blob From URL зафиксированный блочный BLOB-объект в любой учетной записи хранения Azure, которая является общедоступной или авторизованной с подписанным URL-адресом.

Запрос

Запрос можно создать Copy Blob From URL следующим образом. Рекомендуется использовать ПРОТОКОЛ HTTPS. Замените myaccount именем учетной записи хранения, mycontainer именем контейнера, а myblob — именем целевого BLOB-объекта.

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

Универсальный код ресурса (URI) для эмулированной службы хранилища

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

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

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

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

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

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

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

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

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

Начиная с версии 2009-09-19 имена метаданных должны соответствовать правилам именования для идентификаторов C#. Дополнительные сведения см. в статье Именование контейнеров, BLOB-объектов и метаданных и ссылки на нее.
x-ms-encryption-scope Необязательный элемент. Указывает область шифрования для шифрования содержимого запроса. Этот заголовок поддерживается в версии 2020-12-06 и более поздних версиях.
x-ms-tags Необязательный элемент. Задает теги в кодировке строки запроса для большого двоичного объекта. Теги не копируются из источника копирования. Дополнительные сведения см. в разделе Примечания. Поддерживается в версии 2019-12-12 и более поздних версиях.
x-ms-copy-source-tag-option Необязательный элемент. Возможные значения: REPLACE и COPY (с учетом регистра). Значение по умолчанию — REPLACE.

Если COPY указан параметр , теги из исходного BLOB-объекта будут скопированы в целевой BLOB-объект. Исходный BLOB-объект должен быть частным, а запрос должен иметь разрешение на операцию Получения тегов BLOB-объектов в исходном BLOB-объекте и операцию Set Blob Tags в целевом BLOB-объекте. Это приведет к дополнительному вызову операции в Get Blob Tags исходной учетной записи.

REPLACE задает теги, заданные заголовком x-ms-tags для целевого BLOB-объекта. Если x-ms-tags указывает REPLACE и нет тегов, то в целевом blob-объекте не будут заданы теги. Указание COPY и x-ms-tags приведет к ошибке 409 (конфликт).

Поддерживается в версии 2021-04-10 и более поздних.
x-ms-source-if-modified-since Необязательный элемент. Значение DateTime. Задайте этот заголовок условной операции, чтобы BLOB-объект копировался, только если BLOB-объект источника был изменен, начиная с указанной даты-времени. Если исходный BLOB-объект не был изменен, хранилище BLOB-объектов возвращает код состояния 412 (сбой предварительного условия). Этот заголовок нельзя указать, если источником является файл Azure.
x-ms-source-if-unmodified-since Необязательный элемент. Значение DateTime. Задайте этот заголовок условной операции, чтобы BLOB-объект копировался, только если BLOB-объект источника не был изменен, начиная с указанной даты-времени. Если исходный BLOB-объект был изменен, хранилище BLOB-объектов возвращает код состояния 412 (сбой предварительного условия). Этот заголовок нельзя указать, если источником является файл Azure.
x-ms-source-if-match Необязательный элемент. Значение ETag. Укажите этот условный заголовок, чтобы скопировать исходный BLOB-объект, только если его ETag значение совпадает с указанным значением. Если значения не совпадают, хранилище BLOB-объектов возвращает код состояния 412 (сбой предварительного условия). Этот заголовок нельзя указать, если источником является файл Azure.
x-ms-source-if-none-match Необязательный элемент. Значение ETag. Укажите этот условный заголовок для копирования большого двоичного объекта, только если его ETag значение не соответствует указанному значению. Если значения идентичны, хранилище BLOB-объектов возвращает код состояния 412 (сбой предварительного условия). Этот заголовок нельзя указать, если источником является файл Azure.
If-Modified-Since Необязательный элемент. Значение DateTime. Задайте этот заголовок условной операции, чтобы копировать BLOB-объект, только если BLOB-объект назначения был изменен после указанной даты-времени. Если целевой BLOB-объект не был изменен, хранилище BLOB-объектов возвращает код состояния 412 (сбой предварительного условия).
If-Unmodified-Since Необязательный элемент. Значение DateTime. Задайте этот заголовок условной операции, чтобы копировать BLOB-объект, только если BLOB-объект назначения не был изменен после указанной даты-времени. Если целевой BLOB-объект был изменен, хранилище BLOB-объектов возвращает код состояния 412 (сбой предварительного условия).
If-Match Необязательный элемент. Значение ETag. ETag Укажите значение для этого условного заголовка, чтобы скопировать большой двоичный объект, только если указанное ETag значение совпадает со значением ETag существующего целевого BLOB-объекта. Если значения не совпадают, хранилище BLOB-объектов возвращает код состояния 412 (сбой предварительного условия).
If-None-Match Необязательный элемент. Значение ETag или подстановочный знак (*).

ETag Укажите значение для этого условного заголовка, чтобы скопировать большой двоичный объект, только если указанное ETag значение не соответствует значению ETag целевого BLOB-объекта.

Укажите подстановочный знак (*) для выполнения операции только в том случае, если целевой BLOB-объект не существует.

Если указанное условие не выполняется, хранилище BLOB-объектов возвращает код состояния 412 (сбой предварительного условия).
x-ms-copy-source:name Обязательный. Указывает URL-адрес исходного большого двоичного объекта. Значением может быть URL-адрес длиной до 2 кибибайт (КиБ), указывающий большой двоичный объект. Значение должно быть закодировано в URL-адресе в том виде, в каком оно указано в запросе URI. Исходный BLOB-объект должен быть общедоступным или авторизован с помощью подписанного URL-адреса. Если исходный BLOB-объект является общедоступным, для выполнения операции авторизация не требуется. Если размер исходного BLOB-объекта превышает 256 МиБ, запрос завершается ошибкой 409 (конфликт). Типом исходного BLOB-объекта должен быть блочный 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-requires-sync:true Обязательный. Указывает, что это синхронная Copy Blob From URL операция, а не асинхронная Copy Blob .
x-ms-source-content-md5 Необязательный элемент. Указывает md5-хэш содержимого большого двоичного объекта из универсального кода ресурса (URI). Этот хэш используется для проверки целостности большого двоичного объекта во время передачи данных из URI. Если указан этот заголовок, служба хранилища сравнивает хэш содержимого, полученного из источника копирования, с этим значением заголовка.

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

Если два хэша не совпадают, операция завершается ошибкой с кодом 400 (недопустимый запрос).
x-ms-lease-id:<ID> Требуется, если BLOB-объект назначения имеет активную аренду. Идентификатор аренды, указанный для этого заголовка, должен согласовываться с идентификатором аренды большого двоичного объекта назначения. Если запрос не содержит идентификатор аренды или он недопустим, операция завершается ошибкой с кодом состояния 412 (сбой условия).

Если этот заголовок указан и целевой BLOB-объект в настоящее время не имеет активной аренды, операция завершается ошибкой с кодом состояния 412 (сбой предварительного условия).

В версии 2012-02-12 и более поздних это значение должно указывать активную бесконечную аренду для арендованного BLOB-объекта. Сбой идентификатора аренды конечной длительности с кодом состояния 412 (сбой условия).
x-ms-client-request-id Необязательный элемент. Предоставляет созданное клиентом непрозрачное значение с ограничением в 1 КиБ символов, которое записывается в журналы при настройке ведения журнала. Мы настоятельно рекомендуем использовать этот заголовок для сопоставления действий на стороне клиента с запросами, получаемыми сервером.
x-ms-access-tier Необязательный элемент. Указывает уровень, который необходимо задать для целевого BLOB-объекта. Этот заголовок предназначен для страничных BLOB-объектов в учетной записи уровня "Премиум" только с версии 2017-04-17 и более поздних версий. Полный список поддерживаемых уровней см. в статье Высокопроизводительное хранилище класса Premium и управляемые диски для виртуальных машин. Этот заголовок поддерживается в версии 2018-11-09 и более поздних для блочных BLOB-объектов. В хранилище BLOB-объектов или общего назначения учетных записях версии 2 поддерживается разнесение по уровням блочных BLOB-объектов. Допустимые значения: Hot, Cool, Cold и Archive. Примечание:Cold tier поддерживается для версии 2021-12-02 и более поздних версий. Подробные сведения о разных уровнях блочных BLOB-объектов см. в разделе Горячий, холодный и архивный уровни хранилища.

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

Нет.

Ответ

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

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

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

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

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

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

Заголовок ответа Описание
ETag Если копирование завершено, содержит ETag значение целевого большого двоичного объекта. Если копирование не завершено, содержит ETag значение пустого большого двоичного объекта, созданного в начале копии.

Значение ETag находится в кавычках.
Last-Modified Возвращает дату и время завершения операции копирования в целевой BLOB-объект.
x-ms-request-id Однозначно идентифицирует выполненный запрос. Его можно использовать для устранения неполадок с запросом. Дополнительные сведения см. в разделе Устранение неполадок с операциями API.
x-ms-version Указывает версию хранилища BLOB-объектов, которая используется для выполнения запроса.
Date Значение даты и времени в формате UTC, указывающее время, в которое служба отправила ответ.
x-ms-copy-id: <id> Идентификатор строки для этой операции копирования.
x-ms-copy-status: <success> Указывает состояние операции копирования. Значение success означает, что операция успешно завершена.
x-ms-client-request-id Может использоваться для устранения неполадок с запросами и соответствующими ответами. Значение этого заголовка равно значению заголовка x-ms-client-request-id , если он присутствует в запросе и содержит не более 1024 видимых символов ASCII. Если заголовок x-ms-client-request-id отсутствует в запросе, этот заголовок не будет присутствовать в ответе.
x-ms-request-server-encrypted: true/false Задайте значение , true если содержимое запроса успешно зашифровано с помощью указанного алгоритма. В противном случае — значение false.
x-ms-encryption-scope Возвращается, если запрос использовал область шифрования, чтобы клиент смог убедиться, что содержимое запроса успешно зашифровано с помощью область шифрования.

Текст ответа

Нет.

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

Ниже приведен образец ответа на запрос копирования BLOB-объекта.

Response Status:  
HTTP/1.1 202 Accepted  
  
Response Headers:   
Last-Modified: <date>   
ETag: "0x8CEB669D794AFE2"  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0  
x-ms-request-id: cc6b209a-b593-4be1-a38a-dde7c106f402  
x-ms-version: 2018-03-28  
x-ms-copy-id: 1f812371-a41d-49e6-b123-f4b542e851c5  
x-ms-copy-status: success  
Date: <date>

Авторизация

При вызове любой операции доступа к данным в службе хранилища Azure требуется авторизация. В следующей таблице показано, как можно авторизовать целевые и исходные Copy Blob From URL объекты для операции.

Тип объекта авторизация Microsoft Entra ID Авторизация подписанного URL-адреса (SAS) Авторизация с общим ключом (или общий ключ Lite)
Блочный BLOB-объект назначения Да Да Да
Исходный блочный BLOB-объект в той же учетной записи хранения Да Да Да
Исходный блочный BLOB-объект в другой учетной записи хранения Нет Да Нет

Если в запросе указаны теги в заголовке x-ms-tags запроса, вызывающий объект должен соответствовать требованиям авторизации операции Set Blob Tags (Задать теги BLOB-объектов ).

Вы можете авторизовать Copy Blob From URL операцию, как описано ниже. Обратите внимание, что исходный BLOB-объект в другой учетной записи хранения должен быть авторизован отдельно с помощью маркера SAS с разрешением Чтение (r). Дополнительные сведения об авторизации исходного BLOB-объекта см. в сведениях о заголовке x-ms-copy-sourceзапроса .

Служба хранилища Azure поддерживает использование Microsoft Entra ID для авторизации запросов к данным BLOB-объектов. С помощью Microsoft Entra ID можно использовать управление доступом на основе ролей Azure (Azure RBAC) для предоставления разрешений субъекту безопасности. Субъектом безопасности может быть пользователь, группа, субъект-служба приложения или управляемое удостоверение Azure. Субъект безопасности проходит проверку подлинности Microsoft Entra ID для возврата маркера OAuth 2.0. Затем маркер можно использовать для авторизации запроса к службе BLOB-объектов.

Дополнительные сведения об авторизации с помощью Microsoft Entra ID см. в статье Авторизация доступа к BLOB-объектам с помощью Microsoft Entra ID.

Разрешения

Ниже перечислены действия RBAC, необходимые Microsoft Entra пользователю, группе или субъекту-службе для вызова Copy Blob From URL операции, а также встроенная роль Azure RBAC с минимальными привилегиями, которая включает это действие:

Целевой BLOB-объект

Исходный BLOB-объект в одной учетной записи хранения

Дополнительные сведения о назначении ролей с помощью Azure RBAC см. в статье Назначение роли Azure для доступа к данным BLOB-объектов.

Комментарии

Исходный и целевой Copy Blob From URL BLOB-объект для операции должен быть блочный BLOB-объект.

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

Операция Copy Blob From URL всегда копирует весь исходный BLOB-объект. Копирование диапазона байтов или набора блоков не поддерживается.

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

При копировании из блочного BLOB-объекта копируются все зафиксированные блоки и их идентификаторы блоков. Незафиксированные блоки не копируются. В конце операции копирования целевой BLOB-объект будет иметь то же количество зафиксированных блоков, что и источник.

Значение ETag блочного BLOB-объекта изменяется при Copy Blob From URL запуске операции и по завершении операции.

Копирование свойств и метаданных BLOB-объекта

При копировании блочного BLOB-объекта в целевой blob-объект копируются следующие системные свойства с теми же значениями:

  • Content-Type

  • Content-Encoding

  • Content-Language

  • Content-Length

  • Cache-Control

  • Content-MD5

  • Content-Disposition

Список зафиксированных блоков исходного BLOB-объекта также копируется в целевой BLOB-объект. Незафиксированные блоки не копируются.

Целевой BLOB-объект всегда имеет тот же размер, что и исходный BLOB-объект, поэтому значение заголовка Content-Length для целевого BLOB-объекта совпадает со значением этого заголовка для исходного BLOB-объекта.

Если заголовок x-ms-tags предоставляет теги для целевого BLOB-объекта, они должны быть закодированы в строке запроса. Ключи и значения тегов должны соответствовать требованиям к именованию и длине, указанным в операции Задание тегов BLOB-объектов .

Заголовок x-ms-tags может содержать до 2 килобит тегов. Если требуется больше тегов, используйте Set Blob Tags операцию .

Если заголовок x-ms-tags не содержит тегов, теги не копируются из исходного BLOB-объекта.

Копирование арендованного BLOB-объекта

Операция Copy Blob From URL считывает только из исходного BLOB-объекта, поэтому состояние аренды исходного BLOB-объекта не имеет значения.

Выставление счетов

Запросы на ценообразование могут поступать от клиентов, использующих API хранилища BLOB-объектов, напрямую через REST API хранилища BLOB-объектов или из клиентской библиотеки службы хранилища Azure. Эти запросы начисляют плату за транзакцию. Тип транзакции влияет на способ оплаты учетной записи. Например, транзакции чтения начисляются к категории выставления счетов, отличной от категории операций записи. В следующей таблице показана категория выставления счетов для Copy Blob From URL запросов на основе типа учетной записи хранения.

Операция Тип учетной записи хранения Категория выставления счетов
Копирование BLOB-объекта из URL-адреса (целевая учетная запись1) Блочный BLOB-объект (ценовая категории "Премиум")
Общего назначения версии 2 (цен. категория "Стандартный")
Стандартная общего назначения версии 1		 Операции записи
Копирование BLOB-объекта из URL-адреса (исходная учетная запись2) Блочный BLOB-объект (ценовая категории "Премиум")
Общего назначения версии 2 (цен. категория "Стандартный")
Стандартная общего назначения версии 1		 Операции чтения

1С целевой учетной записи взимается плата за одну транзакцию для запуска записи.
2Исходная учетная запись выполняет одну транзакцию для каждого запроса на чтение к исходному объекту.

Дополнительные сведения о ценах на указанные категории выставления счетов см. в разделе Цены на Хранилище BLOB-объектов Azure.

Кроме того, если исходная и целевая учетные записи находятся в разных регионах (например, в северной части США и южной части США), пропускная способность, используемая для передачи запроса, будет взиматься в исходную учетную запись хранения как исходящий трафик. Передача исходящих данных между учетными записями в пределах одного и того же региона осуществляется бесплатно.

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

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

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