Udostępnij za pomocą

Przekazywanie blokowego obiektu blob przy użyciu języka Python

W tym artykule pokazano, jak przesłać obiekt blob przy użyciu biblioteki klienta Azure Storage dla Pythona. Można przesyłać dane do blobu blokowego ze ścieżki pliku, strumienia, obiektu binarnego lub ciągu tekstowego. Można również przekazywać obiekty blob za pomocą tagów indeksu.

Aby dowiedzieć się więcej na temat przekazywania obiektów blob przy użyciu asynchronicznych interfejsów API, zobacz Asynchroniczne przekazywanie obiektów blob.

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

Dodaj instrukcje importu

Dodaj następujące import wyrażenia:

import io
import os
import uuid
from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient, ContainerClient, BlobBlock, BlobClient, StandardBlobTier

Autoryzacja

Mechanizm autoryzacji musi mieć niezbędne uprawnienia do załadowania bloba. Aby uzyskać autoryzację przy użyciu Microsoft Entra ID (zalecane), potrzebujesz wbudowanej roli Azure RBAC o nazwie Storage Blob Data Contributor lub wyższej. Aby dowiedzieć się więcej, zobacz wskazówki dotyczące autoryzacji dla funkcji Put Blob (interfejs API REST) i Put Block (interfejs API REST).

Tworzenie obiektu klienta

Aby połączyć aplikację z usługą Blob Storage, utwórz wystąpienie 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 za pomocą obiektu BlobServiceClient. 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.

Prześlij dane do blokowego bloba

Aby przekazać obiekt blob przy użyciu strumienia lub obiektu binarnego, użyj następującej metody:

Ta metoda tworzy nowy blob ze źródła danych z automatycznym fragmentowaniem, co oznacza, że źródło danych może zostać podzielone na mniejsze fragmenty i przesłane. Aby przeprowadzić przesyłanie, biblioteka kliencka może używać funkcji Put Blob lub serii wywołań funkcji Put Block, a następnie wywołać funkcję Put Block List. To zachowanie zależy od ogólnego rozmiaru obiektu i sposobu ustawiania opcji transferu danych.

Uwaga

Biblioteki klienckie Azure Storage nie obsługują równoczesnego zapisu do tego samego obiektu blob. Jeśli Twoja aplikacja wymaga wielu procesów zapisujących do tego samego obiektu blob, należy zaimplementować strategię kontroli współbieżności, aby zapewnić przewidywalne doświadczenie. Aby dowiedzieć się więcej na temat strategii współbieżności, zobacz Zarządzanie współbieżnością w usłudze Blob Storage.

Przekazywanie obiektu blob w postaci bloku ze ścieżki pliku lokalnego

Przykład poniżej przesyła plik do bloba blokowego przy użyciu obiektu BlobClient.

def upload_blob_file(self, blob_service_client: BlobServiceClient, container_name: str):
    container_client = blob_service_client.get_container_client(container=container_name)
    with open(file=os.path.join('filepath', 'filename'), mode="rb") as data:
        blob_client = container_client.upload_blob(name="sample-blob.txt", data=data, overwrite=True)

Prześlij blok typu blob ze strumienia

Poniższy przykład tworzy losowe dane bajtowe i przesyła BytesIO obiekt do blokowego obiektu typu blob przy użyciu obiektu BlobClient.

def upload_blob_stream(self, blob_service_client: BlobServiceClient, container_name: str):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")
    input_stream = io.BytesIO(os.urandom(15))
    blob_client.upload_blob(input_stream, blob_type="BlockBlob")

Przekazywanie danych binarnych do blokowego blobu

W poniższym przykładzie przesyłanie danych binarnych do obiektu typu block blob odbywa się za pomocą obiektu BlobClient.

def upload_blob_data(self, blob_service_client: BlobServiceClient, container_name: str):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")
    data = b"Sample data for blob"

    # Upload the blob data - default blob type is BlockBlob
    blob_client.upload_blob(data, blob_type="BlockBlob")

Przesyłanie obiektu typu block blob z tagami indeksu

Poniższy przykład wysyła obiekt blob typu blokowego z tagami indeksu:

