Rychlý start: Klientská knihovna Azure Queue Storage pro .NET

  • Článek

Začínáme s klientskou knihovnou Azure Queue Storage pro .NET Azure Queue Storage je služba pro ukládání velkého počtu zpráv pro pozdější načtení a zpracování. Pomocí těchto kroků nainstalujte balíček a vyzkoušejte si ukázkový kód pro základní úlohy.

Referenční dokumentace k | rozhraní API – Ukázka balíčku zdrojového kódu | knihovny (NuGet) |

Klientskou knihovnu Azure Queue Storage pro .NET použijte k:

  • Vytvořit frontu
  • Přidání zpráv do fronty
  • Náhled zpráv ve frontě
  • Aktualizace zprávy ve frontě
  • Získání délky fronty
  • Příjem zpráv z fronty
  • Odstranění zpráv z fronty
  • Odstranění fronty

Předpoklady

Nastavení

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

Vytvoření projektu

Vytvořte aplikaci .NET s názvem QueuesQuickstart.

  1. V okně konzoly (například cmd, PowerShell nebo Bash) pomocí dotnet new příkazu vytvořte novou konzolovou aplikaci s názvem QueuesQuickstart. Tento příkaz vytvoří jednoduchý projekt "hello world" C# s jedním zdrojovým souborem s názvem Program.cs.

    dotnet new console -n QueuesQuickstart

  2. Přepněte do nově vytvořeného QueuesQuickstart adresáře.

    cd QueuesQuickstart

Instalace balíčků

V adresáři aplikace nainstalujte pomocí příkazu klientskou knihovnu Azure Queue Storage pro balíček dotnet add package .NET.

dotnet add package Azure.Storage.Queues

Balíček klientské knihovny Azure Identity je také nutný pro připojení bez hesla ke službám Azure.

dotnet add package Azure.Identity

Nastavení architektury aplikace

  1. Otevření projektu v libovolném editoru
  2. Otevření souboru Program.cs
  3. Aktualizujte existující kód tak, aby odpovídal následujícímu:
using Azure;
using Azure.Identity;
using Azure.Storage.Queues;
using Azure.Storage.Queues.Models;
using System;
using System.Threading.Tasks;

Console.WriteLine("Azure Queue Storage client library - .NET quickstart sample");

// Quickstart code goes here

Ověřování v Azure

Žádosti o aplikace na většinu služeb Azure musí být autorizované. DefaultAzureCredential Použití třídy poskytované klientskou knihovnou Azure Identity je doporučeným přístupem k implementaci připojení bez hesel ke službám Azure ve vašem kódu.

Žádosti o služby Azure můžete také autorizovat pomocí hesel, připojovací řetězec nebo jiných přihlašovacích údajů přímo. Tento přístup by však měl být používán s opatrností. Vývojáři musí být usilovní, aby tyto tajné kódy nikdy nezpřístupnili v nezabezpečeném umístění. Každý, kdo získá přístup k heslu nebo tajnému klíči, se může ověřit. 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 DefaultAzureCredentialv přehledu 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í.

Vaše aplikace se například může při vývoji místně ověřovat pomocí přihlašovacích údajů sady Visual Studio a potom používat spravovanou identitu po nasazení do Azure. Pro tento přechod nejsou vyžadovány žádné změny kódu.

Při místním vývoji se ujistěte, že uživatelský účet, který přistupuje k datům fronty, má správná oprávnění. Ke čtení a zápisu dat fronty budete potřebovat přispěvatel dat fronty služby Storage. Abyste mohli tuto roli přiřadit sami sobě, musíte mít přiřazenou roli User Access Správa istrator 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 dostupných oborech pro přiřazení rolí najdete na stránce přehledu oboru.

V tomto scénáři přiřadíte oprávnění k vašemu uživatelskému účtu s vymezeným oborem účtu ú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 fronty úložiště k vašemu uživatelskému účtu, který poskytuje přístup pro čtení i zápis k datům fronty 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.

A screenshot showing how to assign a role.

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

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

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

  4. Vyberte Zkontrolovat a přiřadit přejděte na poslední stránku a pak proces dokončete opětovnou kontrolou a přiřazením .

Objektový model

Azure Queue Storage je služba pro ukládání velkých objemů zpráv. Zpráva fronty může mít velikost až 64 kB. Fronta může obsahovat miliony zpráv až do celkového limitu kapacity účtu úložiště. Fronty se běžně používají k vytvoření backlogu práce pro asynchronní zpracování. Queue Storage nabízí tři typy prostředků:

  • Účet úložiště: Veškerý přístup ke službě Azure Storage se provádí prostřednictvím účtu úložiště. Další informace o účtech úložiště najdete v tématu Přehled účtu úložiště
  • Fronta: Fronta obsahuje sadu zpráv. Všechny zprávy musí být ve frontě. Upozorňujeme, že název fronty musí být psaný malými písmeny. Informace o pojmenování front najdete v tématu Pojmenování front a metadata.
  • Zpráva: Zprávu v libovolném formátu o velikosti až 64 kB. Zpráva může zůstat ve frontě maximálně 7 dní. Pro verzi 2017-07-29 nebo novější může být maximální doba k živému přenosu libovolné kladné číslo nebo -1 označující, že platnost zprávy nevyprší. Pokud tento parametr vynecháte, výchozí hodnota time-to-live je sedm dní.

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

