Azure Storage Blobs ügyfélkódtár Pythonhoz – 12.19.0-s verzió

  • Cikk

Az Azure Blob Storage a Microsoft felhőalapú objektumtárolási megoldása. A Blob Storage nagy mennyiségű strukturálatlan adat, például szöveg vagy bináris adatok tárolására van optimalizálva.

A Blob Storage a következőkhöz ideális:

  • Képek vagy dokumentumok közvetlen szolgáltatása a böngésző számára
  • Fájlok tárolása megosztott hozzáféréshez
  • Videó- és hangtartalom streamelése
  • Adattárolás biztonsági mentésekhez és helyreállításhoz, vészhelyreállításhoz és archiváláshoz
  • Adattárolás helyszíni vagy az Azure-ban üzemeltetett szolgáltatásban való elemzéshez

Forráskód | Csomag (PyPI) | Csomag (Conda) | API-referenciadokumentáció | Termékdokumentáció | Minták

Első lépések

Előfeltételek

A csomag telepítése

Telepítse a Pythonhoz készült Azure Storage Blobs ügyfélkódtárat a pip használatával:

pip install azure-storage-blob

Tárfiók létrehozása

Ha új tárfiókot szeretne létrehozni, használhatja az Azure Portalt, a Azure PowerShell vagy az Azure CLI-t:

# 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

Az ügyfél létrehozása

A Pythonhoz készült Azure Storage Blobs-ügyfélkódtár három típusú erőforrás használatát teszi lehetővé: magát a tárfiókot, a blobtárolókat és a blobokat. Ezekkel az erőforrásokkal való interakció egy ügyfélpéldánysal kezdődik. Ügyfélobjektum létrehozásához szüksége lesz a tárfiók blobszolgáltatás-fiókjának URL-címére és egy hitelesítő adatra, amely lehetővé teszi a tárfiók elérését:

from azure.storage.blob import BlobServiceClient

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

A fiók URL-címének keresése

A tárfiók blobszolgáltatásÁNAK URL-címét az Azure Portal, a Azure PowerShell vagy az Azure CLI használatával találja meg:

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

Hitelesítő adatok típusai

A credential paraméter többféle formában is megadható a használni kívánt engedély típusától függően:

  1. Az Azure Active Directory-jogkivonat hitelesítő adatainak használatához adja meg az azure-identity kódtárból beszerzett kívánt hitelesítőadat-típus egy példányát. A DefaultAzureCredential például használható az ügyfél hitelesítésére.

    Ehhez néhány kezdeti beállításra van szükség:

    Az ügyfél hitelesítéséhez használja a visszaadott jogkivonat hitelesítő adatait:

        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. Ha közös hozzáférésű jogosultságkód (SAS) jogkivonatot szeretne használni, adja meg a jogkivonatot sztringként. Ha a fiók URL-címe tartalmazza az SAS-jogkivonatot, kihagyja a hitelesítőadat-paramétert. Sas-jogkivonatot az Azure Portalról a "Közös hozzáférésű jogosultságkód" területen hozhat létre, vagy az generate_sas() egyik függvény használatával sas-jogkivonatot hozhat létre a tárfiókhoz, tárolóhoz vagy blobhoz:

    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. A tárfiók megosztott kulcsának (más néven fiókkulcsnak vagy hozzáférési kulcsnak) használatához sztringként adja meg a kulcsot. Ez az Azure Portal "Hozzáférési kulcsok" szakaszában vagy az alábbi Azure CLI-parancs futtatásával érhető el:

    az storage account keys list -g MyResourceGroup -n MyStorageAccount

    Használja a kulcsot hitelesítőadat-paraméterként az ügyfél hitelesítéséhez:

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

    Ha testre szabott URL-címet használ (ami azt jelenti, hogy az URL-cím nem ebben a formátumban <my_account_name>.blob.core.windows.netvan), példányosíthatja az ügyfelet az alábbi hitelesítő adatok használatával:

    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. A névtelen nyilvános olvasási hozzáférés használatához egyszerűen kihagyja a hitelesítőadat-paramétert.

Az ügyfél létrehozása egy kapcsolati karakterlánc

A használati esettől és az engedélyezési módszertől függően előfordulhat, hogy inkább egy ügyfélpéldányt szeretne inicializálni egy tárterülettel kapcsolati karakterlánc a fiók URL-címének és hitelesítő adatainak külön megadása helyett. Ehhez adja át a tárolási kapcsolati karakterlánc az ügyfél osztálymetódusánakfrom_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)

A tárfiókhoz kapcsolati karakterlánc az Azure Portal "Hozzáférési kulcsok" szakaszában vagy a következő PARANCSSOR-parancs futtatásával találhatja meg:

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

