Rychlý start: Klientská knihovna azure Blob Storage pro Python

Poznámka:

Možnost Sestavení od začátku vás provede podrobným postupem vytvoření nového projektu, instalace balíčků, psaní kódu a spuštění základní konzolové aplikace. Tento přístup se doporučuje, pokud chcete porozumět všem podrobnostem, které se týkají vytvoření aplikace, která se připojuje ke službě Azure Blob Storage. Pokud raději chcete automatizovat úlohy nasazení a začít s dokončeným projektem, zvolte Začít se šablonou.

Poznámka:

Možnost Začít se šablonou pomocí Azure Developer CLI automatizuje úlohy nasazení a začne s dokončeným projektem. Tento přístup se doporučuje, pokud chcete kód prozkoumat co nejrychleji, aniž byste museli procházet úlohy nastavení. Pokud dáváte přednost podrobným pokynům k sestavení aplikace, zvolte Sestavit od začátku.

Začínáme s klientskou knihovnou služby Azure Blob Storage pro Python pro správu objektů blob a kontejnerů

V tomto článku provedete instalaci balíčku a vyzkoušení ukázkového kódu pro základní úlohy.

V tomto článku pomocí Azure Developer CLI nasadíte prostředky Azure a spustíte dokončenou konzolovou aplikaci pomocí několika příkazů.

Referenční dokumentace k API | Knihovní zdrojový kód | Balíček (PyPi) | Ukázky

Toto video ukazuje, jak začít používat klientskou knihovnu Azure Blob Storage pro Python.

Kroky ve videu jsou popsané také v následujících částech.

Požadavky

Nastavení

Tato část vás provede přípravou projektu pro práci s klientskou knihovnou Azure Blob Storage pro Python.

Vytvoření projektu

Vytvořte aplikaci v Pythonu s názvem blob-quickstart.

  1. V okně konzoly (například PowerShell nebo Bash) vytvořte pro projekt nový adresář:

    mkdir blob-quickstart

  2. Přepněte do nově vytvořeného adresáře blob-quickstart :

    cd blob-quickstart

Instalace balíčků

Z adresáře projektu nainstalujte balíčky pro klientské knihovny Azure Blob Storage a Azure Identity pomocí příkazu pip install. Potřebujete balíček azure-identity pro připojení bez hesla ke službám Azure.

pip install azure-storage-blob azure-identity

Nastavení architektury aplikace

V adresáři projektu vytvořte základní strukturu aplikace pomocí následujícího postupu:

  1. Otevřete nový textový soubor v editoru kódu.
  2. Přidejte import příkazy, vytvořte strukturu programu a zahrňte základní zpracování výjimek, jak je znázorněno v následujícím příkladu.
  3. Uložte nový soubor jako blob_quickstart.py v adresáři 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)

Když nainstalujete Azure Rozhraní příkazového řádku pro vývojáře, můžete vytvořit účet úložiště a spustit ukázkový kód pomocí několika příkazů. Projekt můžete spustit v místním vývojovém prostředí nebo v devContaineru.

Inicializace šablony Azure Developer CLI a nasazení prostředků

Z prázdného adresáře pomocí těchto kroků inicializujete azd šablonu, zřídíte prostředky Azure a začnete s kódem:

  • Naklonujte prostředky úložiště pro rychlý start z GitHubu a inicializujte šablonu místně:

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

    Zobrazí se výzva k zadání následujících informací:

    • Název prostředí: Azure Developer CLI používá tuto hodnotu jako předponu pro všechny prostředky Azure, které vytváří. Název musí být jedinečný pro všechna předplatná Azure a musí mít délku 3 až 24 znaků. Název může obsahovat pouze číslice a malá písmena.

  • Přihlaste se k Azure:

    azd auth login

  • Zprovoznění a nasazení prostředků v Azure:

    azd up

    Zobrazí se výzva k zadání následujících informací:

    • Předplatné: Předplatné Azure, do kterého jsou vaše prostředky nasazené.
    • Umístění: Oblast Azure, ve které jsou vaše prostředky nasazené.

    Dokončení nasazení může trvat několik minut. Výstup příkazu azd up obsahuje název nově vytvořeného účtu úložiště, který budete potřebovat později ke spuštění kódu.

Spuštění ukázkového kódu

