Udostępnij za pośrednictwem

Szybki start: biblioteka klienta usługi Azure Blob Storage dla języka Python

  • Artykuł

Uwaga

Opcja Kompiluj od podstaw przeprowadzi Cię krok po kroku przez proces tworzenia nowego projektu, instalowania pakietów, pisania kodu i uruchamiania podstawowej aplikacji konsolowej. To podejście jest zalecane, jeśli chcesz zrozumieć wszystkie szczegóły związane z tworzeniem aplikacji łączącej się z usługą Azure Blob Storage. Jeśli wolisz zautomatyzować zadania wdrażania i rozpocząć od ukończonego projektu, wybierz pozycję Rozpocznij od szablonu.

Uwaga

Opcja Rozpocznij od szablonu wykorzystuje interfejs wiersza polecenia dla deweloperów platformy Azure do zautomatyzowania zadań wdrożeniowych i rozpoczęcia pracy z gotowym projektem. To podejście jest zalecane, jeśli chcesz eksplorować kod tak szybko, jak to możliwe bez przechodzenia przez zadania konfiguracji. Jeśli wolisz instrukcje krok po kroku dotyczące kompilowania aplikacji, wybierz pozycję Kompiluj od podstaw.

Rozpocznij pracę z biblioteką klienta usługi Azure Blob Storage dla języka Python, aby zarządzać obiektami blob i kontenerami.

W tym artykule wykonasz kroki, aby zainstalować pakiet i wypróbować przykładowy kod dla podstawowych zadań.

W tym artykule użyjesz Azure Developer CLI, aby wdrożyć zasoby platformy Azure i uruchomić ukończoną aplikację konsolową, używając zaledwie kilku poleceń.

Dokumentacja interfejsu API | Kod źródłowy biblioteki | Pakiet (PyPi) | Przykłady

W tym filmie wideo pokazano, jak rozpocząć korzystanie z biblioteki klienta usługi Azure Blob Storage dla języka Python.

Kroki opisane w filmie wideo zostały również opisane w poniższych sekcjach.

Wymagania wstępne

Konfigurowanie

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

Tworzenie projektu

Utwórz aplikację w języku Python o nazwie blob-quickstart.

  1. W oknie konsoli (takim jak PowerShell lub Bash) utwórz nowy katalog na potrzeby projektu.

    mkdir blob-quickstart

  2. Przejdź do nowo utworzonego katalogu blob-quickstart

    cd blob-quickstart

Instalowanie pakietów

Z katalogu projektu zainstaluj pakiety dla bibliotek klienta usługi Azure Blob Storage i usługi Azure Identity 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

Konfigurowanie struktury aplikacji

W katalogu projektu wykonaj kroki, aby utworzyć podstawową strukturę aplikacji:

  1. Otwórz nowy plik tekstowy w edytorze kodu.
  2. Dodaj import instrukcje, zbuduj strukturę programu i uwzględnij podstawową obsługę wyjątków, jak pokazano poniżej.
  3. Zapisz nowy plik jako blob_quickstart.py w katalogu blob-quickstart .
import os, uuid
from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient, BlobClient, ContainerClient

try:
    print("Azure Blob Storage Python quickstart sample")

    # Quickstart code goes here

except Exception as ex:
    print('Exception:')
    print(ex)

Po zainstalowaniu Azure Developer CLI możesz utworzyć konto magazynu i uruchomić przykładowy kod za pomocą kilku poleceń. Projekt można uruchomić w lokalnym środowisku deweloperskim lub w usłudze DevContainer.

Inicjowanie szablonu interfejsu wiersza polecenia dewelopera platformy Azure i wdrażanie zasobów

W pustym katalogu wykonaj następujące kroki, aby zainicjować azd szablon, aprowizować zasoby platformy Azure i rozpocząć pracę z kodem:

  • Sklonuj zasoby repozytorium szybkiego startu z usługi GitHub i zainicjuj szablon lokalnie:

    azd init --template blob-storage-quickstart-python

    Zostanie wyświetlony monit o podanie następujących informacji:

    • Nazwa środowiska: ta wartość jest używana jako prefiks dla wszystkich zasobów platformy Azure utworzonych przez interfejs wiersza polecenia dewelopera platformy Azure. Nazwa musi być unikatowa we wszystkich subskrypcjach platformy Azure i musi mieć długość od 3 do 24 znaków. Nazwa może zawierać tylko cyfry i małe litery.

  • Zaloguj się do platformy Azure:

    azd auth login

  • Aprowizuj i wdróż zasoby na platformie Azure:

    azd up

    Zostanie wyświetlony monit o podanie następujących informacji:

    • Subskrypcja: Subskrypcja platformy Azure, do którego są wdrażane twoje zasoby.
    • Lokalizacja: region świadczenia usługi Azure, w którym są wdrażane zasoby.

    Ukończenie wdrożenia może potrwać kilka minut. Dane wyjściowe polecenia azd up zawierają nazwę nowo utworzonego konta magazynu, które będzie potrzebne później do uruchomienia kodu.

