Wprowadzenie do usługi Azure Blob Storage i języka Python

2025-04-07

W tym artykule pokazano, jak nawiązać połączenie z usługą Azure Blob Storage przy użyciu biblioteki klienta usługi Azure Blob Storage dla języka Python. Po nawiązaniu połączenia skorzystaj z przewodników dla deweloperów , aby dowiedzieć się, jak kod może działać na kontenerach, obiektach blob i funkcjach usługi Blob Storage.

Jeśli chcesz rozpocząć od kompletnego przykładu, zobacz Szybki start: biblioteka klienta usługi Azure Blob Storage dla języka Python.

Dokumentacja interfejsu API | Package (PyPi) | Kod źródłowy biblioteki | Przykłady | Prześlij opinię

Wymagania wstępne

Subskrypcja platformy Azure — utwórz jedną bezpłatnie
Konto usługi Azure Storage — tworzenie konta magazynu danych
Python 3.8+

konfigurowanie projektu

Ta sekcja przeprowadzi Cię przez proces przygotowywania projektu do pracy z biblioteką klienta usługi Azure Blob Storage dla języka Python.

Z katalogu projektu zainstaluj pakiety bibliotek klienta dla usługi Azure Blob Storage i tożsamości platformy Azure przy użyciu polecenia pip install. Pakiet azure-identity jest wymagany w przypadku połączeń bez hasła z usługami platformy Azure.

pip install azure-storage-blob azure-identity

Następnie otwórz plik kodu i dodaj niezbędne instrukcje importu. W tym przykładzie dodamy następujący kod do naszego pliku .py :

from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient, BlobClient, ContainerClient

Informacje o bibliotece klienta obiektów blob:

azure.storage.blob: zawiera klasy podstawowe (obiekty klienta), których można użyć do działania w usłudze, kontenerach i obiektach blob.

Programowanie asynchroniczne

Biblioteka klienta usługi Azure Blob Storage dla języka Python obsługuje zarówno synchroniczne, jak i asynchroniczne interfejsy API. Asynchroniczne interfejsy API są oparte na bibliotece asyncio języka Python.

Wykonaj następujące kroki, aby użyć asynchronicznych interfejsów API w projekcie:

Zainstaluj transport asynchroniczny, taki jak aiohttp. Można zainstalować aiohttp wraz z azure-storage-blob za pomocą opcjonalnego polecenia instalacji zależności. W tym przykładzie użyjemy następującego pip install polecenia:
```
pip install azure-storage-blob[aio]
```
Otwórz plik kodu i dodaj niezbędne instrukcje importu. W tym przykładzie dodamy następujący kod do naszego pliku .py :
```
import asyncio

from azure.identity.aio import DefaultAzureCredential
from azure.storage.blob.aio import BlobServiceClient, BlobClient, ContainerClient
```
Instrukcja import asyncio jest wymagana tylko wtedy, gdy używasz biblioteki w kodzie. Dodano ją tutaj, aby uzyskać jasność, ponieważ przykłady w artykułach z przewodnika dla deweloperów korzystają z asyncio biblioteki.
Utwórz obiekt klienta za pomocą polecenia async with , aby rozpocząć pracę z zasobami danych. Tylko klient najwyższego poziomu musi używać async with, ponieważ inni klienci utworzeni na jego podstawie współużytkują tę samą pulę połączeń. W tym przykładzie utworzymy BlobServiceClient obiekt przy użyciu metody async with, a następnie utworzymy ContainerClient obiekt:
```
async with BlobServiceClient(account_url, credential=credential) as blob_service_client:
    container_client = blob_service_client.get_container_client(container="sample-container")
```
Aby dowiedzieć się więcej, zobacz przykłady asynchroniczne w temacie Autoryzowanie dostępu i nawiązywanie połączenia z usługą Blob Storage.

Informacje o bibliotece klienta asynchronicznego dla obiektu blob:

azure.storage.blob.aio: zawiera główne klasy, które można wykorzystać do asynchronicznego wykonywania operacji na usłudze, kontenerach i obiektach blob.

Autoryzowanie dostępu i nawiązywanie połączenia z usługą Blob Storage

Aby połączyć aplikację z usługą Blob Storage, utwórz wystąpienie klasy BlobServiceClient . Ten obiekt jest punktem wyjścia do interaktywnych działań z zasobami danych na poziomie konta magazynowego. Można go użyć do działania na koncie magazynu i jego kontenerach. Możesz również użyć klienta usługi, aby utworzyć klientów kontenerów lub obiektów blob, w zależności od zasobu, z którym chcesz pracować.

Aby dowiedzieć się więcej na temat tworzenia obiektów klienta i zarządzania nimi, w tym najlepszych rozwiązań, zobacz Tworzenie obiektów klienta korzystających z zasobów danych i zarządzanie nimi.

