Azure Storage Blobs ügyfélkódtár Pythonhoz – 12.19.0-s verzió
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 használatához Python 3.7 vagy újabb verzió szükséges. További részletekért olvassa el az Azure SDK for Python verziótámogatási szabályzatát ismertető oldalt.
- A csomag használatához Azure-előfizetéssel és Azure Storage-fiókkal kell rendelkeznie.
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:
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 azure-identity telepítése
- Új AAD-alkalmazás regisztrálása és engedélyek megadása az Azure Storage eléréséhez
- Hozzáférés biztosítása az Azure Blob-adatokhoz RBAC-vel az Azure Portalon
- Állítsa be az AAD-alkalmazás ügyfélazonosítójának, bérlőazonosítójának és titkos ügyfélkulcsának értékeit környezeti változókként: AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET
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 )
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)
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.net
van), 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>"})
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:
- 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ódusokget_container_client
használatával. - 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. - 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.
- BlobLeaseClient – ez az ügyfél az a
ContainerClient
vagyBlobClient
a 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_code
a 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.
Azure SDK for Python