Добавочное копирование BLOB-объекта

Эта Incremental Copy Blob операция копирует моментальный снимок исходного страничного BLOB-объекта в целевой страничный BLOB-объект. В место назначения передаются только отличия от ранее скопированного снимка. Скопированные снимки являются полными копиями исходного снимка, и вы можете читать или копировать из них как обычно. Этот API поддерживается с версии REST 2016-05-31.

Просьба

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

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

URI службы эмулированного хранилища

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

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

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

Параметры URI

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

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

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

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

Заголовок запроса	Описание
`Authorization`	Обязательное. Указывает схему авторизации, имя учетной записи и подпись. Дополнительные сведения см. в статье Авторизация запросов к службе хранилища Azure.
`Date` или `x-ms-date`	Обязательное. Указывает универсальное время (UTC) для запроса. Дополнительные сведения см. в статье Авторизация запросов к службе хранилища Azure.
`x-ms-version`	Требуется для всех авторизованных запросов и необязательных для анонимных запросов. Указывает версию операции, используемой для этого запроса. Дополнительные сведения см. в разделе Управление версиями служб хранилища Azure.
`If-Modified-Since`	Необязательно. Некоторое значение `DateTime`. Укажите этот условный заголовок, чтобы скопировать большой двоичный объект, только если целевой большой двоичный объект был изменен с указанной даты и времени. Если целевой большой двоичный объект не был изменен, хранилище BLOB-объектов возвращает код состояния 412 (сбой предварительных условий).
`If-Unmodified-Since`	Необязательно. Некоторое значение `DateTime`. Укажите этот условный заголовок, чтобы скопировать большой двоичный объект только в том случае, если целевой большой двоичный объект не изменялся с указанной даты и времени. Если целевой большой двоичный объект был изменен, хранилище BLOB-объектов возвращает код состояния 412 (сбой предварительных условий).
`If-Match`	Необязательно. Значение типа `ETag`. Укажите `ETag` значение для этого условного заголовка, чтобы скопировать большой двоичный объект, только если указанное `ETag` значение совпадает со значением `ETag` для существующего целевого BLOB-объекта. `ETag` Если значение для целевого BLOB-объекта не соответствует указанному `ETag` для `If-Match`, хранилище BLOB-объектов возвращает код состояния 412 (сбой предварительного условия).
`If-None-Match`	Необязательно. Значение `ETag` , или подстановочный знак (``). Укажите `ETag` значение для этого условного заголовка, чтобы скопировать большой двоичный объект, только если указанное `ETag` значение не совпадает со значением `ETag` для целевого большого двоичного объекта. Укажите подстановочный знак (``) для выполнения операции, только если целевой большой двоичный объект не существует. Если указанное условие не выполнено, хранилище BLOB-объектов возвращает код состояния 412 (сбой предварительных условий).
`x-ms-copy-source:name`	Обязательное. Указывает имя моментального снимка BLOB-объекта исходной страницы. Это значение представляет собой URL-адрес длиной до 2 кибибайт (КиБ), который указывает моментальный снимок страничного BLOB-объекта. Значение должно быть закодировано URL-адресом, так как оно будет отображаться в URI запроса. URI исходного BLOB-объекта может быть авторизован одним из двух способов: URI исходного BLOB-объекта может ссылаться на моментальный снимок страничного BLOB-объекта, но он должен включать маркер подписанного URL-адреса (SAS), созданный на базовом BLOB-объекте моментального снимка. В поле со знаком resource(`sr`) SAS должно быть установлено значение `b`. Например: `https://<account-name>.blob.core.windows.net/<container-name>/<page-blob-name>?snapshot=2022-07-23T00:14:45.3964054Z&sp=r&st=2022-07-23T00:15:38Z&se=2022-07-23T08:15:38Z&spr=https&sv=2021-06-08&sr=b&sig=<signature>`. URI исходного BLOB-объекта может ссылаться на моментальный снимок BLOB-объекта на общедоступной странице; Например, `https://myaccount.blob.core.windows.net/mycontainer/myblob?snapshot=<DateTime>`.
`x-ms-client-request-id`	Необязательно. Предоставляет созданное клиентом непрозрачное значение с ограничением символов 1-KiB, записанным в журналах при настройке ведения журнала. Настоятельно рекомендуется использовать этот заголовок для сопоставления действий на стороне клиента с запросами, получаемыми сервером. Дополнительные сведения см. в статье Monitorхранилища BLOB-объектов Azure.

