Azure Storage Blobs-clientbibliotheek voor Python - versie 12.19.0

  • Artikel

Azure Blob Storage is Microsoft's oplossing voor de opslag van objecten in de cloud. Blob Storage is geoptimaliseerd voor het opslaan van grote hoeveelheden ongestructureerde gegevens, zoals tekst of binaire gegevens.

Blob-opslag is ideaal voor:

  • Het rechtstreeks aan een browser leveren van afbeeldingen of documenten
  • De opslag van bestanden voor gedistribueerde toegang
  • Streaming van video en audio
  • De opslag van gegevens voor back-up en herstel, herstel na noodgevallen en archivering
  • De opslag van gegevens voor analyse door een on-premises of in Azure gehoste service

Broncode | Pakket (PyPI) | Pakket (Conda) | API-referentiedocumentatie | Productdocumentatie | Monsters

Aan de slag

Vereisten

Het pakket installeren

Installeer de Azure Storage Blobs-clientbibliotheek voor Python met pip:

pip install azure-storage-blob

Create a storage account

Als u een nieuw opslagaccount wilt maken, kunt u Azure Portal, Azure PowerShell of Azure CLI gebruiken:

# Create a new resource group to hold the storage account -
# if using an existing resource group, skip this step
az group create --name my-resource-group --location westus2

# Create the storage account
az storage account create -n my-storage-account-name -g my-resource-group

De client maken

Met de Azure Storage Blobs-clientbibliotheek voor Python kunt u communiceren met drie typen resources: het opslagaccount zelf, blob-opslagcontainers en blobs. Interactie met deze resources begint met een exemplaar van een client. Als u een clientobject wilt maken, hebt u de URL van het blobserviceaccount van het opslagaccount en een referentie nodig waarmee u toegang hebt tot het opslagaccount:

from azure.storage.blob import BlobServiceClient

service = BlobServiceClient(account_url="https://<my-storage-account-name>.blob.core.windows.net/", credential=credential)

De account-URL opzoeken

U kunt de BLOB-service-URL van het opslagaccount vinden via azure portal, Azure PowerShell of Azure CLI:

# Get the blob service account url for the storage account
az storage account show -n my-storage-account-name -g my-resource-group --query "primaryEndpoints.blob"

Typen referenties

De credential parameter kan in verschillende vormen worden opgegeven, afhankelijk van het type autorisatie dat u wilt gebruiken:

  1. Als u een AAD-tokenreferentie (Azure Active Directory) wilt gebruiken, geeft u een exemplaar op van het gewenste referentietype dat is verkregen uit de azure-identity-bibliotheek . DefaultAzureCredential kan bijvoorbeeld worden gebruikt om de client te verifiëren.

    Hiervoor is enige initiële installatie vereist:

    Gebruik de geretourneerde tokenreferentie om de client te verifiëren:

        from azure.identity import DefaultAzureCredential
    from azure.storage.blob import BlobServiceClient
    token_credential = DefaultAzureCredential()

    blob_service_client = BlobServiceClient(
        account_url="https://<my_account_name>.blob.core.windows.net",
        credential=token_credential
    )

  2. Als u een SAS-token (Shared Access Signature) wilt gebruiken, geeft u het token op als een tekenreeks. Als uw account-URL het SAS-token bevat, laat u de referentieparameter weg. U kunt een SAS-token genereren vanuit Azure Portal onder Shared Access Signature of een van de generate_sas() functies gebruiken om een SAS-token te maken voor het opslagaccount, de container of de blob:

    from datetime import datetime, timedelta
from azure.storage.blob import BlobServiceClient, generate_account_sas, ResourceTypes, AccountSasPermissions

sas_token = generate_account_sas(
    account_name="<storage-account-name>",
    account_key="<account-access-key>",
    resource_types=ResourceTypes(service=True),
    permission=AccountSasPermissions(read=True),
    expiry=datetime.utcnow() + timedelta(hours=1)
)

