Udostępnij za pośrednictwem

Biblioteka klienta obiektów blob usługi Azure Storage dla języka Python — wersja 12.19.0

  • Artykuł

Azure Blob Storage to rozwiązanie do magazynowania obiektów w chmurze firmy Microsoft. Usługa Blob Storage jest zoptymalizowana pod kątem przechowywania olbrzymich ilości danych bez struktury, takich jak dane tekstowe lub binarne.

Usługa Blob Storage to idealne rozwiązanie w następujących przypadkach:

  • Obsługiwanie obrazów i dokumentów bezpośrednio w przeglądarce
  • Przechowywanie plików do dostępu rozproszonego
  • Przesyłanie strumieniowe audio i wideo
  • Przechowywanie danych do wykonywania kopii zapasowych, przywracania, odzyskiwania po awarii i archiwizowania
  • Przechowywanie danych w celu analizy w usłudze lokalnej lub hostowanej na platformie Azure

Kod | źródłowyPakiet (PyPI) | Pakiet (Conda) | Dokumentacja referencyjna interfejsu | APIDokumentacja | produktuPróbki

Wprowadzenie

Wymagania wstępne

Instalowanie pakietu

Zainstaluj bibliotekę klienta obiektów blob usługi Azure Storage dla języka Python za pomocą narzędzia pip:

pip install azure-storage-blob

Tworzenie konta magazynu

Jeśli chcesz utworzyć nowe konto magazynu, możesz użyć witryny Azure Portal, Azure PowerShell lub interfejsu wiersza polecenia platformy Azure:

# 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

Tworzenie klienta

Biblioteka klienta obiektów blob usługi Azure Storage dla języka Python umożliwia interakcję z trzema typami zasobów: samym kontem magazynu, kontenerami magazynu obiektów blob i obiektami blob. Interakcja z tymi zasobami rozpoczyna się od wystąpienia klienta. Aby utworzyć obiekt klienta, musisz mieć adres URL konta usługi blob magazynu oraz poświadczenia umożliwiające dostęp do konta magazynu:

from azure.storage.blob import BlobServiceClient

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

Szukanie adresu URL konta

Adres URL usługi blob konta magazynu można znaleźć za pomocą witryny Azure Portal, Azure PowerShell lub interfejsu wiersza polecenia platformy Azure:

# 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 poświadczeń

Parametr credential może być podany w wielu różnych formularzach w zależności od typu autoryzacji , którego chcesz użyć:

  1. Aby użyć poświadczeń tokenu usługi Azure Active Directory (AAD), podaj wystąpienie żądanego typu poświadczeń uzyskanego z biblioteki azure-identity . Na przykład wartość DefaultAzureCredential może służyć do uwierzytelniania klienta.

    Wymaga to konfiguracji początkowej:

    Użyj zwróconego poświadczenia tokenu, aby uwierzytelnić klienta:

        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. Aby użyć tokenu sygnatury dostępu współdzielonego (SAS), podaj token jako ciąg. Jeśli adres URL konta zawiera token SAS, pomiń parametr poświadczeń. Token sygnatury dostępu współdzielonego można wygenerować w witrynie Azure Portal w obszarze "Sygnatura dostępu współdzielonego" lub użyć jednej z generate_sas() funkcji do utworzenia tokenu sas dla konta magazynu, kontenera lub obiektu 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. Aby użyć klucza współużytkowanego konta magazynu (klucza konta lub klucza dostępu), podaj klucz jako ciąg. Można to znaleźć w witrynie Azure Portal w sekcji "Klucze dostępu" lub uruchamiając następujące polecenie interfejsu wiersza polecenia platformy Azure:

    az storage account keys list -g MyResourceGroup -n MyStorageAccount

    Użyj klucza jako parametru poświadczeń, aby uwierzytelnić klienta:

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

    Jeśli używasz dostosowanego adresu URL (co oznacza, że adres URL nie jest w tym formacie <my_account_name>.blob.core.windows.net), utwórz wystąpienie klienta przy użyciu poniższego poświadczenia:

    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. Aby użyć anonimowego publicznego dostępu do odczytu, po prostu pomiń parametr poświadczeń.

Tworzenie klienta na podstawie parametry połączenia

W zależności od przypadku użycia i metody autoryzacji wolisz zainicjować wystąpienie klienta przy użyciu parametry połączenia magazynu zamiast oddzielnie podać adres URL konta i poświadczenia. W tym celu przekaż parametry połączenia magazynu do metody klasy 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)

Parametry połączenia konta magazynu można znaleźć w witrynie Azure Portal w sekcji "Klucze dostępu" lub uruchamiając następujące polecenie interfejsu wiersza polecenia:

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

Kluczowe pojęcia

