Nahrání objektu blob bloku pomocí Pythonu

Tento článek ukazuje, jak nahrát objekt blob pomocí klientské knihovny azure Storage pro Python. Data můžete nahrát do block blobu z cesty k souboru, datového proudu, binárních objektů nebo textových řetězců. Můžete také nahrát objekty blob s indexovými značkami.

Další informace o nahrávání objektů blob pomocí asynchronních rozhraní API najdete v tématu Asynchronní nahrávání objektů blob.

Požadavky

Předplatné Azure – vytvoření bezplatného předplatného
Účet úložiště Azure – Vytvoření účtu úložiště
Python 3.8 nebo novější

Nastavení prostředí

Pokud nemáte existující projekt, v této části se dozvíte, jak nastavit projekt pro práci s klientskou knihovnou Azure Blob Storage pro Python. Další podrobnosti najdete v tématu Začínáme se službou Azure Blob Storage a Pythonem.

Pokud chcete pracovat s příklady kódu v tomto článku, nastavte projekt pomocí následujícího postupu.

Instalace balíčků

Nainstalujte následující balíčky pomocí pip install:

pip install azure-storage-blob azure-identity

Přidejte příkazy importu

Přidejte následující příkazy import:

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

Autorizace

Autorizační mechanismus musí mít potřebná oprávnění k nahrání objektu blob. K autorizaci pomocí Microsoft Entra ID (doporučeno) potřebujete vestavěnou roli Azure RBAC Storage Blob Data Contributor nebo vyšší. Další informace najdete v pokynech k autorizaci pro Put Blob (REST API) a Put Block (REST API).

Vytvoření objektu klienta

Pokud chcete připojit aplikaci ke službě Blob Storage, vytvořte instanci BlobServiceClient. Následující příklad ukazuje, jak vytvořit objekt klienta pomocí DefaultAzureCredential k autorizaci.

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

Můžete také vytvořit klientské objekty pro konkrétní kontejnery nebo objekty blob, a to buď přímo, nebo z objektu BlobServiceClient . Další informace o vytváření a správě klientských objektů najdete v tématu Vytváření a správa klientských objektů, které pracují s datovými prostředky.

Nahrání dat do objektu blob bloku

K nahrání objektu blob pomocí datového proudu nebo binárního objektu použijte následující metodu:

upload_blob

Tato metoda vytvoří nový blob ze zdroje dat s automatickým dělením na části, což znamená, že zdroj dat může být rozdělen na menší části a nahrán. K nahrání může klientská knihovna použít buď Put Blob, nebo řadu volání Put Block následovaných Put Block List. Toto chování závisí na celkové velikosti objektu a způsobu nastavení možností přenosu dat.

Poznámka:

Klientské knihovny Azure Storage nepodporují souběžné zápisy do stejného objektu blob. Pokud vaše aplikace vyžaduje více procesů zápisů do stejného objektu blob, měli byste implementovat strategii řízení souběžnosti, která poskytuje předvídatelné prostředí. Další informace o strategiích souběžnosti najdete v tématu Správa souběžnosti ve službě Blob Storage.

Nahrání blokového blobu z místní souborové cesty

Následující příklad nahraje soubor do bloku blobu pomocí objektu 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)

Nahrání bloku blobu ze streamu

Následující příklad vytvoří náhodná data v bajtech a nahraje objekt BytesIO do blokového blobu pomocí objektu 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")

Nahrání binárních dat do blokového blobu

Následující příklad nahraje binární data do objektu blob bloku pomocí objektu 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")

** Nahrajte blockový blob s indexovými značkami

Následující příklad nahraje blokový blob s indexovými značkami:

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)

Nahrání bloku typu blob s možnostmi konfigurace

Při nahrávání objektu blob můžete definovat možnosti konfigurace klientské knihovny. Tyto možnosti je možné ladit, aby se zlepšil výkon, zlepšila spolehlivost a optimalizovala náklady. Následující příklady kódu ukazují, jak definovat možnosti konfigurace pro nahrávání na úrovni metody i na úrovni klienta při vytváření instance BlobClient. Tyto možnosti lze také nakonfigurovat pro instanci ContainerClient nebo instanci BlobServiceClient .

Určení možností přenosu dat pro nahrání

Při vytváření instance klienta můžete nastavit možnosti konfigurace pro optimalizaci výkonu operací přenosu dat. Při vytváření klientského objektu v Pythonu můžete předat následující argumenty klíčových slov:

max_block_size – Maximální velikost části pro nahrání objektu blob bloku po částech. Výchozí hodnota je 4 MiB.
max_single_put_size – Pokud je velikost objektu blob menší nebo rovna max_single_put_size, objekt blob se nahraje s jedním Put Blob požadavkem. Pokud je velikost objektu blob větší než max_single_put_size nebo neznámá, blob se nahraje po částech pomocí Put Block a potvrdí se použitím Put Block List. Výchozí nastavení je 64 MiB.