V tuto chvíli jste nasadili prostředky do Azure a kód je téměř připravený ke spuštění. Pomocí těchto kroků nainstalujte balíčky, aktualizujte název účtu úložiště v kódu a spusťte ukázkovou konzolovou aplikaci:

  • Install packages: V místním adresáři nainstalujte balíčky pro klientské knihovny Azure Blob Storage a Azure Identity spuštěním následujícího příkazu: pip install azure-storage-blob azure-identity
  • Aktualizujte název účtu úložiště: V místním adresáři upravte soubor s názvem blob_quickstart.py. <storage-account-name> Vyhledejte zástupný symbol a nahraďte ho skutečným názvem účtu úložiště vytvořeného příkazemazd up. Uložte změny.
  • Spusťte projekt: Spuštěním následujícího příkazu spusťte aplikaci: python blob_quickstart.py.
  • Prohlédněte si výstup: Tato aplikace vytvoří testovací soubor ve složce místních dat a nahraje ho do kontejneru v účtu úložiště. Příklad pak vypíše objekty blob v kontejneru a stáhne soubor s novým názvem, abyste mohli porovnat staré a nové soubory.

Další informace o tom, jak ukázkový kód funguje, najdete v příkladech kódu.

Po dokončení testování kódu se podívejte do části Vyčištění prostředků a odstraňte prostředky vytvořené příkazem azd up .

Objektový model

Azure Blob Storage je optimalizovaná pro ukládání obrovských objemů nestrukturovaných dat. Nestrukturovaná data jsou data, která neodpovídají žádnému konkrétnímu datovému modelu nebo definici, jako jsou textová nebo binární data. Blob Storage nabízí tři typy prostředků:

  • Účet úložiště
  • Kontejner v účtu úložiště
  • Objekt blob v kontejneru

Následující diagram znázorňuje vztah mezi těmito prostředky:

Snímek obrazovky architektury úložiště objektů blob, na kterém jsou zobrazeny účet úložiště, kontejner a objekty blob.

K interakci s těmito prostředky použijte následující třídy Pythonu:

  • BlobServiceClient: Pomocí třídy BlobServiceClient můžete pracovat s prostředky Azure Storage a kontejnery objektů blob.
  • ContainerClient: Pomocí třídy ContainerClient můžete pracovat s kontejnery Azure Storage a jejich objekty blob.
  • BlobClient: K práci s objekty blob Azure Storage použijte třídu BlobClient.

Příklady kódu

Tyto ukázkové fragmenty kódu ukazují, jak provádět následující úlohy s klientskou knihovnou služby Azure Blob Storage pro Python:

Poznámka:

Šablona Azure Developer CLI obsahuje soubor s ukázkovým kódem, který už je zavedený. Následující příklady obsahují podrobnosti pro každou část vzorového kódu. Šablona implementuje doporučenou metodu ověřování bez hesla, jak je popsáno v části Ověřování v Azure . Metoda připojovacího řetězce se uvádí jako alternativní volba, ale není použita v šabloně a nedoporučuje se pro produkční prostředí.

Ověřování v Azure a autorizace přístupu k datům objektů blob

Žádosti aplikací do služby Azure Blob Storage musí být autorizované. Použití třídy poskytované klientskou knihovnou Azure Identity je doporučeným přístupem k implementaci bezheslové připojení ke službám Azure ve vašem kódu, včetně Blob Storage.

Žádosti o službu Azure Blob Storage můžete také autorizovat pomocí přístupového klíče účtu. Tento přístup by však měl být používán s opatrností. Vývojáři musí být opatrní, aby nikdy nezveřejnili přístupový klíč v nezabezpečeném místě. Každý, kdo má přístupový klíč, může autorizovat požadavky na účet úložiště a efektivně má přístup ke všem datům. DefaultAzureCredential nabízí vylepšené výhody správy a zabezpečení oproti klíči účtu, které umožňují ověřování bez hesla. Obě možnosti jsou demonstrována v následujícím příkladu.

DefaultAzureCredential podporuje více metod ověřování a určuje, kterou metodu použít za běhu. Tento přístup umožňuje vaší aplikaci používat různé metody ověřování v různých prostředích (místní a produkční) bez implementace kódu specifického pro prostředí.

V jakém pořadí a v jakých umístěních DefaultAzureCredential hledá přihlašovací údaje, najdete v přehledu knihovny Azure Identity.

