použití Queue Storage z Java

  • Článek
  • 17 min ke čtení

Přehled

v této příručce se dozvíte, jak pomocí služby Azure Queue Storage code pro běžné scénáře. Ukázky jsou napsané v Javě a využívají sadu SDK služby Azure Storage pro Javu. Mezi scénáře patří vkládání, prohlížení, získávání a odstraňování zpráv fronty. Kód pro vytváření a odstraňování front je také pokrytý. Další informace o frontách najdete v části Další kroky .

Co je Queue Storage?

Azure Queue Storage je služba pro ukládání velkého počtu zpráv, ke které můžete získat přístup z jakéhokoli místa na světě prostřednictvím ověřených volání s využitím protokolu HTTP nebo HTTPS. Zpráva s jednou frontou může mít velikost až 64 kB a jedna fronta můžete obsahovat miliony zpráv, až do dosažení celkové kapacity účtu úložiště. Fronta úložiště se často používá k vytvoření nevyřízených položek pro asynchronní zpracování.

Služba front koncepty

Služba front Azure obsahuje následující komponenty:

Součásti Azure Služba front

  • Úč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. Maximální doba, po kterou může zpráva zůstat ve frontě, je 7 dní. V případě verze 2017-07-29 nebo novější může být maximální doba do živého kladného čísla nebo-1, což znamená, že platnost zprávy nevyprší. Pokud je tento parametr vynechán, výchozí hodnota TTL (Time to Live) je sedm dní.

  • Formát adresy URL: Fronty jsou adresovatelné v následujícím formátu adresy URL: http:// <storage account> . Queue.Core.Windows.NET/<queue>

    Následující adresa URL odkazuje na frontu v diagramu:

    http://myaccount.queue.core.windows.net/incoming-orders

Vytvoření účtu úložiště Azure

Nejjednodušší způsob, jak vytvořit první účet úložiště Azure, je pomocí Azure Portal. Další informace najdete v tématu Vytvoření účtu úložiště.

Účet úložiště Azure můžete vytvořit také pomocí prostředí Azure PowerShell, rozhraní příkazového řádku Azure nebo pomocí poskytovatele prostředků služby Azure Storage pro .NET.

Pokud nechcete v Azure v tuto chvíli vytvářet účet úložiště, můžete použít taky emulátor úložiště Azurite ke spuštění a testování kódu v místním prostředí. Další informace najdete v tématu použití emulátoru Azurite pro vývoj místních Azure Storage.

Vytvoření aplikace Java

nejdřív ověřte, že váš vývojový systém splňuje požadavky uvedené v Azure Queue Storage klientské knihovně v12 pro jazyk Java.

