Azure Storage Blobs-clientbibliotheek voor Python - versie 12.19.0
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
- Python 3.7 of hoger is vereist voor het gebruik van dit pakket. Lees onze pagina over ondersteuningsbeleid voor Azure SDK voor Python-versies voor meer informatie.
- U moet een Azure-abonnement en een Azure-opslagaccount hebben om dit pakket te kunnen gebruiken.
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:
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:
- Azure-identity installeren
- Een nieuwe AAD-toepassing registreren en machtigingen verlenen voor toegang tot Azure Storage
- Toegang verlenen tot Azure Blob-gegevens met RBAC in Azure Portal
- Stel de waarden van de client-id, tenant-id en clientgeheim van de AAD-toepassing in als omgevingsvariabelen: AZURE_TENANT_ID, AZURE_CLIENT_ID AZURE_CLIENT_SECRET
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 )
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)
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.net
heeft), 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>"})
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:
- 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 ofget_blob_client
. - 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. - 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.
- BlobLeaseClient : deze client vertegenwoordigt lease-interacties met een
ContainerClient
ofBlobClient
. 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.
Azure SDK for Python
Feedback
https://aka.ms/ContentUserFeedback.
Binnenkort beschikbaar: In de loop van 2024 zullen we GitHub-problemen geleidelijk uitfaseren als het feedbackmechanisme voor inhoud en deze vervangen door een nieuw feedbacksysteem. Zie voor meer informatie:Feedback verzenden en weergeven voor