Następujące składniki składają się na usługę Azure Blob Service:

  • Samo konto magazynu
  • Kontener na koncie magazynu
  • Obiekt blob w kontenerze

Biblioteka klienta obiektów blob usługi Azure Storage dla języka Python umożliwia interakcję z każdym z tych składników za pomocą dedykowanego obiektu klienta.

Klienci

Czterech różnych klientów jest dostarczanych do interakcji z różnymi składnikami usługi Blob Service:

  1. BlobServiceClient — ten klient reprezentuje interakcję z samym kontem usługi Azure Storage i umożliwia uzyskanie wstępnie skonfigurowanych wystąpień klienta w celu uzyskania dostępu do kontenerów i obiektów blob w obrębie programu . Zapewnia ona operacje pobierania i konfigurowania właściwości konta, a także listy, tworzenia i usuwania kontenerów w ramach konta. Aby wykonać operacje na określonym kontenerze lub obiekcie blob, pobierz klienta przy użyciu get_container_client metod lub get_blob_client .
  2. ContainerClient — ten klient reprezentuje interakcję z określonym kontenerem (który jeszcze nie istnieje) i umożliwia uzyskanie wstępnie skonfigurowanych wystąpień klienta w celu uzyskania dostępu do obiektów blob w ramach programu . Zapewnia ona operacje tworzenia, usuwania lub konfigurowania kontenera oraz obejmuje operacje wyświetlania, przekazywania i usuwania w nim obiektów blob. Aby wykonać operacje na określonym obiekcie blob w kontenerze, pobierz klienta przy użyciu get_blob_client metody .
  3. BlobClient — ten klient reprezentuje interakcję z określonym obiektem blob (który nie musi jeszcze istnieć). Zapewnia ona operacje przekazywania, pobierania, usuwania i tworzenia migawek obiektu blob, a także określonych operacji na typ obiektu blob.
  4. BlobLeaseClient — ten klient reprezentuje interakcje dzierżawy z obiektem ContainerClient lub BlobClient. Zapewnia ona operacje uzyskiwania, odnawiania, wydawania, zmieniania i przerywania dzierżawy dla określonego zasobu.

Klienci asynchroniczny

Ta biblioteka zawiera kompletny asynchroniczny interfejs API obsługiwany w języku Python 3.5 lub nowszym. Aby go używać, należy najpierw zainstalować transport asynchroniczny, taki jak aiohttp. Aby uzyskać więcej informacji, zobacz dokumentację platformy azure-core .

Klienci asynchroniczne i poświadczenia powinny być zamykane, gdy nie są już potrzebne. Te obiekty są menedżerami kontekstu asynchronicznego i definiują metody asynchroniczne close .

Typy obiektów blob

Po zainicjowaniu klienta możesz wybrać spośród różnych typów obiektów blob:

  • Blokowe obiekty blob przechowują dane tekstowe i binarne do około 4,75 TiB. Blokowe obiekty blob składają się z bloków danych, którymi można zarządzać indywidualnie
  • Uzupełnialne obiekty blob również składają się z bloków, podobnie jak blokowe obiekty blob, lecz są zoptymalizowane pod kątem operacji dołączania. Uzupełnialne obiekty blob są idealne w scenariuszach, takich jak rejestrowanie danych z maszyn wirtualnych
  • Stronicowe obiekty blob przechowują pliki dostępu losowego o rozmiarze do 8 TiB. Stronicowe obiekty blob przechowują pliki wirtualnego dysku twardego (VHD) i służą jako dyski dla maszyn wirtualnych platformy Azure

Przykłady

Poniższe sekcje zawierają kilka fragmentów kodu obejmujących niektóre z najbardziej typowych zadań obiektu blob usługi Storage, w tym:

Należy pamiętać, że kontener należy utworzyć przed przekazaniem lub pobraniem obiektu blob.

Tworzenie kontenera

Utwórz kontener, z którego można przekazywać lub pobierać obiekty blob.

from azure.storage.blob import ContainerClient

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

container_client.create_container()

Przekazywanie obiektu blob za pomocą klienta asynchronicznego

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

Przekazywanie obiektu blob

Przekazywanie obiektu blob do kontenera

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)

Przekazywanie obiektu blob za pomocą klienta asynchronicznego

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)

Pobieranie obiektu blob

Pobieranie obiektu blob z kontenera

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)

Asynchroniczne pobieranie obiektu 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)

Wyliczanie obiektów blob

Wyświetlanie listy obiektów blob w kontenerze

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

Asynchroniczna lista obiektów 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)

Konfiguracja opcjonalna

Opcjonalne argumenty słów kluczowych, które można przekazać na poziomie klienta i na poziomie operacji.

Konfiguracja zasad ponawiania prób

