Udostępnij za pośrednictwem

Kopiowanie obiektu blob z planowaniem asynchronicznym przy użyciu języka Python

  • Artykuł

W tym artykule pokazano, jak skopiować obiekt blob z planowaniem asynchronicznym przy użyciu biblioteki klienta usługi Azure Storage dla języka Python. Obiekt blob można skopiować ze źródła na tym samym koncie magazynu, ze źródła na innym koncie magazynu lub z dowolnego dostępnego obiektu pobranego za pośrednictwem żądania HTTP GET dla danego adresu URL. Możesz również przerwać oczekującą operację kopiowania.

Metody biblioteki klienta omówione w tym artykule korzystają z operacji kopiowania interfejsu API REST obiektów blob i mogą być używane, gdy chcesz wykonać kopię za pomocą planowania asynchronicznego. W przypadku większości scenariuszy kopiowania, w których chcesz przenieść dane na konto magazynu i mieć adres URL obiektu źródłowego, zobacz Kopiowanie obiektu blob z adresu URL obiektu źródłowego przy użyciu języka Python.

Wymagania wstępne

Konfigurowanie środowiska

Jeśli nie masz istniejącego projektu, w tej sekcji pokazano, jak skonfigurować projekt do pracy z biblioteką klienta usługi Azure Blob Storage dla języka Python. Aby uzyskać więcej informacji, zobacz Rozpoczynanie pracy z usługami Azure Blob Storage i Python.

Aby pracować z przykładami kodu w tym artykule, wykonaj następujące kroki, aby skonfigurować projekt.

Instalowanie pakietów

Zainstaluj następujące pakiety przy użyciu polecenia pip install:

pip install azure-storage-blob azure-identity

Dodawanie instrukcji importu

Dodaj następujące instrukcje import:

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

Autoryzacja

Mechanizm autoryzacji musi mieć uprawnienia niezbędne do wykonania operacji kopiowania lub przerwania oczekującej kopii. W przypadku autoryzacji przy użyciu identyfikatora Entra firmy Microsoft (zalecane) najmniej uprzywilejowana rola wbudowana RBAC platformy Azure różni się w zależności od kilku czynników. Aby dowiedzieć się więcej, zobacz wskazówki autoryzacji dotyczące kopiowania obiektów blob (interfejs API REST) lub Abort Copy Blob (INTERFEJS API REST) .

Tworzenie obiektu klienta

Aby połączyć aplikację z usługą Blob Storage, utwórz wystąpienie klasy BlobServiceClient. W poniższym przykładzie pokazano, jak utworzyć obiekt klienta przy użyciu DefaultAzureCredential autoryzacji:

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

Można również tworzyć obiekty klienta dla określonych kontenerów lub obiektów blob bezpośrednio lub z BlobServiceClient obiektu. Aby dowiedzieć się więcej na temat tworzenia obiektów klienta i zarządzania nimi, zobacz Tworzenie obiektów klienta korzystających z zasobów danych i zarządzanie nimi.

Informacje o kopiowaniu obiektów blob za pomocą planowania asynchronicznego

Operacja Copy Blob może zakończyć się asynchronicznie i jest wykonywana na podstawie najlepszego nakładu pracy, co oznacza, że operacja nie gwarantuje natychmiastowego uruchomienia ani ukończenia w określonym przedziale czasu. Operacja kopiowania jest zaplanowana w tle i wykonywana jako serwer ma dostępne zasoby. Operacja może zakończyć się synchronicznie, jeśli kopia występuje na tym samym koncie magazynu.

Operacja Copy Blob może wykonać dowolną z następujących akcji:

  • Skopiuj źródłowy obiekt blob do docelowego obiektu blob o innej nazwie. Docelowy obiekt blob może być istniejącym obiektem blob tego samego typu obiektu blob (blok, dołączanie lub strona) albo może być nowym obiektem blob utworzonym przez operację kopiowania.
  • Skopiuj źródłowy obiekt blob do docelowego obiektu blob o takiej samej nazwie, który zastępuje docelowy obiekt blob. Ten typ operacji kopiowania usuwa wszystkie niezatwierdzone bloki i zastępuje metadane docelowego obiektu blob.
  • Skopiuj plik źródłowy w usłudze Azure File do docelowego obiektu blob. Docelowy obiekt blob może być istniejącym blokowym obiektem blob lub może być nowym blokowym obiektem blob utworzonym przez operację kopiowania. Kopiowanie z plików do stronicowych obiektów blob lub uzupełnialnych obiektów blob nie jest obsługiwane.
  • Skopiuj migawkę na podstawowy obiekt blob. Promując migawkę do pozycji podstawowego obiektu blob, można przywrócić starszą wersję obiektu blob.
  • Skopiuj migawkę do docelowego obiektu blob o innej nazwie. Wynikowy docelowy obiekt blob jest zapisywalnym obiektem blob, a nie migawką.

Źródłowy obiekt blob operacji kopiowania może być jednym z następujących typów: blokowy obiekt blob, uzupełnialne obiekty blob, stronicowy obiekt blob, migawka obiektu blob lub wersja obiektu blob. Operacja kopiowania zawsze kopiuje cały źródłowy obiekt blob lub plik. Kopiowanie zakresu bajtów lub zestawu bloków nie jest obsługiwane.

Jeśli docelowy obiekt blob już istnieje, musi mieć ten sam typ obiektu blob co źródłowy obiekt blob, a istniejący docelowy obiekt blob zostanie zastąpiony. Nie można zmodyfikować docelowego obiektu blob, gdy operacja kopiowania jest w toku, a docelowy obiekt blob może mieć tylko jedną zaległą operację kopiowania.

