Azure Storage Blobs-klientbibliotek för Python – version 12.19.0

  • Artikel

Azure Blob Storage är Microsofts objektlagringslösning för molnet. Blob Storage är optimerat för att lagra stora mängder ostrukturerade data, exempelvis text eller binära data.

Blob Storage är perfekt för att:

  • Leverera bilder eller dokument direkt till en webbläsare
  • Lagra filer för distribuerad åtkomst
  • Direktuppspela video och ljud
  • Lagra data för säkerhetskopiering och återställning, haveriberedskap och arkivering
  • Lagra data för analys av en tjänst som kan vara lokal eller Azure-värdbaserad

| KällkodPaket (PyPI) | Paket (Conda) | API-referensdokumentation | Produktdokumentation | Prover

Komma igång

Förutsättningar

Installera paketet

Installera Azure Storage Blobs-klientbiblioteket för Python med pip:

pip install azure-storage-blob

Skapa ett lagringskonto

Om du vill skapa ett nytt lagringskonto kan du använda Azure Portal, Azure PowerShell eller Azure CLI:

# 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

Skapa klienten

Med Azure Storage Blobs-klientbiblioteket för Python kan du interagera med tre typer av resurser: själva lagringskontot, bloblagringscontainrar och blobar. Interaktionen med dessa resurser börjar med en instans av en klient. Om du vill skapa ett klientobjekt behöver du lagringskontots blobtjänstkonto-URL och en autentiseringsuppgift som gör att du kan komma åt lagringskontot:

from azure.storage.blob import BlobServiceClient

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

Leta upp konto-URL:en

Du hittar lagringskontots blobtjänst-URL med hjälp av Azure-portalen, Azure PowerShell eller 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"

Typer av autentiseringsuppgifter

Parametern credential kan anges i ett antal olika formulär, beroende på vilken typ av auktorisering du vill använda:

  1. Om du vill använda en AAD-tokenautentisering (Azure Active Directory) anger du en instans av önskad typ av autentiseringsuppgifter som hämtats från biblioteket azure-identity . Till exempel kan DefaultAzureCredential användas för att autentisera klienten.

    Detta kräver viss inledande konfiguration:

    Använd den returnerade tokenautentiseringsuppgiften för att autentisera klienten:

        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. Om du vill använda en SAS-token (signatur för delad åtkomst) anger du token som en sträng. Om din konto-URL innehåller SAS-token utelämnar du parametern för autentiseringsuppgifter. Du kan generera en SAS-token från Azure-portalen under "Signatur för delad åtkomst" eller använda en av generate_sas() funktionerna för att skapa en SAS-token för lagringskontot, containern eller bloben:

    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. Om du vill använda en delad nyckel för lagringskontot (även kallat kontonyckel eller åtkomstnyckel) anger du nyckeln som en sträng. Du hittar det i Azure-portalen under avsnittet "Åtkomstnycklar" eller genom att köra följande Azure CLI-kommando:

    az storage account keys list -g MyResourceGroup -n MyStorageAccount

    Använd nyckeln som parameter för autentiseringsuppgifter för att autentisera klienten:

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

    Om du använder anpassad URL (vilket innebär att URL:en inte är i det här formatet <my_account_name>.blob.core.windows.net) instansierar du klienten med hjälp av autentiseringsuppgifterna nedan:

    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. Om du vill använda anonym offentlig läsåtkomst utelämnar du bara parametern för autentiseringsuppgifter.

Skapa klienten från en anslutningssträng

Beroende på ditt användningsfall och din auktoriseringsmetod kanske du föredrar att initiera en klientinstans med en lagrings-anslutningssträng i stället för att ange kontots URL och autentiseringsuppgifter separat. Det gör du genom att skicka lagrings-anslutningssträng till klientens from_connection_string klassmetod:

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)

Du hittar anslutningssträng till ditt lagringskonto i Azure-portalen under avsnittet "Åtkomstnycklar" eller genom att köra följande CLI-kommando:

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