def upload_blob_tags(self, blob_service_client: BlobServiceClient, container_name: str):
    container_client = blob_service_client.get_container_client(container=container_name)
    sample_tags = {"Content": "image", "Date": "2022-01-01"}
    with open(file=os.path.join('filepath', 'filename'), mode="rb") as data:
        blob_client = container_client.upload_blob(name="sample-blob.txt", data=data, tags=sample_tags)

Prześlij obiekt blokowy blob przy użyciu opcji konfiguracji

Opcje konfiguracji biblioteki klienta można zdefiniować podczas przekazywania danego obiektu. Te opcje można dostosować, aby zwiększyć wydajność, zwiększyć niezawodność i zoptymalizować koszty. W poniższych przykładach kodu pokazano, jak zdefiniować opcje konfiguracji przesyłania zarówno na poziomie metody, jak i na poziomie klienta podczas inicjalizacji BlobClient. Te opcje można również skonfigurować dla instancji ContainerClient lub BlobServiceClient.

Określ opcje transferu danych do przesłania

Można ustawić opcje konfiguracji podczas tworzenia instancji klienta w celu optymalizacji wydajności operacji transferu danych. Podczas konstruowania obiektu klienta w języku Python można przekazać następujące argumenty słowa kluczowego:

  • max_block_size - Maksymalny rozmiar fragmentu do przesyłania blokowego obiektu blob w częściach. Wartość domyślna to 4 MiB.
  • max_single_put_size — Jeśli rozmiar obiektu blob jest mniejszy lub równy max_single_put_size, obiekt blob jest przekazywany z pojedynczym Put Blob żądaniem. Jeśli rozmiar obiektu blob jest większy niż max_single_put_size lub nieznany, obiekt blob jest przekazywany we fragmentach przy użyciu Put Block i zatwierdzany za pomocą Put Block List. Wartość domyślna to 64 MiB.

Aby uzyskać więcej informacji na temat limitów rozmiaru transferu dla usługi Blob Storage, zobacz Skalowanie obiektów docelowych dla usługi Blob Storage.

Podczas operacji przesyłania można również przekazać max_concurrency argument podczas wywoływania upload_blob. Ten argument definiuje maksymalną liczbę połączeń równoległych do użycia, gdy rozmiar obiektu blob przekracza 64 MiB.

Poniższy przykład kodu przedstawia sposób określania opcji transferu danych podczas tworzenia BlobClient obiektu oraz sposobu przekazywania danych przy użyciu tego obiektu klienta. Wartości podane w tym przykładzie nie są przeznaczone do zalecenia. Aby prawidłowo dostosować te wartości, należy wziąć pod uwagę konkretne potrzeby aplikacji.

def upload_blob_transfer_options(self, account_url: str, container_name: str, blob_name: str):
    # Create a BlobClient object with data transfer options for upload
    blob_client = BlobClient(
        account_url=account_url, 
        container_name=container_name, 
        blob_name=blob_name,
        credential=DefaultAzureCredential(),
        max_block_size=1024*1024*4, # 4 MiB
        max_single_put_size=1024*1024*8 # 8 MiB
    )
    
    with open(file=os.path.join(r'file_path', blob_name), mode="rb") as data:
        blob_client = blob_client.upload_blob(data=data, overwrite=True, max_concurrency=2)

Aby dowiedzieć się więcej na temat dostrajania opcji transferu danych, zobacz Dostosowywanie wydajności przekazywania i pobierania za pomocą języka Python.

Ustaw warstwę dostępu obiektu blob podczas przesyłania

Warstwę dostępu obiektu blob można ustawić podczas przesyłania, podając argument słowa kluczowego standard_blob_tier do funkcji upload_blob. Usługa Azure Storage oferuje różne warstwy dostępu, dzięki czemu można przechowywać dane obiektów blob w najbardziej ekonomiczny sposób na podstawie sposobu ich użycia.

W poniższym przykładzie kodu pokazano, jak ustawić warstwę dostępu podczas ładowania obiektu blob.

def upload_blob_access_tier(self, blob_service_client: BlobServiceClient, container_name: str, blob_name: str):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob=blob_name)
    
    #Upload blob to the cool tier
    with open(file=os.path.join(r'file_path', blob_name), mode="rb") as data:
        blob_client = blob_client.upload_blob(data=data, overwrite=True, standard_blob_tier=StandardBlobTier.COOL)

