Klientská knihovna Azure Storage Blobs pro Python – verze 12.19.0

  • Článek

Azure Blob Storage je řešení úložiště objektů pro cloud od Microsoftu. Blob Storage je optimalizované pro ukládání velkých objemů nestrukturovaných dat, jako jsou textová nebo binární data.

Blob Storage je ideální pro:

  • poskytování obrázků nebo dokumentů přímo do prohlížeče
  • Ukládání souborů pro distribuovaný přístup
  • Streamování videa a zvuku
  • Ukládání dat pro zálohování a obnovování, zotavení po havárii a pro archivaci
  • Ukládání dat, která bude analyzovat místní nebo v Azure hostovaná služba

Zdrojový kód | Balíček (PyPI) | Balíček (Conda) | Referenční dokumentace k | rozhraní APIDokumentace k | produktuVzorky

Začínáme

Požadavky

Instalace balíčku

Nainstalujte klientskou knihovnu Azure Storage Blobs pro Python pomocí pipu:

pip install azure-storage-blob

Vytvoření účtu úložiště

Pokud chcete vytvořit nový účet úložiště, můžete použít Azure Portal, Azure PowerShell nebo 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

Vytvoření klienta

Klientská knihovna Azure Storage Blobs pro Python umožňuje interakci se třemi typy prostředků: se samotným účtem úložiště, kontejnery úložiště objektů blob a objekty blob. Interakce s těmito prostředky začíná instancí klienta. K vytvoření objektu klienta budete potřebovat adresu URL účtu služby Blob Service úložiště a přihlašovací údaje, které vám umožní přístup k účtu úložiště:

from azure.storage.blob import BlobServiceClient

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

Vyhledání adresy URL účtu

Adresu URL služby blob účtu úložiště najdete pomocí webu Azure Portal, Azure PowerShell nebo 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"

Typy přihlašovacích údajů

Parametr credential může být poskytnut v několika různých formách v závislosti na typu autorizace , kterou chcete použít:

  1. Pokud chcete použít přihlašovací údaje tokenu Azure Active Directory (AAD), zadejte instanci požadovaného typu přihlašovacích údajů získaného z knihovny azure-identity . Například DefaultAzureCredential se dá použít k ověření klienta.

    To vyžaduje počáteční nastavení:

    K ověření klienta použijte vrácené přihlašovací údaje tokenu:

        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. Pokud chcete použít token sdíleného přístupového podpisu (SAS), zadejte ho jako řetězec. Pokud adresa URL vašeho účtu obsahuje token SAS, parametr credential vyněžte. Token SAS můžete vygenerovat z webu Azure Portal v části Sdílený přístupový podpis nebo můžete použít některou z generate_sas() funkcí k vytvoření tokenu SAS pro účet úložiště, kontejner nebo objekt 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. Pokud chcete použít sdílený klíč účtu úložiště (neboli přístupový klíč účtu), zadejte tento klíč jako řetězec. Najdete ho na webu Azure Portal v části Přístupové klíče nebo spuštěním následujícího příkazu Azure CLI:

    az storage account keys list -g MyResourceGroup -n MyStorageAccount

    K ověření klienta použijte klíč jako parametr přihlašovacích údajů:

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

    Pokud používáte přizpůsobenou adresu URL (což znamená, že adresa URL není v tomto formátu <my_account_name>.blob.core.windows.net), vytvořte instanci klienta pomocí následujících přihlašovacích údajů:

    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. Pokud chcete použít anonymní veřejný přístup pro čtení, jednoduše vyněžte parametr přihlašovacích údajů.

Vytvoření klienta ze připojovací řetězec

V závislosti na vašem případu použití a metodě autorizace můžete raději inicializovat instanci klienta s připojovací řetězec úložiště, než zadat adresu URL účtu a přihlašovací údaje samostatně. Provedete to tak, že předáte připojovací řetězec úložiště metodě třídy klientafrom_connection_string:

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)

Připojovací řetězec k vašemu účtu úložiště najdete na webu Azure Portal v části Přístupové klíče nebo spuštěním následujícího příkazu rozhraní příkazového řádku:

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

Klíčové koncepty

Službu Azure Blob Service tvoří následující komponenty:

  • Samotný účet úložiště
  • Kontejner v rámci účtu úložiště
  • Objekt blob v kontejneru