Fő fogalmak

A következő összetevők alkotják az Azure Blob Service-t:

  • Maga a tárfiók
  • Tároló a tárfiókban
  • Tárolón belüli blob

A Pythonhoz készült Azure Storage Blobs-ügyfélkódtár lehetővé teszi ezen összetevők használatát egy dedikált ügyfélobjektum használatával.

Ügyfelek

Négy különböző ügyfél érhető el a Blob Service különböző összetevőinek használatához:

  1. BlobServiceClient – ez az ügyfél az Azure Storage-fiókkal való interakciót jelöli, és lehetővé teszi előre konfigurált ügyfélpéldányok beszerzését a tárolók és blobok eléréséhez. Műveleteket biztosít a fióktulajdonságok lekéréséhez és konfigurálásához, valamint a fiókon belüli tárolók listázásához, létrehozásához és törléséhez. Ha egy adott tárolón vagy blobon szeretne műveleteket végezni, kérje le az ügyfelet a vagy get_blob_client metódusok get_container_client használatával.
  2. ContainerClient – ez az ügyfél egy adott tárolóval való interakciót jelöl (amelynek még nem kell léteznie), és lehetővé teszi előre konfigurált ügyfélpéldányok beszerzését a blobok eléréséhez. A tárolók létrehozásához, törléséhez vagy konfigurálásához biztosít műveleteket, és magában foglalja a benne lévő blobok listázására, feltöltésére és törlésére szolgáló műveleteket. Ha egy adott blobon szeretne műveleteket végrehajtani a tárolón belül, kérje le az ügyfelet a get_blob_client metódus használatával.
  3. BlobClient – ez az ügyfél egy adott blobgal való interakciót jelöli (amelynek még nem kell léteznie). Műveleteket biztosít a blobok feltöltéséhez, letöltéséhez, törléséhez és pillanatképek létrehozásához, valamint adott műveletek blobtípusonkénti létrehozásához.
  4. BlobLeaseClient – ez az ügyfél az a ContainerClient vagy BlobClienta bérlettel való interakciót jelöli. Műveleteket biztosít egy adott erőforrás bérletének beszerzéséhez, megújításához, kiadásához, módosításához és megszakításához.

Aszinkron ügyfelek

Ez a kódtár tartalmazza a Python 3.5+-on támogatott teljes async API-t. A használatához először telepítenie kell egy aszinkron átvitelt, például az aiohttp-t. További információért tekintse meg az Azure Core dokumentációját .

Az aszinkron ügyfeleket és a hitelesítő adatokat akkor kell bezárni, ha már nincs rájuk szükség. Ezek az objektumok aszinkron környezetkezelők, és aszinkron close metódusokat definiálnak.

Blobtípusok

Az ügyfél inicializálása után a különböző blobtípusok közül választhat:

  • A blokkblobok szöveges és bináris adatokat tárolnak, körülbelül 4,75 TiB-ig. A blokkblobok olyan adatblokkokból állnak, amelyek egyenként kezelhetők
  • A hozzáfűző blobok blokkokból, például blokkblobokból állnak, de hozzáfűzési műveletekre vannak optimalizálva. A hozzáfűző blobok ideálisak olyan forgatókönyvekhez, mint például az adatok naplózása a virtuális gépekről
  • A lapblobok legfeljebb 8 TiB méretű véletlenszerű hozzáférési fájlokat tárolnak. A lapblobok virtuális merevlemez- (VHD-) fájlokat tárolnak, és lemezként szolgálnak az Azure-beli virtuális gépekhez

Példák

A következő szakaszok számos kódrészletet biztosítanak, amelyek a leggyakoribb Storage Blob-feladatokat fedik le, többek között a következőket:

Vegye figyelembe, hogy a blob feltöltéséhez vagy letöltéséhez létre kell hozni egy tárolót.

Tároló létrehozása

Hozzon létre egy tárolót, ahonnan blobokat tölthet fel vagy tölthet le.

from azure.storage.blob import ContainerClient

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

container_client.create_container()

Blob feltöltése az aszinkron ügyfélalkalmazással

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

Blob feltöltése

Blob feltöltése a tárolóba

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)

Blob feltöltése az aszinkron ügyfélalkalmazással

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)

Blob letöltése

Blob letöltése a tárolóból

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)

Blob aszinkron letöltése

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)

Blobok számbavétele

A tárolóban lévő blobok listázása

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

A blobok aszinkron listázása

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)

Választható konfiguráció

Választható kulcsszóargumentumok, amelyek az ügyfél és a művelet szintjén is átadhatók.

Szabályzatkonfiguráció újrapróbálkozásának

