Rychlý start: Klientská knihovna azure Blob Storage pro .NET

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.

V tomto rychlém startu se dozvíte, jak pomocí klientské knihovny Azure Blob Storage pro .NET vytvořit kontejner, nahrát a stáhnout objekty blob a vypsat objekty blob v kontejneru.

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 rozhraní API | Zdrojový kód knihovny | Balíček (NuGet) | Ukázky

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

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 .NET.

Vytvoření projektu

Vytvořte konzolovou aplikaci .NET pomocí rozhraní příkazového řádku .NET nebo sady Visual Studio 2022.

  1. V horní části Visual Studio přejděte na Soubor>New>Project.

  2. V dialogovém okně zadejte konzolovou aplikaci do vyhledávacího pole šablony projektu a vyberte první výsledek. V dolní části dialogového okna zvolte Další .

    Screenshot při vytváření nového projektu konzolové aplikace v Visual Studio.

  3. Jako název projektu zadejte BlobQuickstart. Ponechte výchozí hodnoty pro zbývající pole a vyberte Další.

  4. V Framework zkontrolujte, jestli je vybraná nejnovější nainstalovaná verze .NET. Potom zvolte Create (Vytvořit). Nový projekt se otevře v prostředí sady Visual Studio.

Nainstalujte balíček .

Pokud chcete pracovat se službou Azure Blob Storage, nainstalujte klientskou knihovnu Azure Blob Storage pro .NET.

  1. V Průzkumník řešení klikněte pravým tlačítkem myši na uzel Závislosti projektu. Vyberte Spravovat balíčky NuGet.

  2. Ve výsledném okně vyhledejte Azure.Storage.Blobs. Vyberte odpovídající výsledek a vyberte Nainstalovat.

    Screenshot instalace balíčku NuGet v Visual Studio.

Nastavení kódu aplikace

Nahraďte počáteční kód v Program.cs souboru tak, aby odpovídal následujícímu příkladu, který obsahuje nezbytné using příkazy pro toto cvičení.

using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using System;
using System.IO;

// See https://aka.ms/new-console-template for more information
Console.WriteLine("Hello, World!");

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-dotnet

    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

  • Zřízení a nasazení prostředků do 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 tomto okamžiku jste nasadili prostředky do Azure a projekt je připravený ke spuštění. Následujícím postupem aktualizujte název účtu úložiště v kódu a spusťte ukázkovou konzolovou aplikaci:

  • Aktualizujte název účtu úložiště: Přejděte do adresáře src a upravte Program.cs. <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 provedené změny.
  • Spusťte projekt: Pokud používáte Visual Studio, stisknutím klávesy F5 sestavte a spusťte kód a interagujte s konzolovou aplikací. Pokud používáte rozhraní příkazového řádku .NET, přejděte do adresáře aplikace, sestavte projekt pomocí dotnet build a spusťte aplikaci pomocí dotnet run.
  • 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 nedodržují konkrétní datový model nebo definici, jako jsou textová nebo binární data. Blob Storage nabízí tři typy prostředků:

  • Účet služby úložiště
  • Kontejner v účtu úložiště
  • Blob v kontejneru

Na následujícím diagramu jsou vztahy těchto prostředků.

Schéma architektury úložiště objektů blob.

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

  • BlobServiceClient: Pomocí třídy BlobServiceClient můžete pracovat s prostředky Azure Storage a kontejnery objektů blob.
  • BlobContainerClient: Pomocí třídy BlobContainerClient 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

Ukázkové fragmenty kódu v následujících částech ukazují, jak provádět následující úlohy s klientskou knihovnou Azure Blob Storage pro .NET:

Důležité

Ujistěte se, že nainstalujete správné balíčky NuGet a přidáte potřebné příkazy using pro ukázky kódu, které budou fungovat, jak je popsáno v části nastavení .

Poznámka:

Šablona Azure Developer CLI obsahuje projekt 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 je uvedena jako alternativa, ale v šabloně se nepoužívá a pro použití v produkčním kódu se nedoporučuje.

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 DefaultAzureCredential, kterou poskytuje klientská knihovna Azure Identity, je doporučený přístup k implementaci připojení bez hesla ke službám Azure ve vašem kódu, včetně úložiště objektů blob.

Žá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í dbát na to, aby nikdy neodhalili přístupový klíč na 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 je třída poskytovaná klientskou knihovnou Azure Identity pro .NET; další informace najdete v článku Přehled DefaultAzureCredential. DefaultAzureCredential podporuje více metod ověřování a určuje, která metoda se má 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í.

Pořadí a umístění, ve který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ů sady Visual Studio při místním vývoji. Vaše aplikace pak může používat spravovanou identitu , jakmile ji nasadíte do Azure. 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í. Pro čtení a zápis dat objektů blob v úložišti budete potřebovat roli Přispěvatel k datům objektů blob služby Storage. 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í svému uživatelskému účtu s rozsahem omezeným na účet úložiště, abyste dodrželi princip 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í vašemu uživatelskému účtu roli Přispěvatel k datům objektů blob v úložišti, která poskytuje oprávnění ke čtení i zápisu dat objektů blob 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 v zobrazené rozevírací nabídce vyberte Přidat přiřazení role.

    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 Storage Blob Data Contributor, vyberte odpovídající výsledek a potom 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, přejděte na poslední stránku a pak proces dokončete opětovným výběrem možnosti Zkontrolovat a přiřadit.

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