Ustawienie warstwy dostępu jest dozwolone tylko dla obiektów blob typu blok. Warstwę dostępu dla bloba blokowego można ustawić na Hot, Cool, Cold lub Archive. Aby ustawić warstwę dostępu na Cold, należy użyć minimalnej wersji biblioteki klienta 12.15.0.

Aby dowiedzieć się więcej na temat warstw dostępu, zobacz Omówienie warstw dostępu.

Przekazywanie blokowego bloba poprzez etapowanie bloków i ich zatwierdzanie

Możesz mieć większą kontrolę nad sposobem dzielenia przesyłanych danych na bloki przez ręczne etapowanie poszczególnych bloków danych. Gdy wszystkie bloki tworzące obiekt typu blob są przygotowane, można je zatwierdzić w usłudze Blob Storage.

Użyj następującej metody, aby utworzyć nowy blok, który ma zostać zatwierdzony w ramach obiektu blob:

Użyj następującej metody, aby utworzyć obiekt blob, określając listę identyfikatorów bloków, które składają się na obiekt blob:

Poniższy przykład odczytuje dane z pliku i przygotowuje bloki, które będą częścią obiektu blob:

def upload_blocks(self, blob_container_client: ContainerClient, local_file_path: str, block_size: int):
    file_name = os.path.basename(local_file_path)
    blob_client = blob_container_client.get_blob_client(file_name)

    with open(file=local_file_path, mode="rb") as file_stream:
        block_id_list = []

        while True:
            buffer = file_stream.read(block_size)
            if not buffer:
                break

            block_id = uuid.uuid4().hex
            block_id_list.append(BlobBlock(block_id=block_id))

            blob_client.stage_block(block_id=block_id, data=buffer, length=len(buffer))

        blob_client.commit_block_list(block_id_list)

Asynchroniczne przesyłanie blobów

Biblioteka klienta usługi Azure Blob Storage dla języka Python obsługuje asynchroniczne przekazywanie obiektów blob. Aby dowiedzieć się więcej na temat wymagań dotyczących konfiguracji projektu, zobacz Programowanie asynchroniczne.

Wykonaj następujące kroki, aby przesłać obiekt blob przy użyciu asynchronicznych interfejsów API:

  1. Dodaj następujące instrukcje importowania:

    import asyncio

from azure.identity.aio import DefaultAzureCredential
from azure.storage.blob.aio import BlobServiceClient, BlobClient, ContainerClient

  2. Dodaj kod, aby uruchomić program przy użyciu polecenia asyncio.run. Ta funkcja uruchamia przekazaną kohroutynę w main() naszym przykładzie i zarządza pętlą asyncio zdarzeń. Coroutines są deklarowane za pomocą składni async/await. W tym przykładzie main() coroutine najpierw tworzy najwyższy poziom BlobServiceClient przy użyciu async with, a następnie wywołuje metodę, która przesyła obiekt blob. Należy pamiętać, że tylko klient najwyższego poziomu musi używać programu async with, ponieważ inni klienci utworzoni na jego podstawie współużytkować tę samą pulę połączeń.

    async def main():
    sample = BlobSamples()

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

    async with BlobServiceClient(account_url, credential=credential) as blob_service_client:
        await sample.upload_blob_file(blob_service_client, "sample-container")

if __name__ == '__main__':
    asyncio.run(main())

  3. Dodaj kod, aby przesłać obiekt blob. Poniższy przykład przesyła blob ze ścieżki pliku lokalnego za pomocą obiektu ContainerClient. Kod jest taki sam jak w przykładzie synchronicznym, z tą różnicą, że metoda jest zadeklarowana ze async słowem kluczowym, a await słowo kluczowe jest użyte przy wywoływaniu metody upload_blob.

    async def upload_blob_file(self, blob_service_client: BlobServiceClient, container_name: str):
    container_client = blob_service_client.get_container_client(container=container_name)
    with open(file=os.path.join('filepath', 'filename'), mode="rb") as data:
        blob_client = await container_client.upload_blob(name="sample-blob.txt", data=data, overwrite=True)

Dzięki tej podstawowej konfiguracji możesz zaimplementować inne przykłady w tym artykule jako korutyny ze składnią async/await.

Zasoby

Aby dowiedzieć się więcej na temat przekazywania obiektów blob 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 do przekazywania obiektów blob używają następujących operacji interfejsu API REST:

Zasoby biblioteki klienta

Zobacz też

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.
  • Last updated on