Delen via

Een blok-blob uploaden met Python

In dit artikel wordt beschreven hoe u een blob uploadt met behulp van de Azure Storage-clientbibliotheek voor Python. U kunt gegevens uploaden naar een blok-blob vanuit een bestandspad, een stroom, een binair object of een tekenreeks. U kunt ook blobs uploaden met indextags.

Zie Blobs asynchroon uploaden voor meer informatie over het uploaden van blobs met behulp van asynchrone API's.

Prerequisites

Uw omgeving instellen

Als u geen bestaand project hebt, ziet u in deze sectie hoe u een project instelt voor gebruik met de Azure Blob Storage-clientbibliotheek voor Python. Zie Aan de slag met Azure Blob Storage en Python voor meer informatie.

Als u wilt werken met de codevoorbeelden in dit artikel, volgt u deze stappen om uw project in te stellen.

Pakketten installeren

Installeer de volgende pakketten met behulp van pip install:

pip install azure-storage-blob azure-identity

Importverklaringen toevoegen

Voeg de volgende import instructies toe:

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

Autorisatie

Het autorisatiemechanisme moet over de benodigde machtigingen beschikken om een blob te kunnen uploaden. Voor autorisatie met Microsoft Entra ID (aanbevolen) hebt u de ingebouwde Azure RBAC-rol Opslag Blob Gegevens Bijdrager of hoger nodig. Zie de autorisatierichtlijnen voor Put Blob (REST API) en Put Block (REST API) voor meer informatie.

Een clientobject maken

Als u een app wilt verbinden met Blob Storage, maakt u een exemplaar van BlobServiceClient. In het volgende voorbeeld ziet u hoe u een clientobject maakt met behulp van DefaultAzureCredential autorisatie:

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

U kunt ook clientobjecten maken voor specifieke containers of blobs, rechtstreeks of vanuit het BlobServiceClient object. Zie Clientobjecten maken en beheren die interactie hebben met gegevensbronnen voor meer informatie over het maken en beheren van clientobjecten.

Upload data to a block blob

Als u een blob wilt uploaden met behulp van een stream of een binair object, gebruikt u de volgende methode:

Met deze methode maakt u een nieuwe blob op basis van een gegevensbron met automatische segmentering, wat betekent dat de gegevensbron kan worden gesplitst in kleinere segmenten en kan worden geüpload. Als u het uploaden wilt uitvoeren, kan de clientbibliotheek Put Blob of een reeks Put Block-aanroepen gebruiken, gevolgd door Put Block List. Dit gedrag is afhankelijk van de totale grootte van het object en hoe de opties voor gegevensoverdracht worden ingesteld.

Notitie

De Azure Storage-clientbibliotheken bieden geen ondersteuning voor gelijktijdige schrijfbewerkingen naar dezelfde blob. Als voor uw app meerdere processen nodig zijn die naar dezelfde blob worden geschreven, moet u een strategie voor gelijktijdigheidsbeheer implementeren om een voorspelbare ervaring te bieden. Zie Gelijktijdigheid beheren in Blob Storagevoor meer informatie over gelijktijdigheidsstrategieën.

Een blok-blob uploaden vanuit een lokaal bestandspad

In het volgende voorbeeld wordt een bestand geüpload naar een blok-blob met behulp van een BlobClient object:

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

The following example creates random bytes of data and uploads a BytesIO object to a block blob using a BlobClient object:

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

Binaire gegevens uploaden naar een blok-blob

In het volgende voorbeeld worden binaire gegevens geüpload naar een blok-blob met behulp van een BlobClient object:

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

Een blok-blob uploaden met indextags

In het volgende voorbeeld wordt een blok-blob met indextags geüpload:

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)

Een blok-blob uploaden met configuratieopties

U kunt configuratieopties voor clientbibliotheek definiëren bij het uploaden van een blob. Deze opties kunnen worden afgestemd om de prestaties te verbeteren, de betrouwbaarheid te verbeteren en de kosten te optimaliseren. In de volgende codevoorbeelden ziet u hoe u configuratieopties definieert voor een upload, zowel op methodeniveau als op clientniveau bij het instantiëren van BlobClient. Deze opties kunnen ook worden geconfigureerd voor een ContainerClient-exemplaar of een BlobServiceClient-exemplaar .

Opties voor gegevensoverdracht opgeven voor uploaden

U kunt configuratieopties instellen bij het instantiëren van een client om de prestaties voor gegevensoverdrachtbewerkingen te optimaliseren. U kunt de volgende trefwoordargumenten doorgeven bij het maken van een clientobject in Python:

  • max_block_size - The maximum chunk size for uploading a block blob in chunks. Defaults to 4 MiB.
  • max_single_put_size - Als de blobgrootte kleiner is dan of gelijk is aan max_single_put_size, wordt de blob met één Put Blob aanvraag geüpload. Als de blob groter is dan max_single_put_size of onbekend is, wordt de blob geüpload in segmenten met behulp van Put Block en doorgevoerd met behulp van Put Block List. De standaardwaarde is 64 MiB.