blob_service_client = BlobServiceClient(account_url="https://<my_account_name>.blob.core.windows.net", credential=sas_token)

  3. Als u een gedeelde sleutel voor een opslagaccount (ook wel accountsleutel of toegangssleutel genoemd) wilt gebruiken, geeft u de sleutel op als een tekenreeks. U kunt dit vinden in Azure Portal onder de sectie Toegangssleutels of door de volgende Azure CLI-opdracht uit te voeren:

    az storage account keys list -g MyResourceGroup -n MyStorageAccount

    Gebruik de sleutel als referentieparameter om de client te verifiëren:

    from azure.storage.blob import BlobServiceClient
service = BlobServiceClient(account_url="https://<my_account_name>.blob.core.windows.net", credential="<account_access_key>")

    Als u een aangepaste URL gebruikt (wat betekent dat de URL niet deze indeling <my_account_name>.blob.core.windows.netheeft), moet u de client instantiëren met behulp van de onderstaande referentie:

    from azure.storage.blob import BlobServiceClient
service = BlobServiceClient(account_url="https://<my_account_name>.blob.core.windows.net", 
   credential={"account_name": "<your_account_name>", "account_key":"<account_access_key>"})

  4. Als u anonieme openbare leestoegang wilt gebruiken, laat u de referentieparameter gewoon weg.

De client maken op basis van een verbindingsreeks

Afhankelijk van uw gebruiksscenario en autorisatiemethode, kunt u er de voorkeur aan geven om een clientexemplaren te initialiseren met een opslag-verbindingsreeks in plaats van de account-URL en referenties afzonderlijk op te geven. U doet dit door de opslag-verbindingsreeks door te geven aan de klassemethode van from_connection_string de client:

from azure.storage.blob import BlobServiceClient

connection_string = "DefaultEndpointsProtocol=https;AccountName=xxxx;AccountKey=xxxx;EndpointSuffix=core.windows.net"
service = BlobServiceClient.from_connection_string(conn_str=connection_string)

De verbindingsreeks voor uw opslagaccount vindt u in Azure Portal onder de sectie Toegangssleutels of door de volgende CLI-opdracht uit te voeren:

az storage account show-connection-string -g MyResourceGroup -n MyStorageAccount

Belangrijkste concepten

De Azure Blob-service bestaat uit de volgende onderdelen:

  • Het opslagaccount zelf
  • Een container in het opslagaccount
  • Een blob in een container

Met de Azure Storage Blobs-clientbibliotheek voor Python kunt u met elk van deze onderdelen communiceren via het gebruik van een toegewezen clientobject.

Clients

Er zijn vier verschillende clients beschikbaar voor interactie met de verschillende onderdelen van de Blob-service:

  1. BlobServiceClient : deze client vertegenwoordigt interactie met het Azure-opslagaccount zelf en stelt u in staat om vooraf geconfigureerde clientexemplaren te verkrijgen voor toegang tot de containers en blobs binnen. Het biedt bewerkingen voor het ophalen en configureren van de accounteigenschappen, evenals het weergeven, maken en verwijderen van containers in het account. Als u bewerkingen wilt uitvoeren op een specifieke container of blob, haalt u een client op met behulp van de get_container_client methode of get_blob_client .
  2. ContainerClient : deze client vertegenwoordigt interactie met een specifieke container (die nog niet hoeft te bestaan) en stelt u in staat om vooraf geconfigureerde clientexemplaren te verkrijgen voor toegang tot de blobs binnen. Het biedt bewerkingen voor het maken, verwijderen of configureren van een container en bevat bewerkingen voor het weergeven, uploaden en verwijderen van de blobs in de container. Als u bewerkingen wilt uitvoeren op een specifieke blob in de container, haalt u een client op met behulp van de get_blob_client -methode.
  3. BlobClient : deze client vertegenwoordigt interactie met een specifieke blob (die nog niet hoeft te bestaan). Het biedt bewerkingen voor het uploaden, downloaden, verwijderen en maken van momentopnamen van een blob, evenals specifieke bewerkingen per blobtype.
  4. BlobLeaseClient : deze client vertegenwoordigt lease-interacties met een ContainerClient of BlobClient. Het biedt bewerkingen voor het verkrijgen, vernieuwen, vrijgeven, wijzigen en verbreken van een lease voor een opgegeven resource.

Asynchrone clients

Deze bibliotheek bevat een volledige asynchrone API die wordt ondersteund in Python 3.5+. Als u deze wilt gebruiken, moet u eerst een asynchroon transport installeren, zoals aiohttp. Zie azure-core-documentatie voor meer informatie.

