Sdílet prostřednictvím

Kopírování objektu blob s asynchronním plánováním pomocí Pythonu

  • Článek

Tento článek ukazuje, jak zkopírovat objekt blob s asynchronním plánováním pomocí klientské knihovny Azure Storage pro Python. Objekt blob můžete zkopírovat ze zdroje ve stejném účtu úložiště, ze zdroje v jiném účtu úložiště nebo z libovolného přístupného objektu načteného prostřednictvím požadavku HTTP GET na dané adrese URL. Můžete také přerušit čekající operaci kopírování.

Metody klientské knihovny popsané v tomto článku používají operaci copy blob REST API a lze ji použít, když chcete provést kopírování s asynchronním plánováním. Ve většině scénářů kopírování, ve kterých chcete přesunout data do účtu úložiště a mít adresu URL zdrojového objektu, najdete v tématu Kopírování objektu blob z adresy URL zdrojového objektu pomocí Pythonu.

Požadavky

Nastavení prostředí

Pokud nemáte existující projekt, v této části se dozvíte, jak nastavit projekt pro práci s klientskou knihovnou Azure Blob Storage pro Python. Další podrobnosti najdete v tématu Začínáme se službou Azure Blob Storage a Pythonem.

Pokud chcete pracovat s příklady kódu v tomto článku, nastavte projekt pomocí následujícího postupu.

Instalace balíčků

Nainstalujte následující balíčky pomocí pip install:

pip install azure-storage-blob azure-identity

Přidání příkazů importu

Přidejte následující příkazy import:

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

Autorizace

Autorizační mechanismus musí mít potřebná oprávnění k provedení operace kopírování nebo k přerušení čekající kopie. Pro autorizaci pomocí Microsoft Entra ID (doporučeno) se nejméně privilegovaná předdefinovaná role Azure RBAC liší v závislosti na několika faktorech. Další informace najdete v pokynech k autorizaci pro kopírování objektů blob (REST API) nebo přerušení kopírování objektu blob (REST API).

Vytvoření objektu klienta

Pokud chcete připojit aplikaci ke službě Blob Storage, vytvořte instanci BlobServiceClient. Následující příklad ukazuje, jak vytvořit objekt klienta pro DefaultAzureCredential autorizaci:

# 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)

Můžete také vytvořit klientské objekty pro konkrétní kontejnery nebo objekty blob, a to buď přímo, nebo z objektu BlobServiceClient . Další informace o vytváření a správě klientských objektů najdete v tématu Vytváření a správa klientských objektů, které pracují s datovými prostředky.

Kopírování objektů blob pomocí asynchronního plánování

Operace Copy Blob se může dokončit asynchronně a provádí se na základě maximálního úsilí, což znamená, že není zaručeno, že se operace spustí okamžitě nebo dokončí v zadaném časovém rámci. Operace kopírování se naplánuje na pozadí a provede se tak, jak má server dostupné prostředky. Operace může být dokončena synchronně, pokud se kopie vyskytuje ve stejném účtu úložiště.

Copy Blob Operace může provádět některou z následujících akcí:

  • Zkopírujte zdrojový objekt blob do cílového objektu blob s jiným názvem. Cílovým objektem blob může být existující objekt blob stejného typu objektu blob (blok, připojení nebo stránka), nebo může být novým objektem blob vytvořeným operací kopírování.
  • Zkopírujte zdrojový objekt blob do cílového objektu blob se stejným názvem, který nahradí cílový objekt blob. Tento typ operace kopírování odebere všechny nepotvrzené bloky a přepíše metadata cílového objektu blob.
  • Zkopírujte zdrojový soubor ve službě Azure File Service do cílového objektu blob. Cílovým objektem blob může být existující objekt blob bloku nebo může být nový objekt blob bloku vytvořený operací kopírování. Kopírování ze souborů do objektů blob stránky nebo doplňovacích objektů blob se nepodporuje.
  • Zkopírujte snímek nad jeho základní objekt blob. Zvýšením úrovně snímku na pozici základního objektu blob můžete obnovit starší verzi objektu blob.
  • Zkopírujte snímek do cílového objektu blob s jiným názvem. Výsledný cílový objekt blob je zapisovatelný objekt blob, nikoli snímek.

Zdrojový objekt blob operace kopírování může být jedním z následujících typů: objekt blob bloku, doplňovací objekt blob, objekt blob stránky, snímek objektu blob nebo verze objektu blob. Operace kopírování vždy kopíruje celý zdrojový objekt blob nebo soubor. Kopírování rozsahu bajtů nebo sady bloků se nepodporuje.

Pokud cílový objekt blob již existuje, musí mít stejný typ objektu blob jako zdrojový objekt blob a existující cílový objekt blob se přepíše. Cílový objekt blob nelze upravit, když probíhá operace kopírování a cílový objekt blob může mít pouze jednu nevyřešenou operaci kopírování.