Vytvoření aplikace Java s názvem queues-how-to-v12 :

  1. V okně konzoly (například cmd, PowerShell nebo bash) použijte Maven k vytvoření nové konzolové aplikace s názvem queues-how-to-v12 . Zadáním následujícího mvn příkazu vytvořte projekt "Hello World" v jazyce Java.

     mvn archetype:generate \
     --define interactiveMode=n \
     --define groupId=com.queues.howto \
     --define artifactId=queues-howto-v12 \
     --define archetypeArtifactId=maven-archetype-quickstart \
     --define archetypeVersion=1.4

    mvn archetype:generate `
    --define interactiveMode=n `
    --define groupId=com.queues.howto `
    --define artifactId=queues-howto-v12 `
    --define archetypeArtifactId=maven-archetype-quickstart `
    --define archetypeVersion=1.4

  2. Výstup z generování projektu by měl vypadat přibližně takto:

    [INFO] Scanning for projects...
[INFO]
[INFO] ------------------< org.apache.maven:standalone-pom >-------------------
[INFO] Building Maven Stub Project (No POM) 1
[INFO] --------------------------------[ pom ]---------------------------------
[INFO]
[INFO] >>> maven-archetype-plugin:3.1.2:generate (default-cli) > generate-sources @ standalone-pom >>>
[INFO]
[INFO] <<< maven-archetype-plugin:3.1.2:generate (default-cli) < generate-sources @ standalone-pom <<<
[INFO]
[INFO]
[INFO] --- maven-archetype-plugin:3.1.2:generate (default-cli) @ standalone-pom ---
[INFO] Generating project in Batch mode
[INFO] ----------------------------------------------------------------------------
[INFO] Using following parameters for creating project from Archetype: maven-archetype-quickstart:1.4
[INFO] ----------------------------------------------------------------------------
[INFO] Parameter: groupId, Value: com.queues.howto
[INFO] Parameter: artifactId, Value: queues-howto-v12
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] Parameter: package, Value: com.queues.howto
[INFO] Parameter: packageInPathFormat, Value: com/queues/howto
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] Parameter: package, Value: com.queues.howto
[INFO] Parameter: groupId, Value: com.queues.howto
[INFO] Parameter: artifactId, Value: queues-howto-v12
[INFO] Project created from Archetype in dir: C:\queues\queues-howto-v12
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  6.775 s
[INFO] Finished at: 2020-08-17T15:27:31-07:00
[INFO] ------------------------------------------------------------------------

  3. Přepněte do nově vytvořeného queues-howto-v12 adresáře.

    cd queues-howto-v12

Instalace balíčku

Otevřete pom.xml soubor v textovém editoru. Přidejte následující prvek závislosti do skupiny závislostí.

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-storage-queue</artifactId>
  <version>12.6.0</version>
</dependency>

Konfigurace aplikace pro přístup k Queue Storage

do horní části souboru Java přidejte následující příkazy pro import, ve kterých chcete pro přístup k frontám použít rozhraní Azure Storage api:

// Include the following imports to use queue APIs
import com.azure.core.util.*;
import com.azure.storage.queue.*;
import com.azure.storage.queue.models.*;

Nastavení připojovacího řetězce služby Azure Storage

klient Azure Storage používá připojovací řetězec úložiště pro přístup ke službám pro správu dat. Získejte název a primární přístupový klíč pro váš účet úložiště uvedený v Azure Portal. Použijte je jako AccountName hodnoty a AccountKey v připojovacím řetězci. Tento příklad ukazuje deklaraci statického pole pro uložení připojovacího řetězce:

// Define the connection-string with your values
final String connectStr = 
    "DefaultEndpointsProtocol=https;" +
    "AccountName=your_storage_account;" +
    "AccountKey=your_storage_account_key";

Následující ukázky předpokládají, že máte objekt, který String obsahuje připojovací řetězec úložiště.

Postupy: vytvoření fronty

QueueClientObjekt obsahuje operace pro interakci s frontou. Následující kód vytvoří QueueClient objekt. Pomocí QueueClient objektu vytvořte frontu, kterou chcete použít.

public static String createQueue(String connectStr)
{
    try
    {
        // Create a unique name for the queue
        String queueName = "queue-" + java.util.UUID.randomUUID();

        System.out.println("Creating queue: " + queueName);

        // Instantiate a QueueClient which will be
        // used to create and manipulate the queue
        QueueClient queue = new QueueClientBuilder()
                                .connectionString(connectStr)
                                .queueName(queueName)
                                .buildClient();

        // Create the queue
        queue.create();
        return queue.getQueueName();
    }
    catch (QueueStorageException e)
    {
        // Output the exception message and stack trace
        System.out.println("Error code: " + e.getErrorCode() + "Message: " + e.getMessage());
        return null;
    }
}

Postupy: Přidání zprávy do fronty

Chcete-li vložit zprávu do existující fronty, zavolejte sendMessage metodu. Zpráva může být buď řetězec (ve formátu UTF-8), nebo pole bajtů. Zde je kód, který pošle řetězcovou zprávu do fronty.

public static void addQueueMessage
    (String connectStr, String queueName, String messageText)
{
    try
    {
        // Instantiate a QueueClient which will be
        // used to create and manipulate the queue
        QueueClient queueClient = new QueueClientBuilder()
                                    .connectionString(connectStr)
                                    .queueName(queueName)
                                    .buildClient();

        System.out.println("Adding message to the queue: " + messageText);

        // Add a message to the queue
        queueClient.sendMessage(messageText);
    }
    catch (QueueStorageException e)
    {
        // Output the exception message and stack trace
        System.out.println(e.getMessage());
        e.printStackTrace();
    }
}

Postupy: prohlížení další zprávy

Můžete prohlížet zprávy před frontou, aniž byste je museli odebírat z fronty voláním peekMessage .

public static void peekQueueMessage
    (String connectStr, String queueName)
{
    try
    {
        // Instantiate a QueueClient which will be
        // used to create and manipulate the queue
        QueueClient queueClient = new QueueClientBuilder()
                                    .connectionString(connectStr)
                                    .queueName(queueName)
                                    .buildClient();

        // Peek at the first message
        PeekedMessageItem peekedMessageItem = queueClient.peekMessage();
        System.out.println("Peeked message: " + peekedMessageItem.getMessageText());
    }
    catch (QueueStorageException e)
    {
        // Output the exception message and stack trace
        System.out.println(e.getMessage());
        e.printStackTrace();
    }
}

Postupy: Změna obsahu zprávy ve frontě

Podle potřeby můžete změnit obsah zprávy přímo ve frontě. Pokud zpráva představuje pracovní úlohu, můžete tuto funkci použít k aktualizaci stavu. Následující kód aktualizuje zprávu fronty o nový obsah a nastaví časový limit viditelnosti na prodloužení dalších 30 sekund. Prodloužení časového limitu viditelnosti zadává klientovi další 30 sekund, než bude pokračovat ve zpracování zprávy. Můžete také zachovat počet opakování. Pokud se zpráva znovu pokusí o více než n krát, byste ji odstranili. Tento scénář je chráněn proti zprávě, která při každém zpracování vyvolá chybu aplikace.

Následující ukázka kódu prohledá frontu zpráv, vyhledá první obsah zprávy, který odpovídá hledanému řetězci, upraví obsah zprávy a ukončí.

public static void updateQueueMessage
    (String connectStr, String queueName,
    String searchString, String updatedContents)
{
    try
    {
        // Instantiate a QueueClient which will be
        // used to create and manipulate the queue
        QueueClient queueClient = new QueueClientBuilder()
                                    .connectionString(connectStr)
                                    .queueName(queueName)
                                    .buildClient();

        // The maximum number of messages to retrieve is 32
        final int MAX_MESSAGES = 32;

        // Iterate through the queue messages
        for (QueueMessageItem message : queueClient.receiveMessages(MAX_MESSAGES))
        {
            // Check for a specific string
            if (message.getMessageText().equals(searchString))
            {
                // Update the message to be visible in 30 seconds
                queueClient.updateMessage(message.getMessageId(),
                                          message.getPopReceipt(),
                                          updatedContents,
                                          Duration.ofSeconds(30));
                System.out.println(
                    String.format("Found message: \'%s\' and updated it to \'%s\'",
                                    searchString,
                                    updatedContents)
                                  );
                break;
            }
        }
    }
    catch (QueueStorageException e)
    {
        // Output the exception message and stack trace
        System.out.println(e.getMessage());
        e.printStackTrace();
    }
}

Následující ukázka kódu aktualizuje pouze první viditelnou zprávu ve frontě.

public static void updateFirstQueueMessage
    (String connectStr, String queueName, String updatedContents)
{
    try
    {
        // Instantiate a QueueClient which will be
        // used to create and manipulate the queue
        QueueClient queueClient = new QueueClientBuilder()
                                    .connectionString(connectStr)
                                    .queueName(queueName)
                                    .buildClient();

        // Get the first queue message
        QueueMessageItem message = queueClient.receiveMessage();

        // Check for a specific string
        if (null != message)
        {
            // Update the message to be visible in 30 seconds
            UpdateMessageResult result = queueClient.updateMessage(message.getMessageId(),
                                                                   message.getPopReceipt(),
                                                                   updatedContents,
                                                                   Duration.ofSeconds(30));
            System.out.println("Updated the first message with the receipt: " +
                    result.getPopReceipt());
        }
    }
    catch (QueueStorageException e)
    {
        // Output the exception message and stack trace
        System.out.println(e.getMessage());
        e.printStackTrace();
    }
}

Postupy: získání délky fronty

Podle potřeby můžete získat odhadovaný počet zpráv ve frontě.

getPropertiesMetoda vrátí několik hodnot včetně počtu zpráv, které jsou aktuálně ve frontě. Počet je jenom přibližný, protože po vaší žádosti je možné přidat nebo odebrat zprávy. getApproximateMessageCountMetoda vrátí poslední hodnotu získanou voláním getProperties , bez volání Queue Storage.

public static void getQueueLength(String connectStr, String queueName)
{
    try
    {
        // Instantiate a QueueClient which will be
        // used to create and manipulate the queue
        QueueClient queueClient = new QueueClientBuilder()
                                    .connectionString(connectStr)
                                    .queueName(queueName)
                                    .buildClient();

        QueueProperties properties = queueClient.getProperties();
        long messageCount = properties.getApproximateMessagesCount();

        System.out.println(String.format("Queue length: %d", messageCount));
    }
    catch (QueueStorageException e)
    {
        // Output the exception message and stack trace
        System.out.println(e.getMessage());
        e.printStackTrace();
    }
}

Postupy: vyřazení další zprávy z fronty

Váš kód vyřadí zprávu z fronty ve dvou krocích. Když zavoláte receiveMessage , dostanete další zprávu ve frontě. Zpráva vrácená z receiveMessage se bude neviditelná pro jakýkoliv jiný kód, který čte zprávy z této fronty. Ve výchozím nastavení tato zpráva zůstává neviditelná po dobu 30 sekund. Chcete-li dokončit odebrání zprávy z fronty, je také nutné zavolat deleteMessage . Pokud kód nedokáže zpracovat zprávu, tento proces se dvěma kroky zajistí, že můžete získat stejnou zprávu a zkusit to znovu. Váš kód volá deleteMessage hned po zpracování zprávy.

public static void dequeueMessage(String connectStr, String queueName)
{
    try
    {
        // Instantiate a QueueClient which will be
        // used to create and manipulate the queue
        QueueClient queueClient = new QueueClientBuilder()
                                    .connectionString(connectStr)
                                    .queueName(queueName)
                                    .buildClient();

        // Get the first queue message
        QueueMessageItem message = queueClient.receiveMessage();

        // Check for a specific string
        if (null != message)
        {
            System.out.println("Dequeing message: " + message.getMessageText());

            // Delete the message
            queueClient.deleteMessage(message.getMessageId(), message.getPopReceipt());
        }
        else
        {
            System.out.println("No visible messages in queue");
        }
    }
    catch (QueueStorageException e)
    {
        // Output the exception message and stack trace
        System.out.println(e.getMessage());
        e.printStackTrace();
    }
}

Další možnosti pro vyřazování zpráv do fronty

Existují dva způsoby, jak přizpůsobit načítání zpráv z fronty. Nejdřív Získejte dávku zpráv (až 32). Za druhé nastavte delší nebo kratší časový limit neviditelnosti a umožněte, aby váš kód měl více nebo méně času na úplné zpracování každé zprávy.

Následující příklad kódu používá receiveMessages metodu k získání 20 zpráv v jednom volání. Pak každou zprávu zpracuje pomocí for smyčky. Nastaví také časový limit neviditelnosti na pět minut (300 sekund) pro každou zprávu. Časový limit začíná pro všechny zprávy ve stejnou dobu. Až pět minut uplynulo od volání receiveMessages , všechny zprávy, které se neodstraní, se znovu zobrazí.

public static void dequeueMessages(String connectStr, String queueName)
{
    try
    {
        // Instantiate a QueueClient which will be
        // used to create and manipulate the queue
        QueueClient queueClient = new QueueClientBuilder()
                                    .connectionString(connectStr)
                                    .queueName(queueName)
                                    .buildClient();

        // The maximum number of messages to retrieve is 20
        final int MAX_MESSAGES = 20;

        // Retrieve 20 messages from the queue with a
        // visibility timeout of 300 seconds (5 minutes)
        for (QueueMessageItem message : queueClient.receiveMessages(MAX_MESSAGES,
                Duration.ofSeconds(300), Duration.ofSeconds(1), new Context("key1", "value1")))
        {
            // Do processing for all messages in less than 5 minutes,
            // deleting each message after processing.
            System.out.println("Dequeing message: " + message.getMessageText());
            queueClient.deleteMessage(message.getMessageId(), message.getPopReceipt());
        }
    }
    catch (QueueStorageException e)
    {
        // Output the exception message and stack trace
        System.out.println(e.getMessage());
        e.printStackTrace();
    }
}

Postupy: výpis front

Chcete-li získat seznam aktuálních front, zavolejte QueueServiceClient.listQueues() metodu, která vrátí kolekci QueueItem objektů.

public static void listQueues(String connectStr)
{
    try
    {
        // Instantiate a QueueServiceClient which will be
        // used to list the queues
        QueueServiceClient queueServiceClient = new QueueServiceClientBuilder()
                                    .connectionString(connectStr)
                                    .buildClient();

        // Loop through the collection of queues.
        for (QueueItem queue : queueServiceClient.listQueues())
        {
            // Output each queue name.
            System.out.println(queue.getName());
        }
    }
    catch (QueueStorageException e)
    {
        // Output the exception message and stack trace
        System.out.println(e.getMessage());
        e.printStackTrace();
    }
}

Postupy: odstranění fronty

Chcete-li odstranit frontu a všechny zprávy, které jsou v něm obsaženy, zavolejte delete metodu QueueClient objektu.

public static void deleteMessageQueue(String connectStr, String queueName)
{
    try
    {
        // Instantiate a QueueClient which will be
        // used to create and manipulate the queue
        QueueClient queueClient = new QueueClientBuilder()
                                    .connectionString(connectStr)
                                    .queueName(queueName)
                                    .buildClient();

        System.out.println("Deleting queue: " + queueClient.getQueueName());

        // Delete the queue
        queueClient.delete();
    }
    catch (QueueStorageException e)
    {
        // Output the exception message and stack trace
        System.out.println(e.getMessage());
        e.printStackTrace();
    }
}

Tip

Projděte si úložiště s ukázkami kódu pro Azure Storage

Snadno použitelné a úplné ukázky kódu pro Azure Storage, které si můžete stáhnout a použít, jsou shrnuté v seznamu ukázky pro Azure Storage.

Další kroky

teď, když jste se naučili základy Queue Storage, postupujte podle těchto odkazů a získejte další informace o složitějších úlohách úložiště.