Uruchamianie przykładowego kodu

Na tym etapie zasoby są wdrażane na platformie Azure, a kod jest prawie gotowy do uruchomienia. Wykonaj następujące kroki, aby zainstalować pakiety, zaktualizować nazwę konta magazynu w kodzie oraz uruchomić przykładową aplikację konsolową.

  • Zainstaluj pakiety: w katalogu lokalnym zainstaluj pakiety dla bibliotek klienta usługi Azure Blob Storage i azure Identity przy użyciu następującego polecenia: pip install azure-storage-blob azure-identity
  • Zaktualizuj nazwę konta magazynu: w katalogu lokalnym zmodyfikuj plik o nazwie blob_quickstart.py. Znajdź symbol zastępczy <storage-account-name> i zastąp go rzeczywistą nazwą konta magazynu utworzonego przez polecenie azd up. Zapisz zmiany.
  • Uruchom projekt: Wykonaj następujące polecenie, aby uruchomić aplikację: python blob_quickstart.py.
  • Obserwuj dane wyjściowe: Ta aplikacja tworzy plik testowy w lokalnym folderze danych i przekazuje go do kontenera na koncie magazynowym. Następnie przykład wymienia obiekty blob w kontenerze i pobiera plik z nową nazwą, aby można było je porównać ze starymi i nowymi plikami.

Aby dowiedzieć się więcej o sposobie działania przykładowego kodu, zobacz Przykłady kodu.

Po zakończeniu testowania kodu zobacz sekcję Czyszczenie zasobów , aby usunąć zasoby utworzone za azd up pomocą polecenia .

Model obiektów

Usługa Azure Blob Storage jest zoptymalizowana pod kątem przechowywania ogromnych ilości danych bez struktury. Dane bez struktury są danymi, które nie są zgodne z żadnym modelem lub definicją danych, jak na przykład dane tekstowe lub binarne. Magazyn obiektów blob oferuje trzy typy zasobów:

  • Konto magazynu
  • Kontener w koncie przechowywania
  • Obiekt blob w kontenerze

Na poniższym diagramie przedstawiono relację między tymi zasobami:

Diagram architektury magazynu obiektów blob

Użyj następujących klas języka Python, aby wchodzić w interakcje z tymi zasobami:

  • BlobServiceClient: BlobServiceClient klasa umożliwia manipulowanie zasobami usługi Azure Storage i kontenerami obiektów blob.
  • ContainerClient: ContainerClient klasa umożliwia manipulowanie kontenerami usługi Azure Storage i ich obiektami blob.
  • BlobClient: BlobClient klasa umożliwia manipulowanie obiektami blob usługi Azure Storage.

Przykłady kodu

Te przykładowe fragmenty kodu pokazują, jak wykonać następujące zadania za pomocą biblioteki klienta usługi Azure Blob Storage dla języka Python:

Uwaga

Szablon Azure Developer CLI zawiera plik z przykładowym kodem, który jest już dostępny. Poniższe przykłady zawierają szczegółowe informacje dotyczące każdej części przykładowego kodu. Szablon implementuje zalecaną metodę uwierzytelniania bez hasła zgodnie z opisem w sekcji Uwierzytelnianie na platformie Azure . Metoda ciągu połączenia jest pokazana jako alternatywa, ale nie jest używana w szablonie i nie jest zalecana do kodu produkcyjnego.

Uwierzytelnij się na platformie Azure i autoryzuj dostęp do danych obiektów blob

Żądania aplikacji do usługi Azure Blob Storage muszą być autoryzowane. DefaultAzureCredential Użycie klasy udostępnionej przez bibliotekę klienta tożsamości platformy Azure jest zalecanym podejściem do implementowania połączeń bez hasła z usługami platformy Azure w kodzie, w tym usługi Blob Storage.