Klientská knihovna Azure Storage Blobs pro Python umožňuje interakci s každou z těchto komponent pomocí vyhrazeného objektu klienta.

Klienti

K dispozici jsou čtyři různí klienti pro interakci s různými komponentami služby Blob Service:

  1. BlobServiceClient – tento klient představuje interakci se samotným účtem úložiště Azure a umožňuje získat předkonfigurované instance klientů pro přístup ke kontejnerům a objektům blob v rámci. Poskytuje operace pro načtení a konfiguraci vlastností účtu a také výpis, vytvoření a odstranění kontejnerů v rámci účtu. Pokud chcete provádět operace s konkrétním kontejnerem nebo objektem blob, načtěte klienta pomocí get_container_client metod nebo get_blob_client .
  2. ContainerClient – tento klient představuje interakci s konkrétním kontejnerem (který ještě nemusí existovat) a umožňuje získat předkonfigurované instance klienta pro přístup k objektům blob v rámci. Poskytuje operace pro vytvoření, odstranění nebo konfiguraci kontejneru a zahrnuje operace pro výpis, nahrání a odstranění objektů blob v něm. Pokud chcete provádět operace s konkrétním objektem blob v rámci kontejneru, načtěte klienta pomocí get_blob_client metody .
  3. BlobClient – tento klient představuje interakci s konkrétním objektem blob (který ještě nemusí existovat). Poskytuje operace pro nahrávání, stahování, odstraňování a vytváření snímků objektu blob a také konkrétní operace podle typu objektu blob.
  4. BlobLeaseClient – tento klient představuje interakce zapůjčení s ContainerClient nebo BlobClient. Poskytuje operace pro získání, obnovení, vydání, změnu a přerušení zapůjčení zadaného prostředku.

Asynchronní klienti

Tato knihovna obsahuje kompletní asynchronní rozhraní API podporované v Pythonu 3.5 a novějším. Abyste ho mohli používat, musíte nejprve nainstalovat asynchronní přenos, například aiohttp. Další informace najdete v dokumentaci k azure-core .

Asynchronní klienti a přihlašovací údaje by se měli zavřít, když už nejsou potřeba. Tyto objekty jsou asynchronní kontextové manažery a definují asynchronní close metody.

Typy objektů blob

Po inicializaci klienta si můžete vybrat z různých typů objektů blob:

  • Objekty blob bloku ukládají textová a binární data až do velikosti přibližně 4,75 TiB. Objekty blob bloku se skládají z bloků dat, které je možné spravovat jednotlivě.
  • Doplňovací objekty blob se skládají z bloků, jako jsou objekty blob bloku, ale jsou optimalizované pro operace připojení. Doplňovací objekty blob jsou ideální pro scénáře, jako je protokolování dat z virtuálních počítačů.
  • Objekty blob stránky ukládají soubory s náhodným přístupem o velikosti až 8 TiB. Objekty blob stránky ukládají soubory virtuálního pevného disku (VHD) a slouží jako disky pro virtuální počítače Azure.

Příklady

V následujících částech najdete několik fragmentů kódu, které pokrývají některé nejběžnější úlohy objektů blob služby Storage, mezi které patří:

Upozorňujeme, že před nahráním nebo stažením objektu blob je potřeba vytvořit kontejner.

Vytvoření kontejneru

Vytvořte kontejner, ze kterého můžete nahrávat nebo stahovat objekty blob.

from azure.storage.blob import ContainerClient

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

container_client.create_container()

Použití asynchronního klienta k nahrání objektu 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()

Nahrání objektu blob

Nahrání objektu blob do kontejneru

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)

Použití asynchronního klienta k nahrání objektu 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)

Stažení objektu blob

Stažení objektu blob z kontejneru

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)

Asynchronní stažení objektu 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("./BlockDestination.txt", "wb") as my_blob:
    stream = await blob.download_blob()
    data = await stream.readall()
    my_blob.write(data)

Výčet objektů blob

Výpis objektů blob v kontejneru

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

Asynchronní výpis objektů blob

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)

Volitelná konfigurace

Volitelné argumenty klíčových slov, které je možné předat na úrovni klienta a na úrovni jednotlivých operací.