Diagram of Queue storage architecture

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

  • QueueServiceClient: Umožňuje QueueServiceClient spravovat všechny fronty ve vašem účtu úložiště.
  • QueueClient: Třída QueueClient umožňuje spravovat a manipulovat s jednotlivými fronty a jejími zprávami.
  • QueueMessage: Třída QueueMessage představuje jednotlivé objekty vrácené při volání ReceiveMessages do fronty.

Příklady kódu

Tyto ukázkové fragmenty kódu ukazují, jak provádět následující akce s klientskou knihovnou Azure Queue Storage pro .NET:

Autorizace přístupu a vytvoření objektu klienta

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

Po ověření můžete vytvořit a autorizovat QueueClient objekt pomocí DefaultAzureCredential přístupu k datům fronty v účtu úložiště. DefaultAzureCredential automaticky zjistí a použije účet, kterým jste se přihlásili v předchozím kroku.

Pokud chcete autorizovat použití DefaultAzureCredential, ujistěte se, že jste přidali balíček Azure.Identity , jak je popsáno v tématu Instalace balíčků. Nezapomeňte také přidat direktivu using pro Azure.Identity obor názvů v souboru Program.cs :

using Azure.Identity;

Dále se rozhodněte o názvu fronty a vytvořte instanci QueueClient třídy, která slouží DefaultAzureCredential k autorizaci. Tento objekt klienta používáme k vytvoření prostředku fronty v účtu úložiště a interakci s ním.

Důležité

Názvy front mohou obsahovat pouze malá písmena, číslice a pomlčky a musí začínat písmenem nebo číslem. Před i za každým spojovníkem musí být jiný znak než spojovník. Název musí mít délku 3 až 63 znaků. Další informace najdete v tématu Pojmenování front a metadat.

Na konec souboru Program.cs přidejte následující kód. Nezapomeňte nahradit zástupnou <storage-account-name> hodnotu:

// Create a unique name for the queue
// TODO: Replace the <storage-account-name> placeholder 
string queueName = "quickstartqueues-" + Guid.NewGuid().ToString();
string storageAccountName = "<storage-account-name>";

// Instantiate a QueueClient to create and interact with the queue
QueueClient queueClient = new QueueClient(
    new Uri($"https://{storageAccountName}.queue.core.windows.net/{queueName}"),
    new DefaultAzureCredential());

Poznámka:

Zprávy odeslané pomocí QueueClient třídy musí být ve formátu, který lze zahrnout do požadavku XML s kódováním UTF-8. Volitelně můžete nastavit možnost MessageEncoding na Base64 pro zpracování zpráv, které nedodržují předpisy.

Vytvořit frontu

Pomocí objektu QueueClient zavolejte metodu CreateAsync pro vytvoření fronty v účtu úložiště.

Přidejte tento kód na konec metody Program.cs :

Console.WriteLine($"Creating queue: {queueName}");

// Create the queue
await queueClient.CreateAsync();

Přidání zpráv do fronty

Následující fragment kódu asynchronně přidává zprávy do fronty voláním SendMessageAsync metody. Uloží také vrácenou SendReceiptSendMessageAsync zprávu z volání. Potvrzení se použije k aktualizaci zprávy později v programu.

Přidejte tento kód na konec souboru Program.cs :

Console.WriteLine("\nAdding messages to the queue...");

// Send several messages to the queue
await queueClient.SendMessageAsync("First message");
await queueClient.SendMessageAsync("Second message");

// Save the receipt so we can update this message later
SendReceipt receipt = await queueClient.SendMessageAsync("Third message");

Náhled zpráv ve frontě

Prohlédněte si zprávy ve frontě voláním PeekMessagesAsync metody. Tato metoda načte jednu nebo více zpráv z přední části fronty, ale nezmění viditelnost zprávy.

Přidejte tento kód na konec souboru Program.cs :

Console.WriteLine("\nPeek at the messages in the queue...");

// Peek at messages in the queue
PeekedMessage[] peekedMessages = await queueClient.PeekMessagesAsync(maxMessages: 10);

foreach (PeekedMessage peekedMessage in peekedMessages)
{
    // Display the message
    Console.WriteLine($"Message: {peekedMessage.MessageText}");
}

Aktualizace zprávy ve frontě

Aktualizujte obsah zprávy voláním UpdateMessageAsync metody. Tato metoda může změnit časový limit viditelnosti a obsah zprávy. Obsah zprávy musí být řetězec s kódováním UTF-8, který má velikost až 64 kB. Spolu s novým obsahem zprávy předejte hodnoty z SendReceipt dříve uloženého kódu. Hodnoty SendReceipt identifikují, která zpráva se má aktualizovat.