Основное содержание запроса

Нет.

Ответ

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

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

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

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

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

Синтаксис	Описание
`ETag`	Содержит значение, которое можно использовать для условного выполнения операций. Стоимость указана в кавычках.
`Last-Modified`	Дата и время последнего изменения объекта BLOB. Дополнительные сведения см. в разделе Представление значений даты и времени в заголовках. Любая операция записи большого двоичного объекта (включая обновление метаданных или свойств большого двоичного объекта) изменяет время последнего изменения большого двоичного объекта.
`x-ms-request-id`	Уникально идентифицирует выполненный запрос и может использоваться для устранения неполадок запроса. Дополнительные сведения см. в операций API устранения неполадок.
`x-ms-version`	Указывает версию хранилища BLOB-объектов, используемую для выполнения запроса.
`Date`	Значение даты и времени в формате UTC, указывающее время, в течение которого был инициирован ответ. Служба создает это значение.
`x-ms-copy-id: <id>`	Строковый идентификатор для этой операции копирования. Используйте with `Get Blob Properties` для проверки состояния этой операции копирования или pass to `Abort Copy Blob` для остановки ожидающей копии.
`x-ms-copy-status: pending`	Состояние операции копирования. Это всегда ожидает, чтобы указать, что копирование началось и выполняется.
`x-ms-client-request-id`	Можно использовать для устранения неполадок запросов и соответствующих ответов. Значение этого заголовка равно значению заголовка `x-ms-client-request-id`, если он присутствует в запросе. Значение не более 1024 видимых символов ASCII. Если в запросе отсутствует заголовок `x-ms-client-request-id`, он не будет присутствовать в ответе.

Основная часть ответа

Нет.

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

Ниже приведен пример ответа на запрос на выполнение добавочного копирования:

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: 2016-05-31
x-ms-copy-id: 1f812371-a41d-49e6-b123-f4b542e851c5
x-ms-copy-status: pending
Date: <date>

Авторизация

Авторизация требуется при вызове любой операции доступа к данным в службе хранилища Azure. В следующем разделе описывается, как можно авторизовать целевой объект для Incremental Copy Blob операции. Доступ к исходному большому двоичному объекту или файлу разрешается отдельно, как описано в сведениях для x-ms-copy-source заголовка запроса.

Это важно

Корпорация Майкрософт рекомендует использовать идентификатор Microsoft Entra с управляемыми удостоверениями для авторизации запросов в службу хранилища Azure. Идентификатор Microsoft Entra обеспечивает более высокую безопасность и удобство использования по сравнению с авторизацией общего ключа.

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

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

Разрешения

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

Действие Azure RBAC:Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write (для записи в существующий BLOB-объект) или Microsoft.Storage/storageAccounts/blobServices/containers/blobs/add/action (для записи нового BLOB-объекта в место назначения)
встроенная роль с минимальными привилегиями:участник данных BLOB-объектов хранилища

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

Подписанный URL-адрес (SAS) обеспечивает безопасный делегированный доступ к ресурсам в учетной записи хранения. С помощью SAS у вас есть детальный контроль над доступом клиента к данным. Вы можете указать, к каким ресурсам клиент может получить доступ, какие разрешения они имеют к этим ресурсам, а также срок действия SAS.

Операция поддерживает три типа подписанных URL-адресов: sas делегирования пользователей, SASслужбыслужбы и SAS учетной записи SASучетной записи.