Další informace o omezení velikosti přenosu pro Blob Storage najdete v tématu Cíle škálování úložiště objektů BLOB.

U operací nahrávání můžete také předat max_concurrency argument při volání upload_blob. Tento argument definuje maximální počet paralelních připojení, která se mají použít, když velikost objektu blob překročí 64 MiB.

Následující příklad kódu ukazuje, jak určit možnosti přenosu dat při vytváření objektu BlobClient a jak nahrát data pomocí tohoto klientského objektu. Hodnoty uvedené v této ukázce nejsou určené jako doporučení. Pokud chcete tyto hodnoty správně vyladit, musíte zvážit konkrétní potřeby vaší aplikace.

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)

Další informace o ladění možností přenosu dat najdete v tématu Ladění výkonu pro nahrávání a stahování pomocí Pythonu.

Nastavte úroveň přístupu objektu blob při nahrání.

Úroveň přístupu objektu blob můžete nastavit při nahrávání předáním klíčového argumentu standard_blob_tier do upload_blob. Azure Storage nabízí různé úrovně přístupu, takže můžete data objektů blob ukládat co nejefektivnějším způsobem podle toho, jak se využívají.

Následující příklad kódu ukazuje, jak nastavit úroveň přístupu při nahrávání "blobu":

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)

Nastavení úrovně přístupu je povolené jenom pro blokové objekty blob. Úroveň přístupu objektu blob bloku můžete nastavit na Hot, Cool, Coldnebo Archive. Abyste nastavili úroveň přístupu na Cold, musíte použít minimální verzi klientské knihovny 12.15.0.

Další informace o úrovních přístupu najdete v tématu Přehled úrovní přístupu.

Nahrání blokového blobu přípravou bloků a potvrzením

Ruční přípravou jednotlivých bloků dat můžete mít větší kontrolu nad tím, jak rozdělit nahrávání na bloky. Když jsou všechny bloky, které tvoří objekt blob, připravené, můžete je potvrdit do služby Blob Storage.

Pomocí následující metody vytvořte nový blok, který se má potvrdit jako součást blobu:

stage_block

K zápisu objektu blob použijte následující metodu zadáním seznamu ID bloků, které tvoří objekt blob:

commit_block_list

Následující příklad načte data ze souboru a připraví bloky ke schválení jako součást blobu:

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)

Asynchronní nahrávání blobů

Klientská knihovna Azure Blob Storage pro Python podporuje asynchronní nahrávání objektů blob. Další informace o požadavcích na nastavení projektu najdete v tématu Asynchronní programování.

K nahrání objektu blob pomocí asynchronních rozhraní API postupujte takto:

Přidejte následující příkazy importu:

import asyncio

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

Přidejte kód pro spuštění programu pomocí asyncio.run. Tato funkce spustí předanou korutinu, v našem příkladu main(), a spravuje událostní smyčku asyncio. Koroutiny jsou deklarovány syntaxí async/await. V tomto příkladu main() korutin nejprve vytvoří nejvyšší úroveň BlobServiceClient pomocí async witha pak zavolá metodu, která nahraje objekt blob. Mějte na paměti, že pouze klient nejvyšší úrovně musí používat async with, protože ostatní klienti, kteří jsou z něj vytvořeni, sdílejí stejný fond připojení.
```
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())
```

Přidejte kód pro nahrání objektu blob. Následující příklad nahraje objekt blob z místní souborové cesty pomocí objektu ContainerClient. Kód je stejný jako synchronní příklad, s tím rozdílem, že metoda je deklarována pomocí klíčového slova async a klíčového slova await se používá při volání 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)

S tímto základním nastavením můžete pomocí syntaxe async/await implementovat další příklady v tomto článku jako korutiny.

Zdroje informací

Další informace o nahrávání objektů blob pomocí klientské knihovny azure Blob Storage pro Python najdete v následujících zdrojích informací.

Ukázky kódu

Zobrazení synchronních nebo asynchronních ukázek kódu z tohoto článku (GitHub)

Operace rozhraní REST API

Sada Azure SDK pro Python obsahuje knihovny, které jsou postavené na rozhraní Azure REST API a umožňují interakci s operacemi rozhraní REST API prostřednictvím známých paradigmat Pythonu. Metody klientské knihovny pro nahrávání objektů blob používají následující operace rozhraní REST API:

Vložení objektu blob (REST API)
Put Block (REST API)

Prostředky klientské knihovny

Viz také

Tento článek je součástí příručky pro vývojáře služby Blob Storage pro Python. Další informace najdete v úplném seznamu článků příručky pro vývojáře na webu Sestavení aplikace v Pythonu.

Váš názor

Byla tato stránka užitečná?

Last updated on 2025-10-09