Obiekt można autoryzować BlobServiceClient przy użyciu tokenu autoryzacji Microsoft Entra, klucza dostępu do konta lub sygnatury dostępu współdzielonego (SAS). Aby uzyskać optymalne zabezpieczenia, firma Microsoft zaleca używanie identyfikatora Entra firmy Microsoft z tożsamościami zarządzanymi w celu autoryzowania żądań względem danych obiektów blob. Aby uzyskać więcej informacji, zobacz Autoryzowanie dostępu do obiektów blob przy użyciu Microsoft Entra ID.

Aby autoryzować za pomocą Microsoft Entra ID, musisz użyć zasobu zabezpieczeń. To, jakiego typu podmiot zabezpieczeń potrzebujesz, zależy od miejsca, w którym działa Twoja aplikacja. Skorzystaj z poniższej tabeli jako przewodnika:

Gdzie działa aplikacja	Podmiot zabezpieczeń	Wskazówki
Maszyna lokalna (programowanie i testowanie)	Jednostka usługi	Aby dowiedzieć się, jak zarejestrować aplikację, skonfigurować grupę firmy Microsoft Entra, przypisać role i skonfigurować zmienne środowiskowe, zobacz Autoryzowanie dostępu przy użyciu jednostek usługi dewelopera
Maszyna lokalna (programowanie i testowanie)	Tożsamość użytkownika	Aby dowiedzieć się, jak skonfigurować grupę firmy Microsoft Entra, przypisać role i zalogować się na platformie Azure, zobacz Autoryzowanie dostępu przy użyciu poświadczeń dewelopera
Hostowane na platformie Azure	Tożsamość zarządzana	Aby dowiedzieć się, jak włączyć tożsamość zarządzaną i przypisać role, zobacz Autoryzowanie dostępu z aplikacji hostowanych na platformie Azure przy użyciu tożsamości zarządzanej
Hostowane poza platformą Azure (na przykład aplikacje lokalne)	Podmiot usługi	Aby dowiedzieć się, jak zarejestrować aplikację, przypisać role i skonfigurować zmienne środowiskowe, zobacz Autoryzowanie dostępu z aplikacji lokalnych przy użyciu jednostki usługi aplikacji

Autoryzowanie dostępu przy użyciu DefaultAzureCredential

Łatwym i bezpiecznym sposobem autoryzowania dostępu i nawiązywania połączenia z usługą Blob Storage jest uzyskanie tokenu OAuth przez utworzenie wystąpienia DefaultAzureCredential . Następnie możesz użyć tego poświadczenia, aby utworzyć obiekt BlobServiceClient .

Poniższy przykład tworzy obiekt BlobServiceClient przy użyciu DefaultAzureCredential.

def get_blob_service_client_token_credential(self):
    # TODO: Replace <storage-account-name> with your actual storage account name
    account_url = "https://<storage-account-name>.blob.core.windows.net"
    credential = DefaultAzureCredential()

    # Create the BlobServiceClient object
    blob_service_client = BlobServiceClient(account_url, credential=credential)

    return blob_service_client

Jeśli projekt używa asynchronicznych interfejsów API, utwórz wystąpienie BlobServiceClient przy użyciu async with:

# TODO: Replace <storage-account-name> with your actual storage account name
account_url = "https://<storage-account-name>.blob.core.windows.net"
credential = DefaultAzureCredential()

async with BlobServiceClient(account_url, credential=credential) as blob_service_client:
    # Work with data resources in the storage account

Aby użyć tokenu sygnatury dostępu współdzielonego (SAS), podaj token jako ciąg i zainicjuj obiekt BlobServiceClient . Jeśli adres URL konta zawiera token SAS, pomiń parametr poświadczeń.

def get_blob_service_client_sas(self, sas_token: str):
    # TODO: Replace <storage-account-name> with your actual storage account name
    account_url = "https://<storage-account-name>.blob.core.windows.net"
    # The SAS token string can be assigned to credential here or appended to the account URL
    credential = sas_token

    # Create the BlobServiceClient object
    blob_service_client = BlobServiceClient(account_url, credential=credential)

    return blob_service_client

Jeśli Twój projekt używa asynchronicznych interfejsów API, utwórz wystąpienie BlobServiceClient przy użyciu async with:

# TODO: Replace <storage-account-name> with your actual storage account name
account_url = "https://<storage-account-name>.blob.core.windows.net"

# Replace <sas_token_str> with your actual SAS token
sas_token: str = "<sas_token_str>"

async with BlobServiceClient(account_url, credential=sas_token) as blob_service_client:
    # Work with data resources in the storage account

Aby dowiedzieć się więcej na temat generowania tokenów SAS i zarządzania nimi, zobacz następujące artykuły:

Uwaga

W przypadku scenariuszy, w których są używane sygnatury dostępu współdzielonego (SAS), firma Microsoft zaleca używanie sygnatury dostępu delegowanej przez użytkownika. Delegowany SAS użytkownika jest zabezpieczony za pomocą poświadczeń Microsoft Entra, a nie klucza konta.

Aby użyć klucza współużytkowanego konta magazynu, podaj klucz w formie ciągu i zainicjuj obiekt BlobServiceClient.

