Nahrání objektu blob bloku pomocí Pythonu

• .NET
• Java
• JavaScript
• TypeScript
• Python
• Přejít

Tento článek ukazuje, jak nahrát objekt blob pomocí klientské knihovny azure Storage pro Python. Data můžete nahrát do objektu blob bloku z cesty k souboru, datového proudu, binárního objektu nebo textového řetězce. Objekty blob můžete také nahrát se značkami indexu.

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řidání příkazů 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 předdefinovanou roli Přispěvatel dat objektů blob služby Azure RBAC 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 pro DefaultAzureCredential 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ý objekt blob ze zdroje dat s automatickým vytvářením bloků dat, což znamená, že zdroj dat může být rozdělený na menší bloky dat 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.

Nahrání objektu blob bloku z místní cesty k souboru

Následující příklad nahraje soubor do objektu blob bloku 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í objektu blob bloku ze streamu

Následující příklad vytvoří náhodné bajty dat a nahraje BytesIO objekt do objektu blob bloku 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 objektu blob bloku

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

Nahrání objektu blob bloku se značkami indexu

Následující příklad nahraje objekt blob bloku se značkami indexu:

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í objektu blob bloku 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 bloku pro nahrání objektu blob bloku do bloků dat. 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ší nebo max_single_put_size neznámá, objekt blob se nahraje do bloků dat pomocí Put Block a potvrzeného použití Put Block List. Výchozí hodnota je 64 MiB.

Další informace o omezení velikosti přenosu pro Blob Storage najdete v tématu Cíle škálování pro ú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.

Nastavení úrovně přístupu k objektu blob při nahrání

Úroveň přístupu objektu blob můžete nastavit při nahrávání předáním argumentu klíčového standard_blob_tier slova 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í objektu 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)

Nastavení úrovně přístupu je povolené jenom pro objekty blob bloku. Úroveň přístupu objektu blob bloku můžete nastavit na Hot, Cool, Coldnebo Archive. Pokud chcete nastavit úroveň přístupu, Coldmusí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í objektu blob bloku přípravými bloky a potvrzením

Můžete mít větší kontrolu nad tím, jak rozdělit nahrávání do bloků ručním přípravou jednotlivých bloků dat. 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 objektu blob:

• 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 bloků fází, které se mají potvrdit jako součást objektu 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)

Asynchronní nahrávání objektů 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:

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

2. Přidejte kód pro spuštění programu pomocí asyncio.run. Tato funkce spustí předanou korutinu v main() našem příkladu a spravuje smyčku asyncio událostí. 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ří z něj vytvořili, 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())
   

3. Přidejte kód pro nahrání objektu blob. Následující příklad nahraje objekt blob z místní cesty k souboru pomocí objektu ContainerClient . Kód je stejný jako synchronní příklad s tím rozdílem, že metoda je deklarována pomocí async klíčového await slova a klíčové slovo 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 implementovat další příklady v tomto článku jako koruty pomocí syntaxe async/await.

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

• Referenční dokumentace ke klientské knihovně
• Zdrojový kód klientské knihovny
• Balíček (PyPi)

Viz také

• Správa a vyhledání dat objektů blob v Azure pomocí značek indexu objektů blob
• Použití značek indexu objektů blob ke správě a hledání dat ve službě Azure Blob Storage

Související obsah

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