Możesz również autoryzować żądania do usługi Azure Blob Storage przy użyciu klucza dostępu do konta. Należy jednak zachować ostrożność przy użyciu tego podejścia. Deweloperzy muszą być sumienni, aby nigdy nie ujawniać klucza dostępu w niezabezpieczonej lokalizacji. Każdy, kto ma klucz dostępu, może autoryzować żądania do konta magazynu i w praktyce ma dostęp do wszystkich danych. DefaultAzureCredential oferuje ulepszone korzyści związane z zarządzaniem i zabezpieczeniami za pośrednictwem klucza konta, aby umożliwić uwierzytelnianie bez hasła. Obie opcje przedstawiono w poniższym przykładzie.

DefaultAzureCredential obsługuje wiele metod uwierzytelniania i określa, która metoda powinna być używana w czasie wykonywania. Takie podejście umożliwia aplikacji używanie różnych metod uwierzytelniania w różnych środowiskach (lokalnych i produkcyjnych) bez implementowania kodu specyficznego dla środowiska.

Kolejność i lokalizacje, w których DefaultAzureCredential szuka poświadczeń, można znaleźć w przeglądzie „Azure Identity library”.

Na przykład Twoja aplikacja może uwierzytelniać się, wykorzystując poświadczenia logowania Azure CLI podczas pracy w środowisku lokalnym. Aplikacja może następnie użyć tożsamości zarządzanej po jej wdrożeniu na platformie Azure. Do tego przejścia nie są wymagane żadne zmiany kodu.

Przypisywanie ról do konta użytkownika usługi Microsoft Entra

Podczas tworzenia aplikacji lokalnie upewnij się, że konto użytkownika, które uzyskuje dostęp do danych obiektów blob, ma odpowiednie uprawnienia. Będziesz potrzebować Współautora danych obiektu Blob w usłudze Storage, aby odczytywać i zapisywać dane blob. Aby przypisać sobie tę rolę, musisz mieć przypisaną rolę Administratora dostępu użytkowników lub inną rolę obejmującą akcję Microsoft.Authorization/roleAssignments/write . Role RBAC platformy Azure można przypisać użytkownikowi przy użyciu witryny Azure Portal, interfejsu wiersza polecenia platformy Azure lub programu Azure PowerShell. Więcej informacji na temat dostępnych zakresów przypisań ról można znaleźć na stronie przeglądu zakresu.

W tym scenariuszu przypiszesz uprawnienia do Twojego konta użytkownika w zakresie konta magazynowego, aby postępować zgodnie z zasadą najniższych uprawnień. Ta praktyka zapewnia użytkownikom tylko minimalne wymagane uprawnienia i tworzy bezpieczniejsze środowiska produkcyjne.

W poniższym przykładzie do konta użytkownika zostanie przypisana rola współautora danych obiektu blob w usłudze Storage, która zapewnia zarówno dostęp do odczytu, jak i zapisu do danych obiektów blob na Twoim koncie magazynowym.

Ważne

W większości przypadków propagacja przypisania roli na platformie Azure potrwa minutę lub dwie, ale w rzadkich przypadkach może upłynąć do ośmiu minut. Jeśli podczas pierwszego uruchomienia kodu wystąpią błędy uwierzytelniania, zaczekaj chwilę i spróbuj ponownie.

  1. W portalu Azure znajdź swoje konto magazynowe, używając głównego paska wyszukiwania lub nawigacji z lewej strony.

  2. Na stronie przeglądu konta magazynu wybierz pozycję Kontrola dostępu (IAM) z menu po lewej stronie.

  3. Na stronie Kontrola dostępu (IAM) wybierz kartę Przypisania ról.

  4. Wybierz pozycję + Dodaj z górnego menu, a następnie Dodaj przypisanie roli z wyświetlonego menu rozwijanego.

    Zrzut ekranu przedstawiający sposób przypisywania roli.

  5. Użyj pola wyszukiwania, aby filtrować wyniki do żądanej roli. W tym przykładzie wyszukaj pozycję Storage Blob Data Contributor i wybierz pasujący wynik, a następnie wybierz pozycję Dalej.

  6. W obszarze Przypisz dostęp do wybierz Użytkownik, grupa lub główna nazwa usługi, a następnie wybierz + Wybierz członków.

  7. W oknie dialogowym wyszukaj nazwę użytkownika firmy Microsoft Entra (zazwyczaj adres e-mail user@domain ), a następnie wybierz pozycję Wybierz w dolnej części okna dialogowego.

  8. Wybierz pozycję Przejrzyj i przypisz , aby przejść do ostatniej strony, a następnie ponownie przejrzyj i przypisz, aby ukończyć proces.