Użyj następujących argumentów słów kluczowych podczas tworzenia wystąpienia klienta, aby skonfigurować zasady ponawiania prób:

  • retry_total (int): całkowita liczba ponownych prób do zezwolenia. Ma pierwszeństwo przed innymi liczbami. Przekaż polecenie , retry_total=0 jeśli nie chcesz ponowić próby na żądaniach. Wartość domyślna to 10.
  • retry_connect (int): ile błędów związanych z połączeniem należy ponowić próbę. Wartość domyślna to 3.
  • retry_read (int): ile razy należy ponowić próbę w przypadku błędów odczytu. Wartość domyślna to 3.
  • retry_status (int): ile razy należy ponowić próbę w przypadku nieprawidłowych kodów stanu. Wartość domyślna to 3.
  • retry_to_secondary (bool): czy żądanie powinno zostać ponowione do pomocniczej, jeśli jest możliwe. Należy włączyć tylko konta RA-GRS, a potencjalnie nieaktualne dane mogą być obsługiwane. Wartość domyślna to False.

Konfiguracja szyfrowania

Użyj następujących argumentów słów kluczowych podczas tworzenia wystąpienia klienta w celu skonfigurowania szyfrowania:

  • require_encryption (wartość logiczna): jeśli ustawiono wartość True, wymusi szyfrowanie i odszyfrowywanie obiektów.
  • encryption_version (str): określa wersję szyfrowania do użycia. Bieżące opcje to '2.0' lub '1.0' , a wartość domyślna to '1.0'. Wersja 1.0 jest przestarzała i zdecydowanie zaleca się używanie wersji 2.0.
  • key_encryption_key (obiekt): udostępniony przez użytkownika klucz-encryption-key. Wystąpienie musi zaimplementować następujące metody:
    • wrap_key(key)--opakowuje określony klucz przy użyciu wybranego algorytmu użytkownika.
    • get_key_wrap_algorithm()--zwraca algorytm używany do opakowowania określonego klucza symetrycznego.
    • get_kid()--zwraca identyfikator klucza ciągu dla tego klucza-encryption-key.
  • key_resolver_function (możliwe do wywołania): rozpoznawanie klucza dostarczonego przez użytkownika. Używa ciągu podrzędnego, aby zwrócić klucz-encryption-key implementujący interfejs zdefiniowany powyżej.

Inna konfiguracja klienta /na operację

Inne opcjonalne argumenty słowa kluczowego konfiguracji, które można określić na kliencie lub na operację.

Argumenty słów kluczowych klienta:

  • connection_timeout (int): liczba sekund oczekiwania klienta na nawiązanie połączenia z serwerem. Wartość domyślna to 20 sekund.
  • read_timeout (int): liczba sekund oczekiwania klienta między kolejnymi operacjami odczytu na odpowiedź z serwera. Jest to limit czasu na poziomie gniazda i nie ma to wpływu na ogólny rozmiar danych. Limity czasu odczytu po stronie klienta będą automatycznie ponawiane. Wartość domyślna to 60 sekund.
  • transport (dowolny): transport dostarczony przez użytkownika w celu wysłania żądania HTTP.

Argumenty słów kluczowych dla operacji:

  • raw_response_hook (możliwe do wywołania): Podane wywołanie zwrotne używa odpowiedzi zwróconej z usługi.
  • raw_request_hook (możliwe do wywołania): podane wywołanie zwrotne używa żądania przed wysłaniem do usługi.
  • client_request_id (str): opcjonalna identyfikacja żądania przez użytkownika opcjonalnego.
  • user_agent (str): dołącza wartość niestandardową do nagłówka user-agent, który ma zostać wysłany za pomocą żądania.
  • logging_enable (bool): włącza rejestrowanie na poziomie DEBUG. Wartość domyślna to False. Można również przekazać na poziomie klienta, aby włączyć je dla wszystkich żądań.
  • logging_body (bool): włącza rejestrowanie treści żądania i odpowiedzi. Wartość domyślna to False. Można również przekazać na poziomie klienta, aby włączyć je dla wszystkich żądań.
  • nagłówki (dict): przekazuj niestandardowe nagłówki jako pary klucz, wartość. Przykład. headers={'CustomValue': value}

Rozwiązywanie problemów

Ogólne

Klienci obiektów blob usługi Storage zgłaszają wyjątki zdefiniowane w usłudze Azure Core.

Ta lista może służyć do przywoływania zgłaszanych wyjątków. Aby uzyskać określony kod błędu wyjątku, użyj atrybutu error_code , exception.error_codetj. .

Rejestrowanie

Ta biblioteka używa standardowej biblioteki rejestrowania do rejestrowania. Podstawowe informacje o sesjach HTTP (adresach URL, nagłówkach itp.) są rejestrowane na poziomie INFORMACJI.