Console.WriteLine("\nUpdating the third message in the queue...");

// Update a message using the saved receipt from sending the message
await queueClient.UpdateMessageAsync(receipt.MessageId, receipt.PopReceipt, "Third message has been updated");

Získání délky fronty

Podle potřeby můžete získat odhadovaný počet zpráv ve frontě. Metoda GetProperties vrátí vlastnosti fronty, včetně počtu zpráv. Vlastnost ApproximateMessagesCount obsahuje přibližný počet zpráv ve frontě. Toto číslo není nižší než skutečný počet zpráv ve frontě, ale může být vyšší.

Přidejte tento kód na konec souboru Program.cs :

QueueProperties properties = queueClient.GetProperties();

// Retrieve the cached approximate message count
int cachedMessagesCount = properties.ApproximateMessagesCount;

// Display number of messages
Console.WriteLine($"Number of messages in queue: {cachedMessagesCount}");

Příjem zpráv z fronty

Stáhněte si dříve přidané zprávy voláním ReceiveMessagesAsync metody.

Přidejte tento kód na konec souboru Program.cs :

Console.WriteLine("\nReceiving messages from the queue...");

// Get messages from the queue
QueueMessage[] messages = await queueClient.ReceiveMessagesAsync(maxMessages: 10);

Volitelně můžete zadat hodnotu pro maxMessages, což je počet zpráv, které se mají načíst z fronty. Výchozí hodnota je 1 zpráva a maximum je 32 zpráv. Můžete také zadat hodnotu pro visibilityTimeout, která skryje zprávy z jiných operací pro období časového limitu. Výchozí hodnota je 30 sekund.

Odstranění zpráv z fronty

Odstraňte zprávy z fronty po jejich zpracování. V tomto případě se při zpracování jenom zobrazí zpráva v konzole.

Aplikace se pozastaví pro uživatelský vstup voláním Console.ReadLine předtím, než zpracuje a odstraní zprávy. Před odstraněním ověřte na webu Azure Portal , že se prostředky správně vytvořily. Všechny zprávy, které se explicitně neodstraní, se nakonec znovu zviditelní ve frontě, aby se daly zpracovat.

Přidejte tento kód na konec souboru Program.cs :

Console.WriteLine("\nPress Enter key to 'process' messages and delete them from the queue...");
Console.ReadLine();

// Process and delete messages from the queue
foreach (QueueMessage message in messages)
{
    // "Process" the message
    Console.WriteLine($"Message: {message.MessageText}");

    // Let the service know we're finished with
    // the message and it can be safely deleted.
    await queueClient.DeleteMessageAsync(message.MessageId, message.PopReceipt);
}

Odstranění fronty

Následující kód vyčistí prostředky vytvořené aplikací odstraněním fronty DeleteAsync pomocí metody.

Přidejte tento kód na konec souboru Program.cs :

Console.WriteLine("\nPress Enter key to delete the queue...");
Console.ReadLine();

// Clean up
Console.WriteLine($"Deleting queue: {queueClient.Name}");
await queueClient.DeleteAsync();

Console.WriteLine("Done");

Spuštění kódu

Tato aplikace vytvoří a přidá do fronty Azure tři zprávy. Kód zobrazí seznam zpráv ve frontě a potom je načte a odstraní, a teprve potom frontu odstraní.

V okně konzoly 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:

Azure Queue Storage client library - .NET quickstart sample

Creating queue: quickstartqueues-5c72da2c-30cc-4f09-b05c-a95d9da52af2

Adding messages to the queue...

Peek at the messages in the queue...
Message: First message
Message: Second message
Message: Third message

Updating the third message in the queue...

Receiving messages from the queue...

Press Enter key to 'process' messages and delete them from the queue...

Message: First message
Message: Second message
Message: Third message has been updated

Press Enter key to delete the queue...

Deleting queue: quickstartqueues-5c72da2c-30cc-4f09-b05c-a95d9da52af2
Done

Když se aplikace pozastaví před příjmem zpráv, zkontrolujte svůj účet úložiště na webu Azure Portal. Ověřte, že jsou zprávy ve frontě.

Stisknutím klávesy Enter zprávy přijmete a odstraníte. Po zobrazení výzvy znovu stisknutím klávesy Enter odstraňte frontu a dokončete ukázku.

Další kroky

V tomto rychlém startu jste zjistili, jak vytvořit frontu a přidat do ní zprávy pomocí asynchronního kódu .NET. Pak jste se naučili zobrazit, načíst a odstranit zprávy. Nakonec jste zjistili, jak odstranit frontu zpráv.

Kurzy, ukázky, rychlé starty a další dokumentace najdete tady:

Azure pro vývojáře na platformě .NET a .NET Core