Pobieranie obiektu blob za pomocą języka Python

  • Artykuł

W tym artykule pokazano, jak pobrać obiekt blob przy użyciu biblioteki klienta usługi Azure Storage dla języka Python. Dane obiektu blob można pobrać do różnych miejsc docelowych, w tym lokalną ścieżkę pliku, strumień lub ciąg tekstowy. Możesz również otworzyć strumień obiektów blob i odczytać go.

Aby dowiedzieć się więcej na temat pobierania obiektów blob przy użyciu asynchronicznych interfejsów API, zobacz Pobieranie obiektów blob asynchronicznie.

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 pobierania. Aby dowiedzieć się więcej, zobacz wskazówki dotyczące autoryzacji dla następującej operacji interfejsu API REST:

Pobieranie obiektu blob

Aby pobrać obiekt blob, możesz użyć następującej metody:

Metoda download_blob zwraca obiekt StorageStreamDownloader . Podczas pobierania biblioteki klienckie dzielą żądanie pobierania na fragmenty, w których każdy fragment jest pobierany z oddzielnym żądaniem pobierania zakresu obiektów blob . To zachowanie zależy od całkowitego rozmiaru obiektu blob i sposobu ustawiania opcji transferu danych.

Pobieranie do ścieżki pliku

Poniższy przykład pobiera obiekt blob do ścieżki pliku:

def download_blob_to_file(self, blob_service_client: BlobServiceClient, container_name):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")
    with open(file=os.path.join(r'filepath', 'filename'), mode="wb") as sample_blob:
        download_stream = blob_client.download_blob()
        sample_blob.write(download_stream.readall())

Pobieranie do strumienia

Poniższy przykład pobiera obiekt blob do strumienia. W tym przykładzie StorageStreamDownloader.read_into pobiera zawartość obiektu blob do strumienia i zwraca liczbę odczytanych bajtów:

def download_blob_to_stream(self, blob_service_client: BlobServiceClient, container_name):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")

    # readinto() downloads the blob contents to a stream and returns the number of bytes read
    stream = io.BytesIO()
    num_bytes = blob_client.download_blob().readinto(stream)
    print(f"Number of bytes: {num_bytes}")

Pobieranie obiektu blob we fragmentach

Poniższy przykład pobiera obiekt blob i iteruje fragmenty w strumieniu pobierania. W tym przykładzie funkcja StorageStreamDownloader.unks zwraca iterator, który umożliwia odczytywanie zawartości obiektu blob we fragmentach:

def download_blob_chunks(self, blob_service_client: BlobServiceClient, container_name):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")

    # This returns a StorageStreamDownloader
    stream = blob_client.download_blob()
    chunk_list = []

    # Read data in chunks to avoid loading all into memory at once
    for chunk in stream.chunks():
        # Process your data (anything can be done here - 'chunk' is a byte array)
        chunk_list.append(chunk)

Pobieranie do ciągu

Poniższy przykład pobiera zawartość obiektu blob jako tekst. W tym przykładzie encoding parametr jest niezbędny do readall() zwrócenia ciągu, w przeciwnym razie zwraca bajty:

def download_blob_to_string(self, blob_service_client: BlobServiceClient, container_name):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")

    # encoding param is necessary for readall() to return str, otherwise it returns bytes
    downloader = blob_client.download_blob(max_concurrency=1, encoding='UTF-8')
    blob_text = downloader.readall()
    print(f"Blob contents: {blob_text}")

Pobieranie blokowego obiektu blob z opcjami konfiguracji

Podczas pobierania obiektu blob można zdefiniować opcje konfiguracji biblioteki klienta. Te opcje można dostosować, aby zwiększyć wydajność i zwiększyć niezawodność. W poniższych przykładach kodu pokazano, jak zdefiniować opcje konfiguracji pobierania 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 podczas pobierania

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_chunk_get_size — Maksymalny rozmiar fragmentu używany do pobierania obiektu blob. Wartość domyślna to 4 MiB.
  • max_single_get_size — Maksymalny rozmiar obiektu blob do pobrania w ramach pojedynczego wywołania. Jeśli łączny max_single_get_sizerozmiar obiektu blob przekroczy wartość , pozostałe dane obiektu blob są pobierane we fragmentach. Wartość domyślna to 32 MiB.

W przypadku operacji pobierania max_concurrency można również przekazać argument podczas wywoływania download_blob. Ten argument definiuje maksymalną liczbę połączeń równoległych dla operacji pobierania.

Poniższy przykład kodu przedstawia sposób określania opcji transferu danych podczas tworzenia obiektu oraz sposobu pobierania BlobClient 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 download_blob_transfer_options(self, account_url: str, container_name: str, blob_name: str):
    # Create a BlobClient object with data transfer options for download
    blob_client = BlobClient(
        account_url=account_url, 
        container_name=container_name, 
        blob_name=blob_name,
        credential=DefaultAzureCredential(),
        max_single_get_size=1024*1024*32, # 32 MiB
        max_chunk_get_size=1024*1024*4 # 4 MiB
    )

    with open(file=os.path.join(r'file_path', 'file_name'), mode="wb") as sample_blob:
        download_stream = blob_client.download_blob(max_concurrency=2)
        sample_blob.write(download_stream.readall())

Asynchroniczne pobieranie obiektów blob

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

Wykonaj następujące kroki, aby pobrać 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

  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 pobiera 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.download_blob_to_file(blob_service_client, "sample-container")

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

  3. Dodaj kod, aby pobrać obiekt blob. Poniższy przykład pobiera obiekt blob do lokalnej ścieżki pliku przy użyciu BlobClient 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 download_blob metody.

    async def download_blob_to_file(self, blob_service_client: BlobServiceClient, container_name):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")
    with open(file=os.path.join(r'filepath', 'filename'), mode="wb") as sample_blob:
        download_stream = await blob_client.download_blob()
        data = await download_stream.readall()
        sample_blob.write(data)

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 pobierania 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 pobierania obiektów blob używają następującej operacji interfejsu API REST:

Przykłady kodu

Zasoby biblioteki klienta