Копирование BLOB с асинхронным расписанием с помощью Python

Статья
2025-04-08

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

Методы библиотеки клиента, описанные в этой статье, используют операцию REST API Copy Blob и могут использоваться для копирования с асинхронным планированием. В большинстве сценариев копирования, где вы хотите переместить данные в учетную запись хранения и иметь URL-адрес для исходного объекта, см. Копировать blob из URL-адреса исходного объекта с помощью Python.

Предварительные условия

Подписка Azure — создайте бесплатную учетную запись.
Учетная запись хранения Azure — создайте такую учетную запись.
Python 3.8+

Настройка среды

Если у вас нет существующего проекта, в этом разделе показано, как настроить проект для работы с клиентской библиотекой Хранилище BLOB-объектов Azure для Python. Для получения более подробной информации см. статью "Работа с хранением BLOB-объектов Azure и Python".

Чтобы работать с примерами кода в этой статье, выполните следующие действия, чтобы настроить проект.

Установка пакетов

Установите следующие пакеты с помощью pip install:

pip install azure-storage-blob azure-identity

Добавление инструкций импорта

Добавьте следующие инструкции import :

import datetime
from azure.identity import DefaultAzureCredential
from azure.storage.blob import (
    BlobServiceClient,
    BlobClient,
    BlobLeaseClient,
    BlobSasPermissions,
    generate_blob_sas
)

Авторизация

Механизм авторизации должен иметь необходимые разрешения для выполнения операции копирования или прерывания ожидающей копии. Для авторизации с помощью идентификатора Microsoft Entra (рекомендуется), встроенная роль RBAC Azure RBAC наименее привилегированная зависит от нескольких факторов. Дополнительные сведения см. в руководстве по авторизации для копирования BLOB-объектов (REST API) или прерывания копирования BLOB-объектов (REST API).

Создание клиентского объекта

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

# TODO: Replace <storage-account-name> with your actual storage account name
account_url = "https://<storage-account-name>.blob.core.windows.net"
credential = DefaultAzureCredential()

# Create the BlobServiceClient object
blob_service_client = BlobServiceClient(account_url, credential=credential)

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

О копировании больших двоичных объектов с помощью асинхронного планирования

Операция Copy Blob может завершиться асинхронно и выполняется по мере возможностей, что означает, что ее начало или завершение в течение указанного времени не гарантируется. Операция копирования запланирована в фоновом режиме и выполняется, так как сервер имеет доступные ресурсы. Операция может выполняться синхронно, если копия происходит в той же учетной записи хранения.

Операция Copy Blob может выполнять любое из следующих действий:

Копирование исходного блоба в целевой блоб с другим именем. Целевой большой двоичный объект может быть существующим BLOB-объектом одного типа (блокировать, добавить или страницу) или быть новым BLOB-объектом, созданным операцией копирования.
Скопируйте исходный большой двоичный объект в целевой большой двоичный объект с тем же именем, который заменяет целевой большой двоичный объект. Этот тип операции копирования удаляет все незафиксированные блоки и перезаписывает метаданные целевого BLOB-объекта.
Копирование исходного файла из службы файлов Azure в целевой объект Blob. Целевой BLOB-объект может быть существующим блочным BLOB-объектом или новым блочным BLOB-объектом, созданным операцией копирования. Копирование из файлов в страничные большие двоичные объекты или добавление больших двоичных объектов не поддерживается.
Копирование моментального снимка на его базовый объект данных. Повысив моментальный снимок до уровня базового блоба, вы можете восстановить более раннюю версию блоба.
Скопировать моментальный снимок на целевой блоб с другим именем. Полученный целевой блоб будет доступным для записи и не станет снимком.

Исходный большой двоичный объект для операции копирования может быть одним из следующих типов: блочный большой двоичный объект, добавление большого двоичного объекта, страничный большой двоичный объект, моментальный снимок большого двоичного объекта или версия БОЛЬШОго двоичного объекта. Операция копирования всегда копирует весь исходный большой двоичный объект или файл. Копирование диапазона байтов или набора блоков не поддерживается.

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

Дополнительные сведения об операции, включая сведения о свойствах, тегах индекса, метаданных и выставлении счетов, см. в примечаниях Copy Blobкопирования BLOB-объектов.

Копирование большого двоичного объекта с асинхронным планированием

В этом разделе представлен обзор методов, предоставляемых клиентской библиотекой служба хранилища Azure для Python для выполнения операции копирования с асинхронным планированием.

Следующие методы упаковывают операцию REST API копирования BLOB-объектов и начинают асинхронную копию данных из исходного BLOB-объекта:

начать_копирование_из_URL

Возвращает start_copy_from_url словарь, содержащий copy_status и copy_id. Свойство copy_status это успех, если копия завершена синхронно, или ожидается, если копия была запущена асинхронно.

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

Если вы копируете объект BLOB в той же учетной записи, операция может выполняться синхронно. Доступ к исходному BLOB-объекту можно авторизовать с помощью Microsoft Entra ID, общей подписанной сигнатуры (SAS) или ключа учетной записи. Для альтернативной синхронной операции копирования см. раздел "Копирование BLOB из URL-адреса исходного объекта с помощью Python".

Если источник копирования является блобом в другом аккаунте хранения, операция может выполняться асинхронно. Исходный объект Blob должен быть общедоступным или авторизованным с помощью маркера SAS. Маркер SAS должен включать разрешение на чтение ('r'). Дополнительные сведения о маркерах SAS см. в статье "Делегирование доступа с подписанными URL-адресами".