Viktiga begrepp

Följande komponenter utgör Azure Blob Service:

  • Själva lagringskontot
  • En container i lagringskontot
  • En blob i en container

Med Azure Storage Blobs-klientbiblioteket för Python kan du interagera med var och en av dessa komponenter genom att använda ett dedikerat klientobjekt.

Klienter

Fyra olika klienter tillhandahålls för att interagera med de olika komponenterna i Blob Service:

  1. BlobServiceClient – den här klienten representerar interaktion med själva Azure-lagringskontot och gör att du kan hämta förkonfigurerade klientinstanser för att få åtkomst till containrar och blobar i. Den tillhandahåller åtgärder för att hämta och konfigurera kontoegenskaper samt lista, skapa och ta bort containrar i kontot. Om du vill utföra åtgärder på en specifik container eller blob hämtar du en klient med hjälp av get_container_client metoderna eller get_blob_client .
  2. ContainerClient – den här klienten representerar interaktion med en specifik container (som inte behöver finnas ännu) och gör att du kan hämta förkonfigurerade klientinstanser för att få åtkomst till blobarna i. Den tillhandahåller åtgärder för att skapa, ta bort eller konfigurera en container och innehåller åtgärder för att lista, ladda upp och ta bort blobarna i den. Om du vill utföra åtgärder på en specifik blob i containern hämtar du en klient med hjälp av get_blob_client metoden .
  3. BlobClient – den här klienten representerar interaktion med en specifik blob (som inte behöver finnas ännu). Den tillhandahåller åtgärder för att ladda upp, ladda ned, ta bort och skapa ögonblicksbilder av en blob, samt specifika åtgärder per blobtyp.
  4. BlobLeaseClient – den här klienten representerar låneinteraktioner med en ContainerClient eller BlobClient. Den tillhandahåller åtgärder för att hämta, förnya, släppa, ändra och bryta ett lån för en angiven resurs.

Asynkrona klienter

Det här biblioteket innehåller ett fullständigt asynkront API som stöds i Python 3.5+. Om du vill använda den måste du först installera en asynkron transport, till exempel aiohttp. Mer information finns i azure-core-dokumentationen .

Asynkrona klienter och autentiseringsuppgifter bör stängas när de inte längre behövs. Dessa objekt är asynkrona kontexthanterare och definierar asynkrona close metoder.

Blobtyper

När du har initierat en klient kan du välja mellan olika typer av blobar:

  • Blockblobar lagrar text och binära data, upp till cirka 4,75 TiB. Blockblobar består av datablock som kan hanteras individuellt
  • Tilläggsblobar består av block som blockblobar, men är optimerade för tilläggsåtgärder. Tilläggsblobar är idealiska för scenarier som loggning av data från virtuella datorer
  • Sidblobar lagrar filer med slumpmässig åtkomst upp till 8 TiB i storlek. Sidblobar lagrar VHD-filer (virtuell hårddisk) och fungerar som diskar för virtuella Azure-datorer

Exempel

Följande avsnitt innehåller flera kodfragment som täcker några av de vanligaste Storage Blob-uppgifterna, inklusive:

Observera att en container måste skapas innan du kan ladda upp eller ladda ned en blob.

Skapa en container

Skapa en container där du kan ladda upp eller ladda ned blobar.

from azure.storage.blob import ContainerClient

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

container_client.create_container()

Använda asynkron klient för att ladda upp en blob

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

Ladda upp en blob

Ladda upp en blob till din 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)

Använda asynkron klient för att ladda upp en blob

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)

Ladda ned en blob

Ladda ned en blob från din 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)

Ladda ned en blob asynkront

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)

Räkna upp blobar

Visa en lista över blobarna i containern

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

Lista blobarna asynkront

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)

Valfri konfiguration

Valfria nyckelordsargument som kan skickas på klient- och åtgärdsnivå.

Konfiguration av återförsöksprincip