Az újrapróbálkozási szabályzat konfigurálásához használja az alábbi kulcsszóargumentumokat az ügyfél példányosításakor:

  • retry_total (int): Az engedélyezni kívánt újrapróbálkozések teljes száma. Elsőbbséget élvez a többi számlálóval szemben. Jelentkezzen be retry_total=0 , ha nem szeretne újrapróbálkozni a kérésekkel. Alapértelmezés szerint 10.
  • retry_connect (int): Hány kapcsolattal kapcsolatos hiba után próbálkozzon újra. Alapértelmezés szerint 3.
  • retry_read (int): Hányszor kell újrapróbálkoznia az olvasási hibákon. Alapértelmezés szerint 3.
  • retry_status (int): Hányszor próbálkozzon újra a hibás állapotkódokkal. Alapértelmezés szerint 3.
  • retry_to_secondary (bool): Azt jelzi, hogy a kérést másodlagosra kell-e újrapróbálkozni, ha lehet. Ezt csak az RA-GRS-fiókok esetében szabad engedélyezni, és az esetlegesen elavult adatok kezelhetők. Alapértelmezés szerint a értékre van kapcsolva False.

Titkosítás konfigurálása

A titkosítás konfigurálásához használja az alábbi kulcsszóargumentumokat az ügyfél példányosításakor:

  • require_encryption (bool): Ha Igaz értékre van állítva, kényszeríti, hogy az objektumok titkosítva legyenek, és visszafejtse őket.
  • encryption_version (str): A használni kívánt titkosítási verziót adja meg. Az aktuális beállítások a vagy '2.0''1.0' az alapértelmezett érték.'1.0' Az 1.0-s verzió elavult, és erősen ajánlott a 2.0-s verzió használata.
  • key_encryption_key (objektum): A felhasználó által megadott kulcstitkosítási kulcs. A példánynak a következő módszereket kell implementálnia:
    • wrap_key(key)--a felhasználó által választott algoritmussal tördeli a megadott kulcsot.
    • get_key_wrap_algorithm()--a megadott szimmetrikus kulcs körbefuttatásához használt algoritmust adja vissza.
    • get_kid()A --visszaad egy sztringkulcs-azonosítót ehhez a kulcstitkosítási kulcshoz.
  • key_resolver_function (hívható): A felhasználó által megadott kulcsfeloldó. A gyermeksztring használatával visszaad egy kulcstitkosítási kulcsot, amely implementálja a fent definiált felületet.

Egyéb ügyfél-/műveletenkénti konfiguráció

Egyéb választható konfigurációs kulcsszóargumentumok, amelyek megadhatók az ügyfélen vagy műveletenként.

Ügyfél kulcsszóargumentumai:

  • connection_timeout (int): Az ügyfél által a kiszolgálóhoz való csatlakozásra váró másodpercek száma. Alapértelmezés szerint 20 másodperc.
  • read_timeout (int): Az ügyfél várakozási ideje az egymást követő olvasási műveletek között a kiszolgáló válaszára. Ez egy szoftvercsatornaszintű időtúllépés, és nem befolyásolja a teljes adatméret. Az ügyféloldali olvasási időtúllépések automatikusan újrapróbálkoznak. Alapértelmezés szerint 60 másodperc.
  • transport (Any): A felhasználó által megadott átvitel a HTTP-kérés elküldéséhez.

Műveletenkénti kulcsszóargumentumok:

  • raw_response_hook (hívható): Az adott visszahívás a szolgáltatástól kapott választ használja.
  • raw_request_hook (hívható): Az adott visszahívás a kérést használja, mielőtt elküldené a szolgáltatásnak.
  • client_request_id (str): A kérelem nem kötelező felhasználó által megadott azonosítója.
  • user_agent (str): Hozzáfűzi az egyéni értéket a felhasználó-ügynök fejlécéhez, amelyet a kéréssel együtt kell elküldeni.
  • logging_enable (bool): Engedélyezi a naplózást DEBUG szinten. Alapértelmezés szerint Hamis. Ügyfélszinten is átadható az összes kérés engedélyezéséhez.
  • logging_body (bool): Engedélyezi a kérés és a válasz törzsének naplózását. Alapértelmezés szerint Hamis. Ügyfélszinten is átadható az összes kérés engedélyezéséhez.
  • fejlécek (diktálás): Adja meg az egyéni fejléceket kulcsként, értékpárként. Pl. headers={'CustomValue': value}

Hibaelhárítás

Általános kérdések

A Storage Blob-ügyfelek kivételeket emelnek ki az Azure Core-ban.

Ez a lista a kidobott kivételekre való hivatkozásra használható. A kivétel adott hibakódjának lekéréséhez használja az error_code attribútumot, azaz exception.error_codea következőt: .

