Upload a block blob with Python

2025-04-13

Tento článek ukazuje, jak nahrát objekt blob pomocí klientské knihovny azure Storage pro Python. You can upload data to a block blob from a file path, a stream, a binary object, or a text string. You can also upload blobs with index tags.

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.

Upload data to a block blob

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.

Upload a block blob from a local file path

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)

Upload a block blob from a stream

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

Upload a block blob with index tags

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)

Upload a block blob with configuration options

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 - The maximum chunk size for uploading a block blob in chunks. Defaults to 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.

Set a blob's access tier on upload

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

Setting the access tier is only allowed for block blobs. Ú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.

Upload a block blob by staging blocks and committing

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. This function runs the passed coroutine, main() in our example, and manages the asyncio event loop. Koroutiny jsou deklarovány syntaxí async/await. In this example, the main() coroutine first creates the top level BlobServiceClient using async with, then calls the method that uploads the blob. Note that only the top level client needs to use async with, as other clients created from it share the same connection pool.
```
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:

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

Sdílet prostřednictvím