Använd följande nyckelordsargument när du instansierar en klient för att konfigurera återförsöksprincipen:

  • retry_total (int): Totalt antal återförsök som ska tillåtas. Har företräde framför andra antal. Skicka in retry_total=0 om du inte vill försöka igen på begäranden. Standardvärdet är 10.
  • retry_connect (int): Hur många anslutningsrelaterade fel som ska försökas igen. Standardvärdet är 3.
  • retry_read (int): Hur många gånger läsfel ska försöka igen. Standardvärdet är 3.
  • retry_status (int): Hur många gånger du försöker igen med felaktiga statuskoder. Standardvärdet är 3.
  • retry_to_secondary (bool): Om begäran ska göras om till sekundär, om det går. Detta bör endast aktiveras för RA-GRS-konton som används och potentiellt inaktuella data kan hanteras. Standardvärdet är False.

Krypteringskonfiguration

Använd följande nyckelordsargument när du instansierar en klient för att konfigurera kryptering:

  • require_encryption (bool): Om värdet är True framtvingar det att objekt krypteras och dekrypterar dem.
  • encryption_version (str): Anger vilken version av krypteringen som ska användas. Aktuella alternativ är '2.0' eller '1.0' och standardvärdet är '1.0'. Version 1.0 är inaktuell och vi rekommenderar starkt att du använder version 2.0.
  • key_encryption_key (objekt): Den nyckelkrypteringsnyckel som tillhandahålls av användaren. Instansen måste implementera följande metoder:
    • wrap_key(key)--wraps den angivna nyckeln med hjälp av en algoritm som användaren väljer.
    • get_key_wrap_algorithm()--returnerar algoritmen som används för att omsluta den angivna symmetriska nyckeln.
    • get_kid()--returnerar ett strängnyckel-ID för nyckelkrypteringsnyckeln.
  • key_resolver_function (anropbar): Nyckelmatcharen från användaren. Använder barnsträngen för att returnera en nyckelkrypteringsnyckel som implementerar gränssnittet som definierats ovan.

Annan klient/per åtgärd-konfiguration

Andra valfria nyckelordsargument för konfiguration som kan anges på klienten eller per åtgärd.

Argument för klientnyckelord:

  • connection_timeout (int): Antalet sekunder som klienten väntar på att upprätta en anslutning till servern. Standardvärdet är 20 sekunder.
  • read_timeout (int): Antalet sekunder som klienten väntar, mellan efterföljande läsåtgärder, på ett svar från servern. Det här är en tidsgräns på socketnivå och påverkas inte av den totala datastorleken. Tidsgränser för läsning på klientsidan görs automatiskt på nytt. Standardvärdet är 60 sekunder.
  • transport (alla): Transport som tillhandahålls av användaren för att skicka HTTP-begäran.

Nyckelordsargument per åtgärd:

  • raw_response_hook (anropsbar): Det angivna återanropet använder svaret som returneras från tjänsten.
  • raw_request_hook (anropsbar): Det angivna återanropet använder begäran innan den skickas till tjänsten.
  • client_request_id (str): Valfri användare har angett identifiering av begäran.
  • user_agent (str): Lägger till det anpassade värdet i user-agent-huvudet som ska skickas med begäran.
  • logging_enable (bool): Aktiverar loggning på felsökningsnivå. Standardvärdet är False. Kan också skickas in på klientnivå för att aktivera det för alla begäranden.
  • logging_body (bool): Aktiverar loggning av begärande- och svarstexten. Standardvärdet är False. Kan också skickas in på klientnivå för att aktivera det för alla begäranden.
  • headers (dict): Skicka in anpassade rubriker som nyckel, värdepar. E.g. headers={'CustomValue': value}

Felsökning

Allmänt

Storage Blob-klienter genererar undantag som definierats i Azure Core.

Den här listan kan användas som referens för att fånga undantag som genereras. Om du vill hämta den specifika felkoden för undantaget använder du error_code attributet , t.ex exception.error_code. .

Loggning