Přístup k datům v účtu úložiště můžete autorizovat pomocí následujícího postupu:

  1. V případě místního vývoje se ujistěte, že jste ověřeni pomocí stejného účtu Microsoft Entra, ke kterému jste přiřadili roli. Ověřování můžete provést prostřednictvím oblíbených vývojových nástrojů, jako je Azure CLI nebo Azure PowerShell. Vývojové nástroje, pomocí kterých se můžete ověřovat, se liší v různých jazycích.

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

    az login

  2. Pokud chcete balíček Azure.Identity použít DefaultAzureCredential, přidejte do své aplikace balíček Azure.Identity .

    1. V Průzkumník řešení klikněte pravým tlačítkem myši na uzel Závislosti projektu. Vyberte Spravovat balíčky NuGet.

    2. Ve výsledném okně vyhledejte Azure.Identity. Vyberte odpovídající výsledek a vyberte Nainstalovat.

      Snímek obrazovky znázorňující, jak přidat balíček identity

  3. Aktualizujte kód Program.cs tak, aby odpovídal následujícímu příkladu. Když se kód během vývoje spustí na místní pracovní stanici, použije k ověřování vůči Azure vývojářské přihlašovací údaje nástroje s nejvyšší prioritou, do kterého jste přihlášeni, například Azure CLI nebo Visual Studio.

    using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using System;
using System.IO;
using Azure.Identity;

// TODO: Replace <storage-account-name> with your actual storage account name
var blobServiceClient = new BlobServiceClient(
        new Uri("https://<storage-account-name>.blob.core.windows.net"),
        new DefaultAzureCredential());

  4. Ujistěte se, že jste aktualizovali název účtu úložiště v identifikátoru URI vašeho BlobServiceClient. Název účtu úložiště najdete na stránce přehledu webu Azure Portal.

    Snímek obrazovky znázorňující, jak najít název účtu úložiště

    Poznámka:

    Při nasazení do Azure se tento stejný kód dá použít k autorizaci požadavků na Azure Storage z aplikace spuštěné v Azure. Budete ale muset ve své aplikaci v Azure povolit spravovanou identitu. 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

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

Na konec souboru Program.cs přidejte následující kód:

// TODO: Replace <storage-account-name> with your actual storage account name
var blobServiceClient = new BlobServiceClient(
        new Uri("https://<storage-account-name>.blob.core.windows.net"),
        new DefaultAzureCredential());

//Create a unique name for the container
string containerName = "quickstartblobs" + Guid.NewGuid().ToString();

// Create the container and return a container client object
BlobContainerClient containerClient = await blobServiceClient.CreateBlobContainerAsync(containerName);

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í .NET.

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ě.

Nahrajte objekt blob do kontejneru

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

Na konec souboru Program.cs přidejte následující kód:

// Create a local file in the ./data/ directory for uploading and downloading
string localPath = "data";
Directory.CreateDirectory(localPath);
string fileName = "quickstart" + Guid.NewGuid().ToString() + ".txt";
string localFilePath = Path.Combine(localPath, fileName);

// Write text to the file
await File.WriteAllTextAsync(localFilePath, "Hello, World!");

// Get a reference to a blob
BlobClient blobClient = containerClient.GetBlobClient(fileName);

Console.WriteLine("Uploading to Blob storage as blob:\n\t {0}\n", blobClient.Uri);

// Upload data from the local file, overwrite the blob if it already exists
await blobClient.UploadAsync(localFilePath, true);

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í .NET.

Vypsat bloby v kontejneru

Vypište objekty blob v kontejneru voláním metody GetBlobsAsync.

Na konec souboru Program.cs přidejte následující kód:

Console.WriteLine("Listing blobs...");