Konfigurace zásad opakování

Při vytváření instance klienta ke konfiguraci zásad opakování použijte následující argumenty klíčových slov:

  • retry_total (int): Celkový počet opakovaných pokusů, které se mají povolit. Má přednost před ostatními počty. retry_total=0 Pokud nechcete opakovat pokusy o žádosti, předejte je. Výchozí hodnota je 10.
  • retry_connect (int): Kolik chyb souvisejících s připojením se má opakovat. Výchozí hodnota je 3.
  • retry_read (int): Kolikrát se má opakovat pokus o chyby čtení. Výchozí hodnota je 3.
  • retry_status (int): Kolikrát se má opakovat chybný stavový kód. Výchozí hodnota je 3.
  • retry_to_secondary (bool): Jestli se má žádost opakovat na sekundární, pokud je to možné. Tato možnost by měla být povolená jenom u účtů RA-GRS a je možné zpracovávat potenciálně zastaralá data. Výchozí hodnota je False.

Konfigurace šifrování

Při vytváření instance klienta ke konfiguraci šifrování použijte následující argumenty klíčových slov:

  • require_encryption (bool): Pokud je nastavená hodnota True, vynutí, aby objekty byly zašifrované a dešifrovaly je.
  • encryption_version (str): Určuje verzi šifrování, která se má použít. Aktuální možnosti jsou '2.0' nebo '1.0' a výchozí hodnota je '1.0'. Verze 1.0 je zastaralá a důrazně doporučujeme používat verzi 2.0.
  • key_encryption_key (objekt): Klíč-šifrování-klíč zadaný uživatelem. Instance musí implementovat následující metody:
    • wrap_key(key)--zabalí zadaný klíč pomocí algoritmu podle volby uživatele.
    • get_key_wrap_algorithm()--vrátí algoritmus použitý k zabalení zadaného symetrického klíče.
    • get_kid()--vrátí ID klíče řetězce pro tento klíč-encryption-key.
  • key_resolver_function (volatelné): Překladač klíčů zadaný uživatelem. Použije řetězec kid k vrácení klíče-encryption-key implementuje rozhraní definované výše.

Konfigurace jiného klienta nebo operace

Další volitelné argumenty klíčového slova konfigurace, které lze zadat v klientovi nebo pro každou operaci.

Argumenty klíčových slov klienta:

  • connection_timeout (int): Počet sekund, po které bude klient čekat na navázání připojení k serveru. Výchozí hodnota je 20 sekund.
  • read_timeout (int): Počet sekund, po které bude klient čekat mezi po sobě jdoucími operacemi čtení na odpověď ze serveru. Jedná se o časový limit na úrovni soketů, který nemá vliv na celkovou velikost dat. Automaticky se budou opakovat časové limity čtení na straně klienta. Výchozí hodnota je 60 sekund.
  • transport (Any): Přenos poskytnutý uživatelem k odeslání požadavku HTTP.

Argumenty klíčových slov pro jednotlivé operace:

  • raw_response_hook (volatelné): Dané zpětné volání použije odpověď vrácenou službou.
  • raw_request_hook (volatelné): Dané zpětné volání použije požadavek před odesláním do služby.
  • client_request_id (str): Nepovinný uživatel zadal identifikaci požadavku.
  • user_agent (str): Připojí vlastní hodnotu k hlavičce uživatelského agenta, která se má odeslat spolu s požadavkem.
  • logging_enable (bool): Povolí protokolování na úrovni LADĚNÍ. Výchozí hodnota je False. Můžete ho také předat na úrovni klienta, abyste ho povolili pro všechny požadavky.
  • logging_body (bool): Povolí protokolování textu požadavku a odpovědi. Výchozí hodnota je False. Můžete ho také předat na úrovni klienta, abyste ho povolili pro všechny požadavky.
  • headers (dict): Předejte vlastní hlavičky jako klíče a páry hodnot. Např. headers={'CustomValue': value}

Poradce při potížích

Obecné

Klienti objektů blob služby Storage vyvolávají výjimky definované v Azure Core.

Tento seznam lze použít jako referenci k zachycení vyvolaných výjimek. Pokud chcete získat konkrétní kód chyby výjimky, použijte error_code atribut , exception.error_codetj. .

protokolování