Asynchrone clients en referenties moeten worden gesloten wanneer ze niet meer nodig zijn. Deze objecten zijn asynchrone contextbeheerders en definiëren asynchrone close methoden.

Blob-typen

Nadat u een client hebt geïnitialiseerd, kunt u kiezen uit de verschillende typen blobs:

  • Blok-blobs slaan tekst en binaire gegevens op, tot ongeveer 4,75 TiB. Blok-blobs bestaan uit gegevensblokken die afzonderlijk kunnen worden beheerd
  • Toevoeg-blobs bestaan uit blokken zoals blok-blobs, maar zijn geoptimaliseerd voor toevoegbewerkingen. Toevoeg-blobs zijn ideaal voor scenario's zoals het vastleggen van gegevens van virtuele machines
  • Pagina-blobs worden gebruikt voor het opslaan van bestanden voor willekeurige toegang tot maximaal 8 TiB in grootte. Pagina-blobs slaan VHD-bestanden (virtuele harde schijven) op en fungeren als schijven voor virtuele Azure-machines

Voorbeelden

De volgende secties bevatten verschillende codefragmenten voor enkele van de meest voorkomende Storage Blob-taken, waaronder:

Houd er rekening mee dat er een container moet worden gemaakt voordat u een blob kunt uploaden of downloaden.

Een container maken

Maak een container van waaruit u blobs kunt uploaden of downloaden.

from azure.storage.blob import ContainerClient

container_client = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

container_client.create_container()

De asynchrone client gebruiken om een blob te uploaden

from azure.storage.blob.aio import ContainerClient

container_client = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

await container_client.create_container()

Een blob uploaden

Een blob uploaden naar uw container

from azure.storage.blob import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./SampleSource.txt", "rb") as data:
    blob.upload_blob(data)

De asynchrone client gebruiken om een blob te uploaden

from azure.storage.blob.aio import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./SampleSource.txt", "rb") as data:
    await blob.upload_blob(data)

Een blob downloaden

Een blob downloaden uit uw container

from azure.storage.blob import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./BlockDestination.txt", "wb") as my_blob:
    blob_data = blob.download_blob()
    blob_data.readinto(my_blob)

Een blob asynchroon downloaden

from azure.storage.blob.aio import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./BlockDestination.txt", "wb") as my_blob:
    stream = await blob.download_blob()
    data = await stream.readall()
    my_blob.write(data)

Blobs opsommen

De blobs in uw container weergeven

from azure.storage.blob import ContainerClient

container = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

blob_list = container.list_blobs()
for blob in blob_list:
    print(blob.name + '\n')

De blobs asynchroon weergeven

from azure.storage.blob.aio import ContainerClient

container = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

blob_list = []
async for blob in container.list_blobs():
    blob_list.append(blob)
print(blob_list)

Optionele configuratie

Optionele trefwoordargumenten die kunnen worden doorgegeven op het niveau van de client en per bewerking.

Configuratie van beleid voor opnieuw proberen

Gebruik de volgende trefwoordargumenten bij het instantiëren van een client om het beleid voor opnieuw proberen te configureren:

  • retry_total (int): het totale aantal nieuwe pogingen dat moet worden toegestaan. Heeft voorrang op andere aantallen. Geef door retry_total=0 als u aanvragen niet opnieuw wilt proberen. De standaardwaarde is 10.
  • retry_connect (int): hoeveel verbindingsfouten u opnieuw wilt proberen. Standaardwaarde is 3.
  • retry_read (int): hoe vaak moet u het opnieuw proberen bij leesfouten. Standaardwaarde is 3.
  • retry_status (int): hoe vaak moet u ongeldige statuscodes opnieuw proberen. Standaardwaarde is 3.
  • retry_to_secondary (bool): of de aanvraag opnieuw moet worden geprobeerd naar secundaire, indien mogelijk. Dit mag alleen worden ingeschakeld als RA-GRS-accounts worden gebruikt en mogelijk verouderde gegevens kunnen worden verwerkt. De standaardwaarde is False.

Versleutelingsconfiguratie

