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

Artykuł
10/02/2024

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) | Przykłady | kodu | źródłowego biblioteki Prześlij opinię |

Wymagania wstępne

Subskrypcja platformy Azure — utwórz jedną bezpłatnie
Konto usługi Azure Storage — tworzenie konta magazynu
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 dla bibliotek klienta usługi Azure Blob Storage i tożsamości platformy Azure przy użyciu pip install polecenia . 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 asynchronicznej języka Python.

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

Zainstaluj transport asynchroniczny, taki jak aiohttp. Instalację można zainstalować aiohttp wraz z azure-storage-blob użyciem 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ć programu async with, ponieważ inni klienci utworzoni na jego podstawie współużytkować 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 obiektu blob:

azure.storage.blob.aio: zawiera klasy podstawowe, których można użyć do wykonywania operacji na usługach, kontenerach i obiektach blob asynchronicznie.

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 interakcji z zasobami danych na poziomie konta magazynu. 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 klientów 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 entra firmy Microsoft, 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 identyfikatora Entra firmy Microsoft.

Aby autoryzować za pomocą identyfikatora Entra firmy Microsoft, musisz użyć podmiotu zabezpieczeń. Jakiego typu podmiot zabezpieczeń potrzebujesz, zależy od tego, gdzie działa 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)	Jednostka 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 elementu 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 BlobServiceClient obiekt przy użyciu polecenia 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 polecenia 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 projekt używa asynchronicznych interfejsów API, utwórz wystąpienie BlobServiceClient przy użyciu polecenia 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 współdzielonego delegowania użytkowników. Sygnatura dostępu współdzielonego delegowania użytkownika jest zabezpieczona przy użyciu poświadczeń usługi Microsoft Entra zamiast klucza konta.

Aby użyć klucza współużytkowanego konta magazynu, podaj klucz jako ciąg 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 przy użyciu parametry 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 przy użyciu polecenia 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 względem konta magazynu i efektywnie 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 zasady ponawiania dla operacji klienta.
Kopiowanie obiektów blob	Skopiuj obiekt blob z jednej lokalizacji do innej.
Tworzenie kontenera	Tworzenie kontenerów obiektów blob.
Tworzenie sygnatury dostępu współdzielonego 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ę obiektu blob 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 obiektów blob	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.
Przekazywanie obiektów blob	Dowiedz się, jak przekazywać obiekty blob przy użyciu ciągów, strumieni, ścieżek plików i innych metod.

Udostępnij za pośrednictwem

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

Wymagania wstępne

konfigurowanie projektu

Programowanie asynchroniczne

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

Autoryzowanie dostępu przy użyciu elementu DefaultAzureCredential

Kompilowanie aplikacji

Opinia

Dodatkowe zasoby