Udostępnij za pośrednictwem

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

  • Artykuł

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

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 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 przekazywania obiektu blob. Aby uzyskać autoryzację przy użyciu identyfikatora Entra firmy Microsoft (zalecane), potrzebujesz wbudowanej kontroli dostępu opartej na rolach platformy Azure współautora danych obiektów blob usługi Storage lub nowszego. 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 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.

Przekazywanie danych do blokowego obiektu blob

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

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:

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:

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:

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

  3. 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.

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.