Gebruik de volgende trefwoordargumenten bij het instantiëren van een client om versleuteling te configureren:

  • require_encryption (bool): als deze is ingesteld op True, wordt afgedwongen dat objecten worden versleuteld en ontsleuteld.
  • encryption_version (str): hiermee geeft u de versie van de versleuteling op die moet worden gebruikt. De huidige opties zijn '2.0' of '1.0' en de standaardwaarde is '1.0'. Versie 1.0 is afgeschaft en het wordt ten zeerste aanbevolen om versie 2.0 te gebruiken.
  • key_encryption_key (object): de door de gebruiker verstrekte sleutel-versleutelingssleutel. Het exemplaar moet de volgende methoden implementeren:
    • wrap_key(key)--verpakt de opgegeven sleutel met behulp van een algoritme naar keuze van de gebruiker.
    • get_key_wrap_algorithm()--retourneert het algoritme dat wordt gebruikt om de opgegeven symmetrische sleutel te verpakken.
    • get_kid()--retourneert een tekenreekssleutel-id voor deze sleutel-versleutelingssleutel.
  • key_resolver_function (aanroepbaar): de door de gebruiker opgegeven sleutel resolver. Hiermee wordt de tekenreeks kid gebruikt om een sleutel-versleutelingssleutel te retourneren die de hierboven gedefinieerde interface implementeert.

Andere client/configuratie per bewerking

Andere optionele trefwoordargumenten voor configuratie die kunnen worden opgegeven op de client of per bewerking.

Argumenten voor clientwoorden:

  • connection_timeout (int): het aantal seconden dat de client wacht om verbinding te maken met de server. De standaardwaarde is 20 seconden.
  • read_timeout (int): het aantal seconden dat de client tussen opeenvolgende leesbewerkingen wacht op een antwoord van de server. Dit is een time-out op socketniveau en wordt niet beïnvloed door de totale gegevensgrootte. Time-outs voor lezen aan de clientzijde worden automatisch opnieuw geprobeerd. De standaardwaarde is 60 seconden.
  • transport (alle): door de gebruiker opgegeven transport om de HTTP-aanvraag te verzenden.

Trefwoordargumenten per bewerking:

  • raw_response_hook (aanroepbaar): de opgegeven callback maakt gebruik van het antwoord dat is geretourneerd door de service.
  • raw_request_hook (aanroepbaar): de opgegeven callback maakt gebruik van de aanvraag voordat deze naar de service wordt verzonden.
  • client_request_id (str): optioneel door de gebruiker opgegeven identificatie van de aanvraag.
  • user_agent (str): voegt de aangepaste waarde toe aan de header user-agent die met de aanvraag moet worden verzonden.
  • logging_enable (bool): hiermee schakelt u logboekregistratie in op het niveau VAN FOUTOPSPORING. Standaard ingesteld op False. Kan ook worden doorgegeven op clientniveau om deze in te schakelen voor alle aanvragen.
  • logging_body (bool): hiermee schakelt u logboekregistratie van de aanvraag- en antwoordtekst in. Standaard ingesteld op False. Kan ook worden doorgegeven op clientniveau om deze in te schakelen voor alle aanvragen.
  • headers (dict): geef aangepaste headers door als sleutel, waardeparen. Bijvoorbeeld. headers={'CustomValue': value}

Problemen oplossen

Algemeen

Storage Blob-clients genereren uitzonderingen die zijn gedefinieerd in Azure Core.

Deze lijst kan worden gebruikt ter referentie om opgetreden uitzonderingen te ondervangen. Als u de specifieke foutcode van de uitzondering wilt ophalen, gebruikt u het error_code kenmerk, dat wil zeggen exception.error_code.

Logboekregistratie