Tato knihovna používá pro protokolování standardní knihovnu protokolování . Základní informace o relacích HTTP (adresy URL, hlavičky atd.) se protokolují na úrovni INFO.

Podrobné protokolování úrovně LADĚNÍ, včetně těl požadavků/odpovědí a nereagovaných hlaviček, je možné povolit na klientovi s argumentem logging_enable :

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)

Podobně logging_enable může povolit podrobné protokolování pro jednu operaci, i když není povolené pro klienta:

service_client.get_service_stats(logging_enable=True)

Další kroky

Další ukázkový kód

Začněte s našimi ukázkami objektů blob.

Několik ukázek sady Python SDK pro objekty blob služby Storage je k dispozici v úložišti sady SDK Na GitHubu. Tyto ukázky poskytují příklad kódu pro další scénáře, se kterými se běžně setkáváme při práci s objekty blob služby Storage:

  • blob_samples_container_access_policy.py (asynchronní verze) – příklady nastavení zásad přístupu:

    • Nastavení zásad přístupu pro kontejner

  • blob_samples_hello_world.py (asynchronní verze) – příklady běžných úloh objektů blob služby Storage:

    • Nastavení kontejneru
    • Vytvoření objektu blob bloku, stránky nebo doplňování
    • Nahrání objektů blob
    • Stáhnout objekty blob
    • Odstraňovat objekty blob

  • blob_samples_authentication.py (asynchronní verze) – příklady ověřování a vytvoření klienta:

    • Z připojovací řetězec
    • Ze sdíleného přístupového klíče
    • Z tokenu sdíleného přístupového podpisu
    • Z active directory

  • blob_samples_service.py (asynchronní verze) – příklady pro interakci se službou Blob Service:

    • Získání informací o účtu
    • Získání a nastavení vlastností služby
    • Získání statistik služby
    • Vytvoření, výpis a odstranění kontejnerů
    • Získání klienta objektu blob nebo kontejneru

  • blob_samples_containers.py (asynchronní verze) – příklady pro interakci s kontejnery:

    • Vytvoření kontejneru a odstranění kontejnerů
    • Nastavení metadat v kontejnerech
    • Získání vlastností kontejneru
    • Získání zapůjčení kontejneru
    • Nastavení zásad přístupu pro kontejner
    • Nahrání, výpis a odstranění objektů blob v kontejneru
    • Získání klienta objektu blob k interakci s konkrétním objektem blob

  • blob_samples_common.py (asynchronní verze) – příklady společné pro všechny typy objektů blob:

    • Vytvoření snímku
    • Odstranění snímku objektu blob
    • Obnovitelné odstranění objektu blob
    • Zrušení obnovení objektu blob
    • Získání zapůjčení objektu blob
    • Zkopírování objektu blob z adresy URL

  • blob_samples_directory_interface.py – příklady propojení se službou Blob Storage, jako by to byl adresář v systému souborů:

    • Kopírování (nahrání nebo stažení) jednoho souboru nebo adresáře
    • Výpis souborů nebo adresářů na jedné úrovni nebo rekurzivně
    • Odstranění jednoho souboru nebo rekurzivní odstranění adresáře

Další dokumentace

Rozsáhlejší dokumentaci ke službě Azure Blob Storage najdete v dokumentaci ke službě Azure Blob Storage na docs.microsoft.com.

Přispívání

Tento projekt vítá příspěvky a návrhy. Většina příspěvků vyžaduje souhlas s licenční smlouvou s přispěvatelem (CLA), která stanoví, že máte právo udělit nám práva k používání vašeho příspěvku a skutečně tak činíte. Podrobnosti najdete tady: https://cla.microsoft.com

Při odesílání žádosti o přijetí změn robot CLA automaticky určí, jestli je potřeba poskytnout smlouvu CLA, a příslušným způsobem žádost o přijetí změn upraví (např. přidáním jmenovky nebo komentáře). Stačí postupovat podle pokynů robota. Pro všechna úložiště používající naši smlouvu CLA to stačí udělat jenom jednou.

Tento projekt přijal pravidla chování pro Microsoft Open Source. Další informace najdete v nejčastějších dotazech k pravidlům chování nebo se obraťte na opencode@microsoft.com případné další dotazy nebo komentáře.