Zie Schaaldoelen voor Blob Storage voor meer informatie over overdrachtslimieten voor Blob Storage.

Voor uploadbewerkingen kunt u ook het argument doorgeven bij het max_concurrency aanroepen van upload_blob. Dit argument definieert het maximum aantal parallelle verbindingen dat moet worden gebruikt wanneer de blob groter is dan 64 MiB.

In het volgende codevoorbeeld ziet u hoe u opties voor gegevensoverdracht opgeeft bij het maken van een BlobClient object en hoe u gegevens uploadt met behulp van dat clientobject. De waarden in dit voorbeeld zijn niet bedoeld als aanbeveling. Als u deze waarden goed wilt afstemmen, moet u rekening houden met de specifieke behoeften van uw app.

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)

Raadpleeg Prestaties aanpassen voor uploads en downloads met Python voor meer informatie over het afstemmen van gegevensoverdracht opties.

De toegangslaag van een blob instellen bij uploaden

U kunt de toegangslaag van een blob instellen bij het uploaden door het standard_blob_tier trefwoordargument door te geven aan upload_blob. Azure Storage biedt verschillende toegangslagen, zodat u uw blob-gegevens op de meest rendabele manier kunt opslaan op basis van de manier waarop deze worden gebruikt.

In het volgende codevoorbeeld ziet u hoe u de toegangslaag instelt bij het uploaden van een 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)

Setting the access tier is only allowed for block blobs. U kunt de toegangslaag voor een blok-blob instellen op Hot, Coolof ColdArchive. Als u de toegangslaag wilt Coldinstellen, moet u een minimale clientbibliotheekversie van 12.15.0 gebruiken.

Zie Overzicht van toegangslagen voor meer informatie over toegangsniveaus.

Upload a block blob by staging blocks and committing

U kunt meer controle hebben over het verdelen van uploads in blokken door afzonderlijke gegevensblokken handmatig te faseren. When all of the blocks that make up a blob are staged, you can commit them to Blob Storage.

Gebruik de volgende methode om een nieuw blok te maken dat moet worden doorgevoerd als onderdeel van een blob:

Gebruik de volgende methode om een blob te schrijven door de lijst met blok-id's op te geven waaruit de blob bestaat:

In het volgende voorbeeld worden gegevens uit een bestand gelezen en worden blokken klaargezet om te worden vastgelegd als onderdeel van een 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)

Upload blobs asynchronously

De Azure Blob Storage-clientbibliotheek voor Python ondersteunt het asynchroon uploaden van blobs. Zie Asynchrone programmering voor meer informatie over de vereisten voor het instellen van projecten.

Volg deze stappen om een blob te uploaden met behulp van asynchrone API's:

  1. Voeg de volgende importverklaringen toe:

    import asyncio

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

  2. Voeg code toe om het programma uit te voeren met behulp van asyncio.run. Met deze functie wordt de doorgegeven coroutine, zoals in ons voorbeeld main(), uitgevoerd en wordt de asyncio gebeurtenislus beheerd. Coroutines worden gedeclareerd met de syntaxis async/await. In dit voorbeeld maakt de main() coroutine eerst het hoogste niveau BlobServiceClient met behulp van async withen roept vervolgens de methode aan waarmee de blob wordt geüpload. Houd er rekening mee dat alleen de client op het hoogste niveau async with moet gebruiken, aangezien andere clients die ervan zijn gemaakt dezelfde verbindingspool gebruiken.

    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. Voeg code toe om de blob te uploaden. In het volgende voorbeeld wordt een blob vanuit een lokaal bestandspad geüpload met behulp van een ContainerClient object. De code is hetzelfde als het synchrone voorbeeld, behalve dat de methode wordt gedeclareerd met het async trefwoord en het await trefwoord wordt gebruikt bij het aanroepen van de upload_blob methode.

    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)

Met deze basisinstallatie kunt u andere voorbeelden in dit artikel implementeren als coroutines met behulp van async/await syntaxis.

Middelen

Zie de volgende resources voor meer informatie over het uploaden van blobs met behulp van de Azure Blob Storage-clientbibliotheek voor Python.

Codevoorbeelden

REST API-bewerkingen

De Azure SDK voor Python bevat bibliotheken die zijn gebaseerd op de Azure REST API, zodat u kunt communiceren met REST API-bewerkingen via bekende Python-paradigma's. De clientbibliotheekmethoden voor het uploaden van blobs gebruiken de volgende REST API-bewerkingen:

Client library resources

Zie ook

Gerelateerde inhoud

  • Dit artikel maakt deel uit van de ontwikkelaarshandleiding voor Blob Storage voor Python. Zie de volledige lijst met artikelen over ontwikkelaarshandleidingen in Uw Python-app bouwen voor meer informatie.