Een blok-blob uploaden met Python

• .NET
• Java
• JavaScript
• TypeScript
• Python
• Go

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.

Vereisten

• Azure-abonnement: u kunt een gratis abonnement nemen
• Azure Storage-account: maak een opslagaccount
• Python 3.8+

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

Importinstructies 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 ingebouwde Azure RBAC-rol Opslagblobgegevensbijdrager 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.

Gegevens uploaden naar een blok-blob

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

• upload_blob

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.

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)

Een blok-blob uploaden vanuit een stream

In het volgende voorbeeld worden willekeurige bytes aan gegevens gemaakt en wordt een BytesIO object geüpload naar een blok-blob met behulp van een 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 - De maximale segmentgrootte voor het uploaden van een blok-blob in segmenten. De standaardwaarde is 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)

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

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)

Het instellen van de toegangslaag is alleen toegestaan voor blok-blobs. U kunt de toegangslaag voor een blok-blob instellen op Hot, Coolof ArchiveCold. Als u de toegangslaag wilt Coldinstellen, moet u een minimale clientbibliotheekversie van 12.15.0 gebruiken.

Zie het overzicht van Access-lagen voor meer informatie over toegangslagen.

Een blok-blob uploaden door blokken te faseren en doorvoeren

U kunt meer controle hebben over het verdelen van uploads in blokken door afzonderlijke gegevensblokken handmatig te faseren. Wanneer alle blokken waaruit een blob bestaat zijn gefaseerd, kunt u ze doorvoeren in Blob Storage.

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

• stage_block

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

• commit_block_list

In het volgende voorbeeld worden gegevens uit een bestand en fasen gelezen die moeten 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)

Blobs asynchroon uploaden

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 importinstructies 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 uitgevoerd in main() ons voorbeeld 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 moet worden gebruikt async with, omdat andere clients die ermee zijn gemaakt, dezelfde verbindingsgroep delen.

   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.

Resources

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

Codevoorbeelden

• Synchrone of asynchrone codevoorbeelden weergeven uit dit artikel (GitHub)

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:

• Blob plaatsen (REST API)
• Put Block (REST API)

Clientbibliotheekbronnen

• Referentiedocumentatie voor clientbibliotheek
• Broncode van clientbibliotheek
• Pakket (PyPi)

Zie ook

• Azure Blob-gegevens beheren en zoeken met blobindextags
• Blob-indextags gebruiken om gegevens te beheren en te zoeken in Azure Blob Storage

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.