Deze bibliotheek maakt gebruik van de standaardbibliotheek voor logboekregistratie voor logboekregistratie. Basisinformatie over HTTP-sessies (URL's, headers, enzovoort) wordt geregistreerd op INFO-niveau.

Gedetailleerde logboekregistratie op foutopsporingsniveau, inclusief aanvraag-/antwoordteksten en niet-bewerkte headers, kan worden ingeschakeld op een client met het logging_enable argument:

import sys
import logging
from azure.storage.blob import BlobServiceClient

# Create a logger for the 'azure.storage.blob' SDK
logger = logging.getLogger('azure.storage.blob')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# This client will log detailed information about its HTTP sessions, at DEBUG level
service_client = BlobServiceClient.from_connection_string("your_connection_string", logging_enable=True)

Op dezelfde manier kan logging_enable logboekregistratie voor één bewerking inschakelen, zelfs wanneer dit niet is ingeschakeld voor de client:

service_client.get_service_stats(logging_enable=True)

Volgende stappen

Meer voorbeeldcode

Ga aan de slag met onze Blob-voorbeelden.

Er zijn verschillende Python SDK-voorbeelden voor Opslagblobs beschikbaar in de GitHub-opslagplaats van de SDK. Deze voorbeelden bevatten voorbeeldcode voor aanvullende scenario's die vaak worden aangetroffen tijdens het werken met Storage-blobs:

  • blob_samples_container_access_policy.py (asynchrone versie): voorbeelden voor het instellen van toegangsbeleid:

    • Toegangsbeleid voor container instellen

  • blob_samples_hello_world.py (asynchrone versie): voorbeelden voor algemene Storage Blob-taken:

    • Een container instellen
    • Een blok-, pagina- of toevoeg-blob maken
    • Blobs uploaden
    • Blobs downloaden
    • Blobs verwijderen

  • blob_samples_authentication.py (asynchrone versie): voorbeelden voor het verifiëren en maken van de client:

    • Vanuit een verbindingsreeks
    • Vanuit een gedeelde toegangssleutel
    • Vanuit een shared access signature-token
    • Vanuit Active Directory

  • blob_samples_service.py (asynchrone versie): voorbeelden voor interactie met de blobservice:

    • Accountgegevens ophalen
    • Service-eigenschappen ophalen en instellen
    • Servicestatistieken ophalen
    • Containers maken, weergeven en verwijderen
    • De blob- of containerclient ophalen

  • blob_samples_containers.py (asynchrone versie): voorbeelden voor interactie met containers:

    • Een container maken en containers verwijderen
    • Metagegevens instellen voor containers
    • Containereigenschappen ophalen
    • Een lease voor een container verkrijgen
    • Een toegangsbeleid instellen voor een container
    • Blobs in container uploaden, weergeven en verwijderen
    • De blobclient laten communiceren met een specifieke blob

  • blob_samples_common.py (asynchrone versie): voorbeelden die voor alle typen blobs gelden:

    • Een momentopname maken
    • Een blob-momentopname verwijderen
    • Een blob voorlopig verwijderen
    • De verwijdering van een blob ongedaan maken
    • Een lease verkrijgen voor een blob
    • Een blob kopiëren vanuit een URL

  • blob_samples_directory_interface.py : voorbeelden voor interactie met Blob Storage alsof het een map in een bestandssysteem is:

    • Eén bestand of map kopiëren (uploaden of downloaden)
    • Bestanden of mappen op één niveau of recursief weergeven
    • Eén bestand verwijderen of een map recursief verwijderen

Aanvullende documentatie

Zie de Documentatie over Azure Blob Storage op docs.microsoft.com voor uitgebreidere documentatie over Azure Blob Storage .

Bijdragen

Wij verwelkomen bijdragen en suggesties voor dit project. Voor de meeste bijdragen moet u instemmen met een licentieovereenkomst voor bijdragers (CLA: Contributor License Agreement) waarin u verklaart dat u gerechtigd bent ons het recht te geven uw bijdrage te gebruiken, en dat u dit ook doet. Ga naar https://cla.microsoft.com voor meer informatie.

Wanneer u een pull-aanvraag indient, wordt met een CLA-bot automatisch bepaald of u een CLA moet verschaffen en wordt de pull-aanvraag dienovereenkomstig opgemaakt (bijvoorbeeld met een label of commentaar). Volg gewoon de instructies van de bot. U hoeft dit maar eenmaal te doen voor alle repo's waar gebruik wordt gemaakt van onze CLA.

Op dit project is de Microsoft Open Source Code of Conduct (Microsoft Open Source-gedragscode) van toepassing. Zie voor meer informatie de veelgestelde vragen over de gedragscode of neem contact op opencode@microsoft.com met eventuele aanvullende vragen of opmerkingen.