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

Artykuł
11/16/2023

W tym artykule pokazano, jak przekazać obiekt blob przy użyciu biblioteki klienta usługi Azure Storage dla języka Python. Dane można przekazać do blokowego obiektu blob 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

W tym artykule założono, że masz już skonfigurowany projekt do pracy z biblioteką klienta usługi Azure Blob Storage dla języka Python. Aby dowiedzieć się więcej na temat konfigurowania projektu, w tym instalacji pakietu, dodawania import instrukcji i tworzenia autoryzowanego obiektu klienta, zobacz Rozpoczynanie pracy z usługami Azure Blob Storage i Python.
Aby używać asynchronicznych interfejsów API w kodzie, zobacz wymagania w sekcji Programowanie asynchroniczne.
Mechanizm autoryzacji musi mieć uprawnienia do wykonywania operacji przekazywania. Aby dowiedzieć się więcej, zobacz wskazówki dotyczące autoryzacji dla następujących operacji interfejsu API REST:
- Umieść obiekt blob
- Umieść blok

Przekazywanie danych do blokowego obiektu blob

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

upload_blob

Ta metoda tworzy nowy obiekt blob ze źródła danych z automatycznym fragmentowaniem, co oznacza, że źródło danych może zostać podzielone na mniejsze fragmenty i przekazane. Aby wykonać przekazywanie, biblioteka kliencka może używać funkcji Put Blob lub serii wywołań Put Block, a następnie umieścić listę bloków. To zachowanie zależy od ogólnego rozmiaru obiektu i sposobu ustawiania opcji transferu danych.

Przekazywanie blokowego obiektu blob ze ścieżki pliku lokalnego

Poniższy przykład przekazuje plik do blokowego obiektu blob przy użyciu BlobClient obiektu :

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)

Przekazywanie blokowego obiektu blob ze strumienia

Poniższy przykład tworzy losowe bajty danych i przekazuje BytesIO obiekt do blokowego obiektu blob przy użyciu BlobClient obiektu :

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 obiektu blob

W poniższym przykładzie dane binarne są przekazywane do blokowego obiektu blob przy użyciu BlobClient obiektu :

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

Przekazywanie blokowego obiektu blob z tagami indeksu

Poniższy przykład przekazuje blokowy obiekt blob 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)

Przekazywanie blokowego obiektu blob przy użyciu opcji konfiguracji

Opcje konfiguracji biblioteki klienta można zdefiniować podczas przekazywania obiektu blob. 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 przekazywania zarówno na poziomie metody, jak i na poziomie klienta podczas tworzenia wystąpienia obiektu BlobClient. Te opcje można również skonfigurować dla wystąpienia Klasy ContainerClient lub wystąpienia obiektu BlobServiceClient .

Określanie opcji transferu danych do przekazania

Opcje konfiguracji można ustawić podczas tworzenia wystąpienia 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 przekazywania blokowego obiektu blob we fragmentach. 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 i zatwierdzonym za pomocą Put Block polecenia 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.

W przypadku operacji przekazywania 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.

Ustawianie warstwy dostępu obiektu blob podczas przekazywania

Warstwę dostępu obiektu blob można ustawić podczas przekazywania, przekazując argument słowa kluczowego standard_blob_tier do 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 przekazywania 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 blokowych obiektów blob. Warstwę dostępu dla blokowego obiektu blob można ustawić na Hot, Cool, Coldlub 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 obiektu blob przez bloki przejściowe i zatwierdzanie

Możesz mieć większą kontrolę nad sposobem dzielenia przekazywania na bloki przez ręczne przemieszczanie poszczególnych bloków danych. Gdy wszystkie bloki tworzące obiekt 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:

stage_block

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

commit_block_list

Poniższy przykład odczytuje dane z pliku i bloków etapów, które mają zostać zatwierdzone w ramach 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 przekazywanie obiektów blob

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 przekazać obiekt blob przy użyciu asynchronicznych interfejsów API:

Dodaj następujące instrukcje importowania:

import asyncio

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

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 metody async with, a następnie wywołuje metodę, która przekazuje 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())
```

Dodaj kod, aby przekazać obiekt blob. Poniższy przykład przekazuje obiekt blob ze ścieżki pliku lokalnego ContainerClient przy użyciu obiektu. Kod jest taki sam jak w przykładzie synchronicznym, z tą różnicą, że metoda jest zadeklarowana za async pomocą słowa kluczowego, a await słowo kluczowe jest używane podczas wywoływania upload_blob metody.

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)

Ta podstawowa konfiguracja umożliwia zaimplementowanie innych przykładów w tym artykule jako kohroutines przy użyciu 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.

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:

Umieszczanie obiektu blob (interfejs API REST)
Umieść blok (interfejs API REST)

Przykłady kodu

Wyświetlanie synchronicznych lub asynchronicznych przykładów kodu z tego artykułu (GitHub)

Udostępnij przez