В следующем примере показан сценарий копирования исходного BLOB-объекта из другой учетной записи хранилища с асинхронным планированием. В этом примере мы создадим URL-адрес исходного BLOB-объекта с добавленным маркером SAS делегирования пользователей. В примере показано, как создать маркер SAS с помощью клиентской библиотеки, но вы также можете предоставить собственные. В примере также показано, как арендовать исходный Блоб во время операции копирования, чтобы предотвратить изменения Блоба от другого клиента. Операция Copy Blob сохраняет значение ETag исходного блоба, когда начинается операция копирования. ETag Если значение изменяется до завершения операции копирования, операция завершается ошибкой.

def copy_from_source_in_azure_async(self, source_blob: BlobClient, destination_blob: BlobClient, blob_service_client: BlobServiceClient):
    # Lease the source blob during copy to prevent other clients from modifying it
    lease = BlobLeaseClient(client=source_blob)

    sas_token = self.generate_user_delegation_sas(blob_service_client=blob_service_client, source_blob=source_blob)
    source_blob_sas_url = source_blob.url + "?" + sas_token

    # Create an infinite lease by passing -1 as the lease duration
    lease.acquire(lease_duration=-1)

    # Start the copy operation - specify False for the requires_sync parameter
    copy_operation = dict()
    copy_operation = destination_blob.start_copy_from_url(source_url=source_blob_sas_url, requires_sync=False)
    
    # If start_copy_from_url returns copy_status of 'pending', the operation has been started asynchronously
    # You can optionally add logic here to wait for the copy operation to complete

    # Release the lease on the source blob
    lease.break_lease()

def generate_user_delegation_sas(self, blob_service_client: BlobServiceClient, source_blob: BlobClient):
    # Get a user delegation key
    delegation_key_start_time = datetime.datetime.now(datetime.timezone.utc)
    delegation_key_expiry_time = delegation_key_start_time + datetime.timedelta(hours=1)
    key = blob_service_client.get_user_delegation_key(
        key_start_time=delegation_key_start_time,
        key_expiry_time=delegation_key_expiry_time
    )

    # Create a SAS token that's valid for one hour, as an example
    sas_token = generate_blob_sas(
        account_name=blob_service_client.account_name,
        container_name=source_blob.container_name,
        blob_name=source_blob.blob_name,
        account_key=None,
        user_delegation_key=key,
        permission=BlobSasPermissions(read=True),
        expiry=datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(hours=1),
        start=datetime.datetime.now(datetime.timezone.utc)
    )

    return sas_token

Примечание.

Маркеры SAS делегирования пользователей обеспечивают более высокую безопасность, так как они подписаны учетными данными Microsoft Entra вместо использования ключа учетной записи. Чтобы создать SAS-токен делегирования пользователей, у участника безопасности Microsoft Entra должны быть необходимые разрешения. Сведения о требованиях к авторизации см. в разделе "Получение ключа делегирования пользователей".

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

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

def copy_from_external_source_async(self, source_url: str, destination_blob: BlobClient):
    # Start the copy operation - specify False for the requires_sync parameter
    copy_operation = dict()
    copy_operation = destination_blob.start_copy_from_url(source_url=source_url, requires_sync=False)
    
    # If start_copy_from_url returns copy_status of 'pending', the operation has been started asynchronously
    # You can optionally add logic here to wait for the copy operation to complete

Проверка состояния операции копирования

Чтобы проверить состояние асинхронной Copy Blob операции, можно провести опрос метода get_blob_properties и проверить состояние копирования.

В следующем примере кода показано, как проверить состояние ожидающей операции копирования:

def check_copy_status(self, destination_blob: BlobClient):
    # Get the copy status from the destination blob properties
    copy_status = destination_blob.get_blob_properties().copy.status

    return copy_status

Прерывание операции копирования

Прерывание ожидающей Copy Blob операции приводит к тому, что целевой объект blob имеет нулевую длину. Однако метаданные для целевого большого двоичного объекта имеют новые значения, скопированные из исходного большого двоичного объекта или явно заданные во время операции копирования. Чтобы сохранить исходные метаданные, существовавшие до копирования, создайте моментальный снимок целевого объекта blob перед вызовом методов копирования.

Чтобы прервать ожидающую операцию копирования, вызовите следующую операцию:

прервать_копирование

Этот метод оборачивает операцию Abort Copy Blob REST API, которая отменяет ожидающую Copy Blob операцию. В следующем примере кода показано, как прервать ожидающую Copy Blob операцию:

def abort_copy(self, destination_blob: BlobClient):
    # Get the copy operation details from the destination blob properties
    copy_status = destination_blob.get_blob_properties().copy.status
    copy_id = destination_blob.get_blob_properties().copy.id

    # Check the copy status and abort if pending
    if copy_status == 'pending':
        destination_blob.abort_copy(copy_id)
        print(f"Copy operation {copy_id} has been aborted")

Ресурсы

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

Примеры кода

Просмотр примеров кода из этой статьи (GitHub)

Операции REST API

Пакет SDK Azure для Python содержит библиотеки, которые создаются на основе REST API Azure, что позволяет взаимодействовать с операциями REST API с помощью знакомых парадигм Python. Методы клиентской библиотеки, описанные в этой статье, используют следующие операции REST API:

Копирование BLOB-объектов (REST API)
Прерывание копирования BLOB-объекта (REST API)

Ресурсы клиентской библиотеки

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