Aby dowiedzieć się więcej o Copy Blob operacji, w tym o właściwościach, tagach indeksu, metadanych i rozliczeniach, zobacz Kopiowanie uwag dotyczących obiektu blob.

Kopiowanie obiektu blob za pomocą planowania asynchronicznego

Ta sekcja zawiera omówienie metod udostępnianych przez bibliotekę klienta usługi Azure Storage dla języka Python w celu wykonania operacji kopiowania przy użyciu planowania asynchronicznego.

Następujące metody opakowuje operację interfejsu API REST kopiowania obiektów blob i rozpoczynają asynchroniczną kopię danych ze źródłowego obiektu blob:

Zwraca start_copy_from_url słownik zawierający copy_status i copy_id. Właściwość copy_status kończy się powodzeniem, jeśli kopia została ukończona synchronicznie lub oczekuje, jeśli kopia została uruchomiona asynchronicznie.

Kopiowanie obiektu blob ze źródła na platformie Azure

Jeśli kopiujesz obiekt blob na tym samym koncie magazynu, operacja może zakończyć się synchronicznie. Dostęp do źródłowego obiektu blob można autoryzować za pośrednictwem identyfikatora Firmy Microsoft, sygnatury dostępu współdzielonego (SAS) lub klucza konta. Aby uzyskać informacje na temat operacji kopiowania synchronicznego, zobacz Kopiowanie obiektu blob z adresu URL obiektu źródłowego przy użyciu języka Python.

Jeśli źródło kopiowania jest obiektem blob na innym koncie magazynu, operacja może zakończyć się asynchronicznie. Źródłowy obiekt blob musi być publiczny lub autoryzowany za pośrednictwem tokenu SAS. Token SAS musi zawierać uprawnienie Odczyt ('r'). Aby dowiedzieć się więcej na temat tokenów SAS, zobacz Delegowanie dostępu za pomocą sygnatur dostępu współdzielonego.

Poniższy przykład przedstawia scenariusz kopiowania źródłowego obiektu blob z innego konta magazynu z asynchronicznym planowaniem. W tym przykładzie utworzymy źródłowy adres URL obiektu blob z dołączonym tokenem SAS delegowania użytkownika. W przykładzie pokazano, jak wygenerować token SAS przy użyciu biblioteki klienta, ale możesz również podać własne. W przykładzie pokazano również, jak dzierżawić źródłowy obiekt blob podczas operacji kopiowania, aby zapobiec zmianom obiektu blob z innego klienta. Operacja Copy Blob zapisuje ETag wartość źródłowego obiektu blob po uruchomieniu operacji kopiowania. Jeśli wartość zostanie zmieniona ETag przed zakończeniem operacji kopiowania, operacja zakończy się niepowodzeniem.

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

Uwaga

Tokeny SAS delegowania użytkownika zapewniają większe bezpieczeństwo, ponieważ są podpisane przy użyciu poświadczeń firmy Microsoft Entra zamiast klucza konta. Aby utworzyć token SAS delegowania użytkownika, podmiot zabezpieczeń firmy Microsoft entra potrzebuje odpowiednich uprawnień. Aby uzyskać wymagania dotyczące autoryzacji, zobacz Pobieranie klucza delegowania użytkownika.

Kopiowanie obiektu blob ze źródła spoza platformy Azure

Operację kopiowania można wykonać na dowolnym obiekcie źródłowym, który można pobrać za pośrednictwem żądania HTTP GET dla danego adresu URL, w tym obiektów dostępnych poza platformą Azure. Poniższy przykład przedstawia scenariusz kopiowania obiektu blob z dostępnego adresu URL obiektu źródłowego.

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

Sprawdzanie stanu operacji kopiowania

Aby sprawdzić stan operacji asynchronicznej Copy Blob , możesz sondować metodę get_blob_properties i sprawdzić stan kopiowania.

W poniższym przykładzie kodu pokazano, jak sprawdzić stan oczekującej operacji kopiowania:

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

Przerywanie operacji kopiowania

Przerwanie oczekującej Copy Blob operacji powoduje utworzenie docelowego obiektu blob o zerowej długości. Jednak metadane docelowego obiektu blob mają nowe wartości skopiowane ze źródłowego obiektu blob lub ustawione jawnie podczas operacji kopiowania. Aby zachować oryginalne metadane przed kopią, przed wywołaniem jednej z metod kopiowania utwórz migawkę docelowego obiektu blob.

Aby przerwać oczekującą operację kopiowania, wywołaj następującą operację:

Ta metoda opakowuje operację interfejsu API REST kopiowania obiektu blob abort, która anuluje oczekującą Copy Blob operację. Poniższy przykład kodu pokazuje, jak przerwać oczekującą Copy Blob operację:

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

Zasoby

Aby dowiedzieć się więcej na temat kopiowania obiektów blob za pomocą planowania asynchronicznego przy użyciu biblioteki klienta usługi Azure Blob Storage dla języka Python, zobacz następujące zasoby.

Przykłady kodu

Operacje interfejsu API REST

Zestaw Azure SDK dla języka Python zawiera biblioteki, które bazują na interfejsie API REST platformy Azure, umożliwiając interakcję z operacjami interfejsu API REST za pomocą znanych paradygmatów języka Python. Metody biblioteki klienta opisane w tym artykule korzystają z następujących operacji interfejsu API REST:

Zasoby biblioteki klienta

Powiązana zawartość

  • Ten artykuł jest częścią przewodnika dla deweloperów usługi Blob Storage dla języka Python. Aby dowiedzieć się więcej, zobacz pełną listę artykułów z przewodnika dla deweloperów w temacie Tworzenie aplikacji w języku Python.