Det här biblioteket använder standardloggningsbiblioteket för loggning. Grundläggande information om HTTP-sessioner (URL:er, rubriker osv.) loggas på INFO-nivå.

Detaljerad loggning på FELSÖKNINGsnivå, inklusive begärande-/svarskroppar och oredigerade huvuden, kan aktiveras på en klient med logging_enable argumentet :

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)

logging_enable På samma sätt kan aktivera detaljerad loggning för en enda åtgärd, även om den inte är aktiverad för klienten:

service_client.get_service_stats(logging_enable=True)

Nästa steg

Mer exempelkod

Kom igång med våra blobexempel.

Flera Python SDK-exempel för Storage Blobs är tillgängliga för dig på SDK:s GitHub-lagringsplats. De här exemplen innehåller exempelkod för ytterligare scenarier som ofta påträffas när du arbetar med Lagringsblobar:

  • blob_samples_container_access_policy.py (asynkron version) – Exempel för att ange åtkomstprinciper:

    • Konfigurera åtkomstprincip för container

  • blob_samples_hello_world.py (asynkron version) – Exempel på vanliga Storage Blob-uppgifter:

    • Konfigurera en container
    • Skapa en block-, sid- eller tilläggsblob
    • Ladda upp blobar
    • Ladda ned blobbar
    • Ta bort blobar

  • blob_samples_authentication.py (asynkron version) – Exempel för att autentisera och skapa klienten:

    • Från en anslutningssträng
    • Från en delad åtkomstnyckel
    • Från en signaturtoken för delad åtkomst
    • Från Active Directory

  • blob_samples_service.py (asynkron version) – Exempel på interaktion med blobtjänsten:

    • Hämta kontoinformation
    • Hämta och ange tjänstegenskaper
    • Hämta tjänststatistik
    • Skapa, lista och ta bort containrar
    • Hämta blob- eller containerklienten

  • blob_samples_containers.py (asynkron version) – Exempel på hur du interagerar med containrar:

    • Skapa en container och ta bort containrar
    • Ange metadata för containrar
    • Hämta containeregenskaper
    • Skaffa ett lån för containern
    • Ange en åtkomstprincip för en container
    • Ladda upp, lista, ta bort blobar i container
    • Hämta blobklienten för att interagera med en specifik blob

  • blob_samples_common.py (asynkron version) – Exempel som är gemensamma för alla typer av blobar:

    • Skapa en ögonblicksbild
    • Ta bort en blobögonblicksbild
    • Mjuk borttagning av en blob
    • Ta bort en blob
    • Skaffa ett lån för en blob
    • Kopiera en blob från en URL

  • blob_samples_directory_interface.py – Exempel på interfacing med Blob Storage som om det vore en katalog i ett filsystem:

    • Kopiera (ladda upp eller ladda ned) en enda fil eller katalog
    • Visa en lista över filer eller kataloger på en enda nivå eller rekursivt
    • Ta bort en enskild fil eller ta bort en katalog rekursivt

Ytterligare dokumentation

Mer omfattande dokumentation om Azure Blob Storage finns i Azure Blob Storage-dokumentationen om docs.microsoft.com.

Bidra

Det här projektet välkomnar bidrag och förslag. Merparten av bidragen kräver att du godkänner ett licensavtal för bidrag, där du deklarerar att du har behörighet att bevilja oss rättigheten att använda ditt bidrag, och att du dessutom uttryckligen gör så. Mer information finns på https://cla.microsoft.com.

När du skickar en pull-förfrågan avgör en CLA-robot automatiskt om du måste tillhandahålla ett licensavtal för bidrag med lämplig PR (t.ex. etikett eller kommentar). Följ bara robotens anvisningar. Du behöver bara göra detta en gång för alla repor som använder vårt licensavtal för bidrag.

Det här projektet använder sig av Microsofts uppförandekod för öppen källkod. Mer information finns i Vanliga frågor och svar om uppförandekod eller kontakt opencode@microsoft.com med ytterligare frågor eller kommentarer.