Vaše aplikace se například může ověřit pomocí přihlašovacích údajů Azure CLI při místním vývoji. Vaše aplikace pak může po nasazení do Azure použít managed identity. Pro tento přechod nejsou vyžadovány žádné změny kódu.

Přiřazení rolí k uživatelskému účtu Microsoft Entra

Při místním vývoji se ujistěte, že uživatelský účet, který přistupuje k datům objektů blob, má správná oprávnění. K čtení a zápisu dat objektů blob budete potřebovat Storage Blob Data Contributor. Abyste mohli tuto roli přiřadit sami sobě, musíte mít přiřazenou roli Správce uživatelských přístupů nebo jinou roli, která zahrnuje akci Microsoft.Authorization/roleAssignments/write . Role Azure RBAC můžete uživateli přiřadit pomocí webu Azure Portal, Azure CLI nebo Azure PowerShellu. Další informace o roli Přispěvatel dat v objektech blob služby Storage najdete v tématu Přispěvatel dat objektů blob služby Storage. Další informace o dostupných oborech pro přiřazení rolí najdete v tématu Vysvětlení oboru pro Azure RBAC.

V tomto scénáři přiřadíte oprávnění k vašemu uživatelskému účtu, která budou omezena na účet úložiště, abyste postupovali podle zásady nejnižších oprávnění. Tento postup poskytuje uživatelům jenom minimální potřebná oprávnění a vytváří bezpečnější produkční prostředí.

Následující příklad přiřadí roli Přispěvatel dat služby Storage Blob k vašemu uživatelskému účtu, která umožňuje čtení a zápis k blobům ve vašem účtu úložiště.

Důležité

Ve většině případů bude trvat minutu nebo dvě, než se přiřazení role rozšíří v Azure, ale ve výjimečných případech může trvat až osm minut. Pokud při prvním spuštění kódu dojde k chybám ověřování, chvíli počkejte a zkuste to znovu.

  1. Na webu Azure Portal vyhledejte svůj účet úložiště pomocí hlavního panelu hledání nebo levé navigace.

  2. Na stránce přehledu účtu úložiště v nabídce vlevo vyberte Řízení přístupu (IAM ).

  3. Na stránce Řízení přístupu (IAM) vyberte kartu Přiřazení rolí.

  4. V horní nabídce vyberte + Přidat a potom přidejte přiřazení role z výsledné rozevírací nabídky.

    Snímek obrazovky znázorňující, jak přiřadit roli

  5. Pomocí vyhledávacího pole vyfiltrujte výsledky podle požadované role. V tomto příkladu vyhledejte Přispěvatel dat objektů blob služby Storage a vyberte odpovídající výsledek a pak zvolte Další.

  6. V části Přiřadit přístup vyberte Uživatel, skupina nebo instanční objekt a pak zvolte + Vybrat členy.

  7. V dialogovém okně vyhledejte své uživatelské jméno Microsoft Entra (obvykle vaše user@domain e-mailová adresa) a pak v dolní části dialogového okna zvolte Vybrat .

  8. Vyberte Zkontrolovat a přiřadit, abyste přešli na poslední stránku, a poté znovu Zkontrolovat a přiřadit, abyste proces dokončili.

Přihlášení a připojení kódu aplikace k Azure pomocí DefaultAzureCredential

Pokud chcete autorizovat přístup k datům v účtu úložiště, postupujte následovně:

  1. Ujistěte se, že jste ověřeni pomocí stejného účtu Microsoft Entra, ke kterému jste přiřadili roli k účtu úložiště. Ověřování můžete provést prostřednictvím Azure CLI, editoru Visual Studio Code nebo Azure PowerShellu.

    Přihlaste se k Azure přes Azure CLI pomocí následujícího příkazu:

    az login

  2. Pokud chcete použít DefaultAzureCredential, ujistěte se, že je nainstalovaný balíček azure-identity a že je naimportovaná třída:

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

  3. Přidejte tento kód do try bloku. Když kód běží na místní pracovní stanici, DefaultAzureCredential použije k ověření vůči Azure přihlašovací údaje vývojáře z upřednostňovaného nástroje, ke kterému jste přihlášeni. Mezi příklady těchto nástrojů patří Azure CLI nebo 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. Aktualizujte název účtu úložiště v identifikátoru URI vašeho objektu BlobServiceClient. Název účtu úložiště najdete na stránce přehledu portálu Azure.

    Screenshot stránky portálu Azure se zvýrazněním názvu účtu úložiště.

    Poznámka:

    Při nasazení do Azure může stejný kód autorizovat požadavky na Azure Storage z aplikace spuštěné v Azure. V aplikaci ale musíte povolit spravovanou identitu v Azure. Pak nakonfigurujte účet úložiště tak, aby se tato spravovaná identita mohla připojit. Podrobné pokyny ke konfiguraci tohoto připojení mezi službami Azure najdete v kurzu ověřování z aplikací hostovaných v Azure.