def get_blob_service_client_account_key(self):
    # TODO: Replace <storage-account-name> with your actual storage account name
    account_url = "https://<storage-account-name>.blob.core.windows.net"
    shared_access_key = os.getenv("AZURE_STORAGE_ACCESS_KEY")
    credential = shared_access_key

    # Create the BlobServiceClient object
    blob_service_client = BlobServiceClient(account_url, credential=credential)

    return blob_service_client

Obiekt można również utworzyć BlobServiceClient za pomocą parametru połączenia.

def get_blob_service_client_connection_string(self):
    # TODO: Replace <storage-account-name> with your actual storage account name
    account_url = "https://<storage-account-name>.blob.core.windows.net"
    connection_string = os.getenv("AZURE_STORAGE_CONNECTION_STRING")

    # Create the BlobServiceClient object
    blob_service_client = BlobServiceClient.from_connection_string(connection_string)

    return blob_service_client

Jeśli projekt używa asynchronicznych interfejsów API, utwórz wystąpienie BlobServiceClient używając async with:

# TODO: Replace <storage-account-name> with your actual storage account name
account_url = "https://<storage-account-name>.blob.core.windows.net"

shared_access_key = os.getenv("AZURE_STORAGE_ACCESS_KEY")

async with BlobServiceClient(account_url, credential=shared_access_key) as blob_service_client:
    # Work with data resources in the storage account

Aby uzyskać informacje na temat uzyskiwania kluczy konta i wytycznych dotyczących najlepszych rozwiązań dotyczących prawidłowego zarządzania kluczami i ich ochrony, zobacz Zarządzanie kluczami dostępu do konta magazynu.

Ważne

Klucz dostępu do konta powinien być używany ostrożnie. Jeśli klucz dostępu do twojego konta zostanie utracony lub przypadkowo umieszczony w niezabezpieczonej lokalizacji, usługa może stać się podatna na zagrożenia. Każdy, kto ma klucz dostępu, może autoryzować żądania dotyczące konta magazynowego i w rzeczywistości ma dostęp do wszystkich danych. DefaultAzureCredential zapewnia ulepszone funkcje zabezpieczeń i korzyści i jest zalecanym podejściem do zarządzania autoryzacją w usługach platformy Azure.

Kompilowanie aplikacji

Podczas tworzenia aplikacji do pracy z zasobami danych w usłudze Azure Blob Storage kod wchodzi głównie w interakcję z trzema typami zasobów: kontami magazynu, kontenerami i obiektami blob. Aby dowiedzieć się więcej o tych typach zasobów, sposobie ich powiązania ze sobą i sposobie interakcji aplikacji z zasobami, zobacz Omówienie sposobu interakcji aplikacji z zasobami danych usługi Blob Storage.

W poniższych przewodnikach przedstawiono sposób uzyskiwania dostępu do danych i wykonywania określonych akcji przy użyciu biblioteki klienta usługi Azure Storage dla języka Python:

Przewodnik	opis
Konfigurowanie zasad ponawiania prób	Zaimplementuj polityki ponawiania dla operacji klienta.
Kopiuj bloby	Skopiuj dane typu blob z jednej lokalizacji do innej.
Tworzenie kontenera	Utwórz kontenery blob.
Utwórz token delegowania użytkownika	Utwórz sygnaturę dostępu współdzielonego delegowania użytkownika dla kontenera lub obiektu blob.
Tworzenie dzierżaw obiektów blob i zarządzanie nimi	Ustanów blokadę na obiekcie magazynowym i zarządzaj nią.
Tworzenie dzierżaw kontenerów i zarządzanie nimi	Ustanawianie blokady kontenera i zarządzanie nią.
Usuwanie i przywracanie obiektów blob	Usuwanie obiektów blob i przywracanie obiektów blob usuniętych nietrwale.
Usuwanie i przywracanie kontenerów	Usuwanie kontenerów i przywracanie kontenerów usuniętych nietrwale.
Pobieranie blobów	Pobierz obiekty blob przy użyciu ciągów, strumieni i ścieżek plików.
Znajdowanie obiektów blob przy użyciu tagów	Ustawianie i pobieranie tagów oraz używanie tagów do znajdowania obiektów blob.
Wyświetlanie listy obiektów blob	Wyświetlanie listy obiektów blob na różne sposoby.
Wyświetlanie listy kontenerów	Wyświetlanie listy kontenerów na koncie i różnych dostępnych opcji dostosowywania listy.
Zarządzanie właściwościami i metadanymi (obiektami blob)	Pobieranie i ustawianie właściwości i metadanych dla obiektów blob.
Zarządzanie właściwościami i metadanymi (kontenerami)	Pobieranie i ustawianie właściwości i metadanych dla kontenerów.
Dostrajanie wydajności na potrzeby transferów danych	Optymalizowanie wydajności operacji transferu danych.
Ustawianie lub zmienianie warstwy dostępu obiektu blob	Ustaw lub zmień warstwę dostępu dla blokowego obiektu blob.
Wysyłanie obiektów blob	Dowiedz się, jak przesyłać bloby przy użyciu ciągów, strumieni, ścieżek plików i innych metod.

Udostępnij za pośrednictwem