Zaloguj się i połącz kod aplikacji z platformą Azure przy użyciu opcji DefaultAzureCredential

Dostęp do danych w koncie magazynowym można autoryzować, wykonując następujące czynności:

  1. Upewnij się, że jesteś uwierzytelniony przy użyciu tego samego konta Microsoft Entra, do którego przypisano rolę na koncie magazynu. Uwierzytelnianie można przeprowadzić za pomocą interfejsu wiersza polecenia platformy Azure, programu Visual Studio Code lub programu Azure PowerShell.

    Zaloguj się do platformy Azure za pomocą interfejsu wiersza polecenia platformy Azure przy użyciu następującego polecenia:

    az login

  2. Aby użyć DefaultAzureCredential, upewnij się, że pakiet azure-identity jest zainstalowany, a klasa zaimportowana:

    from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient

  3. Dodaj ten kod wewnątrz try bloku. Gdy kod działa na lokalnej stacji roboczej, DefaultAzureCredential używa poświadczeń dewelopera priorytetowego narzędzia, do którego logujesz się w celu uwierzytelnienia na platformie Azure. Przykłady tych narzędzi obejmują interfejs wiersza polecenia platformy Azure lub program Visual Studio Code.

    account_url = "https://<storageaccountname>.blob.core.windows.net"
default_credential = DefaultAzureCredential()

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

  4. Pamiętaj, aby zaktualizować nazwę konta magazynu w identyfikatorze URI BlobServiceClient obiektu. Nazwę konta magazynu można znaleźć na stronie przeglądu portalu Azure.

    Zrzut ekranu przedstawiający sposób znajdowania nazwy konta magazynu.

    Uwaga

    Po wdrożeniu na platformie Azure ten sam kod może służyć do autoryzowania żądań do usługi Azure Storage z aplikacji działającej na platformie Azure. Należy jednak włączyć tożsamość zarządzaną w aplikacji na platformie Azure. Następnie skonfiguruj konto magazynu, aby umożliwić nawiązywanie połączenia z tożsamością zarządzaną. Aby uzyskać szczegółowe instrukcje dotyczące konfigurowania tego połączenia między usługami platformy Azure, zobacz samouczek Uwierzytelnianie z aplikacji hostowanych na platformie Azure.

Tworzenie kontenera

Utwórz nowy kontener na koncie magazynu, wywołując metodę create_container w blob_service_client obiekcie . W tym przykładzie kod dołącza wartość identyfikatora GUID do nazwy kontenera, aby upewnić się, że jest on unikatowy.

Dodaj ten kod na końcu try bloku:

# Create a unique name for the container
container_name = str(uuid.uuid4())

# Create the container
container_client = blob_service_client.create_container(container_name)

Aby dowiedzieć się więcej o tworzeniu kontenera i eksplorować więcej przykładów kodu, zobacz Tworzenie kontenera obiektów blob przy użyciu języka Python.

Ważne

Nazwy kontenerów muszą być zapisane małymi literami. Aby uzyskać więcej informacji o nazewnictwie kontenerów i obiektów blob, zobacz temat Nazewnictwo i odwoływanie się do kontenerów, obiektów blob i metadanych.

Przekazywanie obiektów blob do kontenera

Prześlij obiekt blob do kontenera przy użyciu upload_blob. Przykładowy kod tworzy plik tekstowy w lokalnym katalogu danych w celu przekazania do kontenera.

Dodaj ten kod na końcu try bloku:

# Create a local directory to hold blob data
local_path = "./data"
os.mkdir(local_path)

# Create a file in the local data directory to upload and download
local_file_name = str(uuid.uuid4()) + ".txt"
upload_file_path = os.path.join(local_path, local_file_name)

# Write text to the file
file = open(file=upload_file_path, mode='w')
file.write("Hello, World!")
file.close()

# Create a blob client using the local file name as the name for the blob
blob_client = blob_service_client.get_blob_client(container=container_name, blob=local_file_name)

print("\nUploading to Azure Storage as blob:\n\t" + local_file_name)

# Upload the created file
with open(file=upload_file_path, mode="rb") as data:
    blob_client.upload_blob(data)

Aby dowiedzieć się więcej na temat przekazywania obiektów blob i eksplorowania dodatkowych przykładów kodu, zobacz Przekazywanie obiektu blob przy użyciu języka Python.