Naplózás

Ez a kódtár a szabványos naplózási kódtárat használja a naplózáshoz. A HTTP-munkamenetekkel (URL-címekkel, fejlécekkel stb.) kapcsolatos alapvető információk az INFO szintjén naplózva lesznek.

Részletes HIBAKERESÉSi szintű naplózás, beleértve a kérelem-/választörzseket és a nem felügyelt fejléceket, engedélyezhető egy ügyfélen az logging_enable argumentummal:

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)

Hasonlóképpen logging_enable , engedélyezheti a részletes naplózást egyetlen művelethez, még akkor is, ha nincs engedélyezve az ügyfél számára:

service_client.get_service_stats(logging_enable=True)

Következő lépések

További mintakód

Ismerkedés a blobmintákkal.

Az SDK GitHub-adattárában számos Storage Blobs Python SDK-minta érhető el. Ezek a minták példakódot biztosítanak a storage-blobok használata során gyakran előforduló további forgatókönyvekhez:

  • blob_samples_container_access_policy.py (aszinkron verzió) – Példák hozzáférési szabályzatok beállítására:

    • Hozzáférési szabályzat beállítása tárolóhoz

  • blob_samples_hello_world.py (aszinkron verzió) – Példák a gyakori Storage Blob-feladatokra:

    • Tároló beállítása
    • Blokk, oldal vagy hozzáfűző blob létrehozása
    • Blobok feltöltése
    • Blobok letöltése
    • Blobok törlése

  • blob_samples_authentication.py (aszinkron verzió) – Példák az ügyfél hitelesítésére és létrehozására:

    • Kapcsolati karakterlánc
    • Megosztott hozzáférési kulcsból
    • Megosztott hozzáférésű jogosultságkód-jogkivonatból
    • Az Active Directoryból

  • blob_samples_service.py (aszinkron verzió) – Példák a blobszolgáltatással való interakcióra:

    • Fiókadatok lekérése
    • Szolgáltatástulajdonságok lekérése és beállítása
    • Szolgáltatásstatisztikák lekérése
    • Tárolók létrehozása, listázása és törlése
    • A blob- vagy tárolóügyfél lekérése

  • blob_samples_containers.py (aszinkron verzió) – Példák tárolók használatára:

    • Tároló létrehozása és tárolók törlése
    • Metaadatok beállítása tárolókon
    • Tárolótulajdonságok lekérése
    • Bérlet beszerzése tárolón
    • Hozzáférési szabályzat beállítása tárolón
    • Blobok feltöltése, listázása, törlése a tárolóban
    • A blobügyfél lekérése egy adott blob használatához

  • blob_samples_common.py (aszinkron verzió) – Az összes blobtípusra jellemző példák:

    • Pillanatkép létrehozása
    • Blob pillanatképének törlése
    • Blob helyreállítható törlése
    • Blob leválasztása
    • Bérlet beszerzése blobon
    • Blob másolása URL-címről

  • blob_samples_directory_interface.py – Példák a Blob Storage-tal való együttműködésre, mintha egy fájlrendszer könyvtára lenne:

    • Egyetlen fájl vagy könyvtár másolása (feltöltése vagy letöltése)
    • Fájlok vagy könyvtárak listázása egyetlen szinten vagy rekurzív módon
    • Egyetlen fájl törlése vagy könyvtár rekurzív törlése

További dokumentáció

Az Azure Blob Storage részletesebb dokumentációját az Azure Blob Storage dokumentációjában találja a docs.microsoft.com.

Közreműködés

A projektben szívesen fogadjuk a hozzájárulásokat és a javaslatokat. A legtöbb hozzájáruláshoz el kell fogadnia egy Közreműködői licencszerződést (CLA-t), amelyben kijelenti, hogy jogosult arra, hogy ránk ruházza hozzájárulása felhasználási jogát, és ezt ténylegesen meg is teszi. További részletekért lásd: https://cla.microsoft.com.

A lekéréses kérelmek elküldésekor egy CLA-robot automatikusan meghatározza, hogy kell-e biztosítania CLA-t, és megfelelően kitölti a lekéréses kérelmet (például címke, megjegyzés). Egyszerűen csak kövesse a robot által megadott utasításokat. Ezt csak egyszer kell elvégeznie az összes olyan tárházban, amely a CLA-t használja.

A projekt a Microsoft nyílt forráskódú projekteket szabályozó etikai kódexe, a Microsoft Open Source Code of Conduct hatálya alá esik. További információkért lásd a viselkedési szabályzattal kapcsolatos gyakori kérdéseket , vagy vegye fel a kapcsolatot opencode@microsoft.com az esetleges további kérdésekkel vagy megjegyzésekkel.