Další informace o Copy Blob operaci, včetně informací o vlastnostech, značkách indexu, metadatech a fakturaci, najdete v tématu Kopírování poznámek k objektům blob.

Kopírování objektu blob s asynchronním plánováním

Tato část obsahuje přehled metod poskytovaných klientskou knihovnou azure Storage pro Python k provedení operace kopírování s asynchronním plánováním.

Následující metody zabalí operaci copy blob REST API a spustí asynchronní kopii dat ze zdrojového objektu blob:

Vrátí start_copy_from_url slovník obsahující copy_status a copy_id. Vlastnost copy_status je úspěšná , pokud se kopie dokončila synchronně nebo čeká na vyřízení , pokud byla kopie spuštěna asynchronně.

Kopírování objektu blob ze zdroje v Azure

Pokud kopírujete objekt blob ve stejném účtu úložiště, operace se může dokončit synchronně. Přístup ke zdrojovému objektu blob je možné autorizovat prostřednictvím ID Microsoft Entra, sdíleného přístupového podpisu (SAS) nebo klíče účtu. Informace o operaci alterativní synchronní kopírování najdete v tématu Kopírování objektu blob ze zdrojové adresy URL objektu pomocí Pythonu.

Pokud je zdrojem kopírování objekt blob v jiném účtu úložiště, může operace asynchronně dokončit. Zdrojový objekt blob musí být veřejný nebo autorizovaný prostřednictvím tokenu SAS. Token SAS musí obsahovat oprávnění ke čtení ('r' ). Další informace o tokenech SAS najdete v tématu Delegování přístupu pomocí sdílených přístupových podpisů.

Následující příklad ukazuje scénář kopírování zdrojového objektu blob z jiného účtu úložiště s asynchronním plánováním. V tomto příkladu vytvoříme adresu URL zdrojového objektu blob s připojeným tokenem SAS delegování uživatele. Příklad ukazuje, jak vygenerovat token SAS pomocí klientské knihovny, ale můžete také zadat vlastní. Příklad také ukazuje, jak zapůjčení zdrojového objektu blob během operace kopírování, aby se zabránilo změnám objektu blob z jiného klienta. Operace Copy Blob uloží ETag hodnotu zdrojového objektu blob při spuštění operace kopírování. ETag Pokud se hodnota změní před dokončením operace kopírování, operace selže.

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

Poznámka:

Tokeny SAS delegování uživatelů nabízejí větší zabezpečení, protože jsou podepsané pomocí přihlašovacích údajů Microsoft Entra místo klíče účtu. K vytvoření tokenu SAS delegování uživatele potřebuje objekt zabezpečení Microsoft Entra příslušná oprávnění. Požadavky na autorizaci najdete v tématu Získání klíče delegování uživatele.

Kopírování objektu blob ze zdroje mimo Azure

Operaci kopírování můžete provést u libovolného zdrojového objektu, který lze načíst prostřednictvím požadavku HTTP GET na danou adresu URL, včetně přístupných objektů mimo Azure. Následující příklad ukazuje scénář kopírování objektu blob z adresy URL přístupného zdrojového objektu.

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

Kontrola stavu operace kopírování

Pokud chcete zkontrolovat stav asynchronní Copy Blob operace, můžete dotazovat metodu get_blob_properties a zkontrolovat stav kopírování.

Následující příklad kódu ukazuje, jak zkontrolovat stav čekající operace kopírování:

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

Přerušení operace kopírování

Přerušení čekající Copy Blob operace způsobí, že cílový objekt blob má nulovou délku. Metadata cílového objektu blob ale mají nové hodnoty zkopírované ze zdrojového objektu blob nebo explicitně nastavené během operace kopírování. Chcete-li zachovat původní metadata před kopií, vytvořte snímek cílového objektu blob před voláním jedné z metod kopírování.

Chcete-li přerušit čekající operaci kopírování, zavolejte následující operaci:

Tato metoda zabalí operaci Abort Copy Blob REST API, která zruší čekající Copy Blob operaci. Následující příklad kódu ukazuje, jak přerušit čekající Copy Blob operaci:

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")

Zdroje informací

Další informace o kopírování objektů blob s asynchronním plánováním pomocí klientské knihovny služby Azure Blob Storage pro Python najdete v následujících zdrojích informací.

Ukázky kódu

Operace rozhraní REST API

Sada Azure SDK pro Python obsahuje knihovny, které jsou postavené na rozhraní Azure REST API a umožňují interakci s operacemi rozhraní REST API prostřednictvím známých paradigmat Pythonu. Metody klientské knihovny popsané v tomto článku používají následující operace rozhraní REST API:

Prostředky klientské knihovny

Související obsah

  • Tento článek je součástí příručky pro vývojáře služby Blob Storage pro Python. Další informace najdete v úplném seznamu článků příručky pro vývojáře na webu Sestavení aplikace v Pythonu.