Vytvoření kontejneru

V účtu úložiště vytvořte nový kontejner zavoláním metody create_container objektu blob_service_client . V tomto příkladu kód připojí k názvu kontejneru hodnotu GUID, aby se zajistilo, že je jedinečný.

Přidejte tento kód na konec 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)

Další informace o vytváření kontejneru a prozkoumání dalších ukázek kódu najdete v tématu Vytvoření kontejneru objektů blob pomocí Pythonu.

Důležité

Názvy kontejnerů musí být malými písmeny. Další informace o pojmenování kontejnerů a objektů blob najdete v tématu Názvy kontejnerů, objektů blob a metadat a odkazování na ně.

Nahrání objektů blob do kontejneru

Nahrajte objekt blob do kontejneru pomocí upload_blob. Ukázkový kód vytvoří textový soubor v místním datovém adresáři pro nahrání do kontejneru.

Přidejte tento kód na konec 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)

Další informace o nahrávání objektů blob a prozkoumání dalších ukázek kódu najdete v tématu Nahrání objektu blob pomocí Python.

Seznamte blobů v kontejneru

Vylistujte objekty blob v kontejneru pomocí list_blobs. V tomto případě se do kontejneru přidal jenom jeden objekt blob, takže operace výpisu vrátí jenom tento jeden objekt blob.

Přidejte tento kód na konec 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)

Další informace o výpisu objektů blob a prozkoumání dalších ukázek kódu najdete v tématu Seznamy objektů blob pomocí Python.

Stáhnout objekty blob

Stáhněte dříve vytvořený objekt blob voláním metody download_blob . Ukázkový kód přidá k názvu souboru příponu DOWNLOAD, abyste viděli oba soubory v místním systému souborů.

Přidejte tento kód na konec 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())

Další informace o stahování objektů blob a prozkoumání dalších ukázek kódu najdete v tématu Stažení objektu blob pomocí Pythonu.

Odstranění kontejneru

Následující kód vyčistí prostředky vytvořené aplikací odebráním celého kontejneru pomocí metody delete_container . Pokud chcete, můžete také odstranit místní soubory.

Aplikace se pozastaví pro vstup uživatele voláním input() před odstraněním objektu blob, kontejneru a místních souborů. Před odstraněním ověřte, že se prostředky správně vytvořily.

Přidejte tento kód na konec 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")

Další informace o odstranění kontejneru a prozkoumání dalších ukázek kódu najdete v tématu Delete a obnovení kontejneru objektů blob pomocí Python.

Spuštění kódu

Tato aplikace vytvoří testovací soubor ve vaší místní složce a nahraje ho do služby Azure Blob Storage. Příklad pak vypíše objekty blob v kontejneru a stáhne soubor pod novým jménem. Můžete porovnat staré a nové soubory.

Přejděte do adresáře obsahujícího soubor blob_quickstart.py a spuštěním následujícího python příkazu spusťte aplikaci:

python blob_quickstart.py

Výstup aplikace je podobný následujícímu příkladu (hodnoty UUID vynechané pro čitelnost):

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

Než začnete s procesem čištění, zkontrolujte , jestli složka dat obsahuje dva soubory. Můžete je porovnat a zjistit, že jsou identické.

Vyčištění prostředků

Po ověření souborů a dokončení testování stisknutím klávesy Enter odstraňte testovací soubory spolu s kontejnerem, který jste vytvořili v účtu úložiště. K odstranění prostředků můžete také použít Azure CLI.

Po dokončení tohoto rychlého startu vyčistěte prostředky, které jste vytvořili spuštěním následujícího příkazu:

azd down

Zobrazí se výzva k potvrzení odstranění prostředků. Potvrďte akci zadáním y .

Další krok

Ukázky a příručky pro vývojáře pro Azure Storage pro Python

  • Last updated on