Рекомендуется использовать учетные данные Microsoft Entra, а не ключ учетной записи хранения, который может быть проще скомпрометирован. Если для разработки приложения требуются подписанные URL-адреса, используйте учетные данные Microsoft Entra для создания SAS делегирования пользователей по возможности.

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

Делегирование пользователей с помощью SAS

SAS на основе делегирования пользователя защищен учетными данными Microsoft Entra ID, а также разрешениями, указанными для SAS.

Для вызова Incremental Copy Blob операции с помощью маркера SAS, делегированного ресурсу BLOB-объекта, требуется следующее разрешение в рамках делегирования пользователю маркера SAS.

Операция	Тип объекта	Подписанное разрешение
Добавочное копирование BLOB-объекта	Целевой BLOB-объект (новый)	Создание (c) или запись (w)
Добавочное копирование BLOB-объекта	Целевой большой двоичный объект (существующий)	Запись (w)

Дополнительные сведения о SAS делегирования пользователей см. в статье Создание SAS делегирования пользователей.

Сервис SAS

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

Для вызова Incremental Copy Blob операции с помощью маркера SAS, делегированного ресурсу BLOB-объекта, требуется следующее разрешение в составе маркера службы SAS.

Операция	Тип объекта	Подписанное разрешение
Добавочное копирование BLOB-объекта	Целевой BLOB-объект (новый)	Создание (c) или запись (w)
Добавочное копирование BLOB-объекта	Целевой большой двоичный объект (существующий)	Запись (w)

Дополнительные сведения о SAS службы см. в статье Создание SAS службы.

SAS для учетной записи

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

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

Операция	Тип объекта	Подписанная служба	Подписанный тип ресурса	Подписанное разрешение
Добавочное копирование BLOB-объекта	Целевой BLOB-объект (новый)	Большой двоичный объект (b)	Объект (o)	Создание (c) или запись (w)
Добавочное копирование BLOB-объекта	Целевой большой двоичный объект (существующий)	Большой двоичный объект (b)	Объект (o)	Запись (w)

Дополнительные сведения о SAS учетной записи см. в статье Создание SAS учетной записи.

Замечания

Назначение добавочной копии не должно существовать или должно быть создано с помощью предыдущей добавочной копии из того же исходного большого двоичного объекта. После его создания целевой BLOB-объект навсегда связан с источником и может использоваться только для добавочных копий. API Get Blob Properties и List Blobs указывают, является ли большой двоичный объект добавочной копией, созданным таким образом.

Вы не можете напрямую скачивать добавочные копии больших двоичных объектов. Единственными поддерживаемыми операциями являются Get Blob Properties, Incremental Copy Blob, и Delete Blob. Вы можете читать и удалять скопированные снимки как обычно.

Добавочное копирование выполняется в службе асинхронно, и необходимо провести опрос на предмет завершения. Обратитесь к Copy Blob API для получения подробной информации о том, как опрашивать ожидающую копию. Когда копирование будет завершено, целевой BLOB-объект будет содержать новый моментальный снимок. API Get Blob Properties возвращает время создания снимка только что созданного снимка.

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

Разностные изменения вычисляются на сервере путем вызова Get Page Ranges исходного моментального снимка BLOB-объекта. Установите prevsnapshot значение для последнего скопированного снимка. Следовательно, те же ограничения распространяются Get Page Ranges и на Incremental Copy Blobдомен . В частности, необходимо копировать моментальные снимки в порядке возрастания, и если исходный большой двоичный объект будет повторно создан с помощью Put Blob или Copy Blob, то Incremental Copy Blob при создании новых моментальных снимков произойдет сбой.

Дополнительное дисковое пространство, занимаемое копируемым моментальным снимком, — это размер разностных данных, передаваемых во время копирования. Этот размер можно определить, выполнив дифференциальный Get Page Ranges вызов API для моментального снимка, чтобы сравнить его с предыдущим снимком.

См. также

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

Last updated on 2025-06-12