Wyświetlanie listy obiektów blob w kontenerze

Wyświetl listę obiektów blob w kontenerze, wywołując metodę list_blobs . W tym przypadku do kontenera został dodany tylko jeden obiekt blob, więc operacja wyświetlania listy zwraca tylko ten jeden obiekt blob.

Dodaj ten kod na końcu try bloku:

print("\nListing blobs...")

# List the blobs in the container
blob_list = container_client.list_blobs()
for blob in blob_list:
    print("\t" + blob.name)

Aby dowiedzieć się więcej na temat wyświetlania listy obiektów blob i eksplorowania większej liczby przykładów kodu, zobacz Wyświetlanie listy obiektów blob przy użyciu języka Python.

Pobieranie obiektów blob

Pobierz obiekt blob utworzony wcześniej, wywołując metodę download_blob. Przykładowy kod dodaje sufiks "DOWNLOAD" do nazwy pliku, aby zobaczyć oba pliki w lokalnym systemie plików.

Dodaj ten kod na końcu try bloku:

# Download the blob to a local file
# Add 'DOWNLOAD' before the .txt extension so you can see both files in the data directory
download_file_path = os.path.join(local_path, str.replace(local_file_name ,'.txt', 'DOWNLOAD.txt'))
container_client = blob_service_client.get_container_client(container= container_name) 
print("\nDownloading blob to \n\t" + download_file_path)

with open(file=download_file_path, mode="wb") as download_file:
 download_file.write(container_client.download_blob(blob.name).readall())

Aby dowiedzieć się więcej na temat pobierania obiektów blob i eksplorowania dodatkowych przykładów kodu, zobacz Pobieranie obiektu blob za pomocą języka Python.

Usuwanie kontenera

Poniższy kod czyści zasoby utworzone przez aplikację przez usunięcie całego kontenera przy użyciu metody delete_container . Możesz również usunąć pliki lokalne, jeśli chcesz.

Aplikacja oczekuje na dane wejściowe użytkownika, wywołując input() przed usunięciem obiektu blob, kontenera i plików lokalnych. Sprawdź, czy zasoby zostały utworzone poprawnie przed ich usunięciem.

Dodaj ten kod na końcu try bloku:

# Clean up
print("\nPress the Enter key to begin clean up")
input()

print("Deleting blob container...")
container_client.delete_container()

print("Deleting the local source and downloaded files...")
os.remove(upload_file_path)
os.remove(download_file_path)
os.rmdir(local_path)

print("Done")

Aby dowiedzieć się więcej o usuwaniu kontenera i poznać więcej przykładów kodu, zobacz Usuwanie i przywracanie kontenera obiektów blob za pomocą języka Python.

Uruchamianie kodu

Ta aplikacja tworzy plik testowy w folderze lokalnym i przekazuje go do usługi Azure Blob Storage. Przykład następnie wymienia obiekty blob w kontenerze i pobiera plik z nową nazwą. Możesz porównać stare i nowe pliki.

Przejdź do katalogu zawierającego plik blob_quickstart.py , a następnie wykonaj następujące python polecenie, aby uruchomić aplikację:

python blob_quickstart.py

Dane wyjściowe aplikacji są podobne do następujących przykładów (wartości UUID pominięte w celu zapewnienia czytelności):

Azure Blob Storage Python quickstart sample

Uploading to Azure Storage as blob:
        quickstartUUID.txt

Listing blobs...
        quickstartUUID.txt

Downloading blob to
        ./data/quickstartUUIDDOWNLOAD.txt

Press the Enter key to begin clean up

Deleting blob container...
Deleting the local source and downloaded files...
Done

Przed rozpoczęciem procesu oczyszczania sprawdź folder danych w poszukiwaniu dwóch plików. Można je porównać i zaobserwować, że są identyczne.

Czyszczenie zasobów

Po zweryfikowaniu plików i zakończeniu testowania naciśnij Enter , aby usunąć pliki testowe wraz z kontenerem utworzonym na koncie magazynu. Możesz również użyć interfejsu wiersza polecenia platformy Azure, aby usunąć zasoby.

Po zakończeniu pracy z przewodnikiem Szybki start możesz wyczyścić utworzone zasoby, uruchamiając następujące polecenie:

azd down

Zostanie wyświetlony monit o potwierdzenie usunięcia zasobów. Wprowadź , y aby potwierdzić.

Następny krok

Przykłady usługi Azure Storage i przewodniki dla deweloperów dotyczące języka Python