// List all blobs in the container
await foreach (BlobItem blobItem in containerClient.GetBlobsAsync())
{
    Console.WriteLine("\t" + blobItem.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í .NET.

Stáhnout objekt blob

Stáhněte objekt blob, který jste vytvořili dříve, voláním metody DownloadToAsync . Ukázkový kód připojí řetězec "DOWNLOADED" k názvu souboru, abyste viděli oba soubory v místním systému souborů.

Na konec souboru Program.cs přidejte následující kód:

// Download the blob to a local file
// Append the string "DOWNLOADED" before the .txt extension 
// so you can compare the files in the data directory
string downloadFilePath = localFilePath.Replace(".txt", "DOWNLOADED.txt");

Console.WriteLine("\nDownloading blob to\n\t{0}\n", downloadFilePath);

// Download the blob's contents and save it to a file
await blobClient.DownloadToAsync(downloadFilePath);

Další informace o stahování objektů blob a prozkoumání dalších ukázek kódu najdete v tématu Načtěte objekt blob pomocí .NET.

Odstranění kontejneru

Následující kód vyčistí prostředky vytvořené odstraněním kontejneru pomocí deleteAsync. Příklad kódu také odstraní místní soubory, které aplikace vytvořila.

Aplikace čeká na vstup uživatele voláním Console.ReadLine před odstraněním blobu, kontejneru a místních souborů. Toto pozastavení je dobrá šance ověřit, že se prostředky vytvořily správně, než je aplikace odstraní.

Po odstranění kontejneru nemůžete vytvořit další kontejner se stejným názvem alespoň po dobu 30 sekund. Kontejner navíc nemusí být k dispozici déle než 30 sekund, pokud služba stále zpracovává požadavek. Během odstranění kontejneru se pokusí vytvořit kontejner se stejným názvem, který vygeneruje konflikt a selže se stavovým kódem 409. Služba označuje, že se kontejner odstraňuje. Všechny ostatní operace, včetně operací s jakýmikoli objekty blob v kontejneru, během odstraňování kontejneru vracejí stavový kód 404 a selžou.

Na konec souboru Program.cs přidejte následující kód:

// Clean up
Console.Write("Press any key to begin clean up");
Console.ReadLine();

Console.WriteLine("Deleting blob container...");
await containerClient.DeleteAsync();

Console.WriteLine("Deleting the local source and downloaded files...");
File.Delete(localFilePath);
File.Delete(downloadFilePath);

Console.WriteLine("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í .NET.

Dokončený kód

Po dokončení těchto kroků by měl kód v Program.cs souboru vypadat přibližně takto:

using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using Azure.Identity;

// TODO: Replace <storage-account-name> with your actual storage account name
var blobServiceClient = new BlobServiceClient(
        new Uri("https://<storage-account-name>.blob.core.windows.net"),
        new DefaultAzureCredential());

//Create a unique name for the container
string containerName = "quickstartblobs" + Guid.NewGuid().ToString();

// Create the container and return a container client object
BlobContainerClient containerClient = await blobServiceClient.CreateBlobContainerAsync(containerName);

// Create a local file in the ./data/ directory for uploading and downloading
string localPath = "data";
Directory.CreateDirectory(localPath);
string fileName = "quickstart" + Guid.NewGuid().ToString() + ".txt";
string localFilePath = Path.Combine(localPath, fileName);

// Write text to the file
await File.WriteAllTextAsync(localFilePath, "Hello, World!");

// Get a reference to a blob
BlobClient blobClient = containerClient.GetBlobClient(fileName);

Console.WriteLine("Uploading to Blob storage as blob:\n\t {0}\n", blobClient.Uri);

// Upload data from the local file
await blobClient.UploadAsync(localFilePath, true);

Console.WriteLine("Listing blobs...");

// List all blobs in the container
await foreach (BlobItem blobItem in containerClient.GetBlobsAsync())
{
    Console.WriteLine("\t" + blobItem.Name);
}

// Download the blob to a local file
// Append the string "DOWNLOADED" before the .txt extension 
// so you can compare the files in the data directory
string downloadFilePath = localFilePath.Replace(".txt", "DOWNLOADED.txt");

Console.WriteLine("\nDownloading blob to\n\t{0}\n", downloadFilePath);

// Download the blob's contents and save it to a file
await blobClient.DownloadToAsync(downloadFilePath);

// Clean up
Console.Write("Press any key to begin clean up");
Console.ReadLine();

Console.WriteLine("Deleting blob container...");
await containerClient.DeleteAsync();

Console.WriteLine("Deleting the local source and downloaded files...");
File.Delete(localFilePath);
File.Delete(downloadFilePath);

Console.WriteLine("Done");

Spuštění kódu

Tato aplikace vytvoří testovací soubor ve složce místních dat a nahraje ho do úložiště objektů blob. 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.

Pokud používáte Visual Studio, stisknutím klávesy F5 sestavte a spusťte kód a interagujte s konzolovou aplikací. Pokud používáte .NET CLI, přejděte do adresáře aplikace a pak aplikaci sestavte a spusťte.

dotnet build

dotnet run

Výstup aplikace je podobný následujícímu příkladu (hodnoty GUID vynechány pro čitelnost):

Azure Blob Storage - .NET quickstart sample

Uploading to Blob storage as blob:
         https://mystorageacct.blob.core.windows.net/quickstartblobsGUID/quickstartGUID.txt

Listing blobs...
        quickstartGUID.txt

Downloading blob to
        ./data/quickstartGUIDDOWNLOADED.txt

Press any key to begin clean up
Deleting blob container...
Deleting the local source and downloaded files...
Done

Než začnete s vyčištěním, zkontrolujte, jestli složka dat obsahuje dva soubory. Můžete je otevřít a sledovat, ž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 azure Storage a příručky pro vývojáře pro .NET

  • Last updated on