Szczegółowe rejestrowanie na poziomie DEBUG, w tym treści żądań/odpowiedzi i nieredagowanych nagłówków, można włączyć na kliencie z 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)

Podobnie może logging_enable włączyć szczegółowe rejestrowanie dla pojedynczej operacji, nawet jeśli nie jest włączone dla klienta:

service_client.get_service_stats(logging_enable=True)

Następne kroki

Więcej przykładów kodu

Rozpocznij pracę z naszymi przykładami obiektów blob.

Kilka przykładów zestawu PYTHON SDK obiektów blob usługi Storage jest dostępnych w repozytorium GitHub zestawu SDK. Te przykłady zawierają przykładowy kod dla dodatkowych scenariuszy często napotykanych podczas pracy z obiektami blob usługi Storage:

  • blob_samples_container_access_policy.py (wersja asynchroniowa) — przykłady ustawiania zasad dostępu:

    • Konfigurowanie zasad dostępu dla kontenera

  • blob_samples_hello_world.py (wersja asynchroniowa) — przykłady typowych zadań obiektów blob usługi Storage:

    • Konfigurowanie kontenera
    • Tworzenie bloku, strony lub uzupełnialnych obiektów blob
    • Przekazywanie obiektów blob
    • Pobieranie obiektów blob
    • Usuwać obiekty blob

  • blob_samples_authentication.py (wersja asynchronicka) — przykłady uwierzytelniania i tworzenia klienta:

    • Z parametry połączenia
    • Z klucza dostępu współdzielonego
    • Z tokenu sygnatury dostępu współdzielonego
    • Z usługi Active Directory

  • blob_samples_service.py (wersja asynchroniowa) — przykłady interakcji z usługą blob:

    • Pobieranie informacji o koncie
    • Pobieranie i ustawianie właściwości usługi
    • Pobieranie statystyk usługi
    • Tworzenie, wyświetlanie listy i usuwanie kontenerów
    • Pobieranie klienta obiektu blob lub kontenera

  • blob_samples_containers.py (wersja asynchroniowa) — przykłady interakcji z kontenerami:

    • Tworzenie kontenera i usuwanie kontenerów
    • Ustawianie metadanych w kontenerach
    • Pobieranie właściwości kontenera
    • Uzyskiwanie dzierżawy kontenera
    • Ustawianie zasad dostępu w kontenerze
    • Przekazywanie, wyświetlanie listy, usuwanie obiektów blob w kontenerze
    • Uzyskiwanie klienta obiektu blob do interakcji z określonym obiektem blob

  • blob_samples_common.py (wersja asynchroniowa) — przykłady typowe dla wszystkich typów obiektów blob:

    • Tworzenie migawki
    • Usuwanie migawki obiektu blob
    • Usuwanie nietrwałe obiektu blob
    • Cofanie wprowadzania obiektu blob
    • Uzyskiwanie dzierżawy obiektu blob
    • Kopiowanie obiektu blob z adresu URL

  • blob_samples_directory_interface.py — przykłady międzyfakcjonowania z usługą Blob Storage tak, jakby był to katalog w systemie plików:

    • Kopiowanie (przekazywanie lub pobieranie) pojedynczego pliku lub katalogu
    • Wyświetlanie listy plików lub katalogów na jednym poziomie lub rekursywnie
    • Usuwanie pojedynczego pliku lub rekursywnie usuwanie katalogu

Dodatkowa dokumentacja

Aby uzyskać bardziej obszerną dokumentację dotyczącą usługi Azure Blob Storage, zobacz dokumentację usługi Azure Blob Storage dotyczącą docs.microsoft.com.

Współtworzenie

W tym projekcie zachęcamy do współtworzenia i zgłaszania sugestii. Współtworzenie w większości przypadków wymaga zgody na umowę licencyjną dotyczącą współautorów (CLA, Contributor License Agreement), zgodnie z którą współautor ma prawo udzielić i faktycznie udziela nam praw do używania wytworzonej przez siebie zawartości. Aby uzyskać szczegółowe informacje, odwiedź stronę https://cla.microsoft.com.

Po przesłaniu żądania ściągnięcia robot CLA automatycznie określi, czy musisz przekazać umowę CLA, i doda odpowiednie informacje do tego żądania (na przykład etykietę czy komentarz). Po prostu postępuj zgodnie z instrukcjami robota. Wystarczy zrobić to raz dla wszystkich repozytoriów, w przypadku których jest używana nasza umowa CLA.

W tym projekcie przyjęto Kodeks postępowania oprogramowania Open Source firmy Microsoft. Aby uzyskać więcej informacji, zobacz Często zadawane pytania dotyczące kodeksu postępowania lub skontaktuj się z opencode@microsoft.com dodatkowymi pytaniami lub komentarzami.