Rychlý start: Klientská knihovna Azure Queue Storage pro Javu

Začínáme s klientskou knihovnou Azure Queue Storage pro Javu 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ázky balíčku zdrojového kódu | knihovny (Maven) |

Pomocí klientské knihovny Azure Queue Storage pro Javu můžete:

• 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

• Java Development Kit (JDK) verze 8 nebo novější
• Apache Maven
• Předplatné Azure – vytvoření bezplatného předplatného
• Účet služby Azure Storage – Vytvoření účtu úložiště

Nastavení

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

Vytvoření projektu

Vytvořte aplikaci v Javě s názvem queues-quickstart.

1. V okně konzoly (například cmd, PowerShell nebo Bash) použijte Maven k vytvoření nové konzolové aplikace s názvem queues-quickstart. Zadáním následujícího mvn příkazu vytvořte "Hello, world!" Projekt Java.

   • PowerShell
   • Bash

   mvn archetype:generate `
       --define interactiveMode=n `
       --define groupId=com.queues.quickstart `
       --define artifactId=queues-quickstart `
       --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.quickstart
   [INFO] Parameter: artifactId, Value: queues-quickstart
   [INFO] Parameter: version, Value: 1.0-SNAPSHOT
   [INFO] Parameter: package, Value: com.queues.quickstart
   [INFO] Parameter: packageInPathFormat, Value: com/queues/quickstart
   [INFO] Parameter: version, Value: 1.0-SNAPSHOT
   [INFO] Parameter: package, Value: com.queues.quickstart
   [INFO] Parameter: groupId, Value: com.queues.quickstart
   [INFO] Parameter: artifactId, Value: queues-quickstart
   [INFO] Project created from Archetype in dir: C:\quickstarts\queues\queues-quickstart
   [INFO] ------------------------------------------------------------------------
   [INFO] BUILD SUCCESS
   [INFO] ------------------------------------------------------------------------
   [INFO] Total time:  6.394 s
   [INFO] Finished at: 2019-12-03T09:58:35-08:00
   [INFO] ------------------------------------------------------------------------
   

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

   cd queues-quickstart
   

Instalace balíčků

Otevřete soubor v textovém pom.xml editoru.

Přidejte azure-sdk-bom , abyste mohli využívat závislost na nejnovější verzi knihovny. V následujícím fragmentu {bom_version_to_target} kódu nahraďte zástupný symbol číslem verze. Použití azure-sdk-bom vám umožní určit verzi jednotlivých závislostí. Další informace o kusovníku najdete v souboru README pro Azure SDK.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Potom do skupiny závislostí přidejte následující prvky závislostí. Závislost azure-identity je potřebná pro připojení bez hesla ke službám Azure.

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

Nastavení architektury aplikace

Z adresáře projektu:

1. Přejděte do adresáře /src/main/java/com/queues/quickstart .
2. Otevření souboru App.java v editoru
3. System.out.println("Hello, world"); Odstranění příkazu
4. Přidání import direktiv

Tady je kód:

package com.queues.quickstart;

/**
 * Azure Queue Storage client library quickstart
 */
import com.azure.identity.*;
import com.azure.storage.queue.*;
import com.azure.storage.queue.models.*;
import java.io.*;

public class App
{
    public static void main(String[] args) throws IOException
    {
        // 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.

az storage account show --resource-group '<your-resource-group-name>' --name '<your-storage-account-name>' --query id

az role assignment create --assignee "<user@domain>" \
    --role "Storage Queue Data Contributor" \
    --scope "<your-resource-id>"

Get-AzResource -ResourceGroupName "<yourResourceGroupname>" -Name "<yourStorageAccountName>"

New-AzRoleAssignment -SignInName <user@domain> `
    -RoleDefinitionName "Storage Queue Data Contributor" `
    -Scope <yourStorageAccountId>

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

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

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

• QueueClientBuilder: Třída QueueClientBuilder nakonfiguruje a vytvoří instanci objektu QueueClient .
• 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.
• QueueMessageItem: Třída QueueMessageItem 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 Javu:

• Autorizace přístupu a vytvoření objektu klienta
• Vytvoření fronty
• 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 a odstraňování zpráv z fronty
• Odstranění fronty

az login

az login

Connect-AzAccount

import com.azure.identity.*;

System.out.println("Azure Queue Storage client library - Java quickstart sample\n");

// Create a unique name for the queue
String queueName = "quickstartqueues-" + java.util.UUID.randomUUID();

// Instantiate a QueueClient
// We'll use this client object to create and interact with the queue
// TODO: replace <storage-account-name> with the actual name
QueueClient queueClient = new QueueClientBuilder()
        .endpoint("https://<storage-account-name>.queue.core.windows.net/")
        .queueName(queueName)
        .credential(new DefaultAzureCredentialBuilder().build())
        .buildClient();

System.out.println("Azure Queue Storage client library - Java quickstart sample\n");

// Retrieve the connection string for use with the application. The storage
// connection string is stored in an environment variable on the machine
// running the application called AZURE_STORAGE_CONNECTION_STRING. If the environment variable
// is created after the application is launched in a console or with
// Visual Studio, the shell or application needs to be closed and reloaded
// to take the environment variable into account.
String connectStr = System.getenv("AZURE_STORAGE_CONNECTION_STRING");

// Create a unique name for the queue
String queueName = "quickstartqueues-" + java.util.UUID.randomUUID();

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

// Instantiate a QueueClient
// We'll use this client object to create and interact with the queue
QueueClient queueClient = new QueueClientBuilder()
        .connectionString(connectStr)
        .queueName(queueName)
        .buildClient();

Vytvořit frontu

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

Přidejte tento kód na konec main metody:

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

// Create the queue
queueClient.create();

Přidání zpráv do fronty

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

Přidejte tento kód na konec main metody:

System.out.println("\nAdding messages to the queue...");

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

// Save the result so we can update this message later
SendMessageResult result = queueClient.sendMessage("Third message");

Náhled zpráv ve frontě

Prohlédněte si zprávy ve frontě voláním peekMessages 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 main metody:

System.out.println("\nPeek at the messages in the queue...");

// Peek at messages in the queue
queueClient.peekMessages(10, null, null).forEach(
    peekedMessage -> System.out.println("Message: " + peekedMessage.getMessageText()));

Aktualizace zprávy ve frontě

Aktualizujte obsah zprávy voláním updateMessage 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 ID zprávy a potvrzení otevírané okno pomocí SendMessageResult dříve uloženého v kódu. ID zprávy a potvrzení otevírané okno identifikují, kterou zprávu chcete aktualizovat.

System.out.println("\nUpdating the third message in the queue...");

// Update a message using the result that
// was saved when sending the message
queueClient.updateMessage(result.getMessageId(),
                          result.getPopReceipt(),
                          "Third message has been updated",
                          Duration.ofSeconds(1));

Získání délky fronty

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

Metoda getProperties vrátí několik hodnot, včetně počtu zpráv aktuálně ve frontě. Počet je pouze přibližný, protože zprávy je možné přidat nebo odebrat po požadavku. Metoda getApproximateMessageCount vrátí poslední hodnotu načtenou voláním getProperties, bez volání Queue Storage.

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

System.out.println(String.format("Queue length: %d", messageCount));

Příjem a odstraňování zpráv z fronty

Stáhněte si dříve přidané zprávy voláním receiveMessages metody. Ukázkový kód také odstraní zprávy z fronty po jejich přijetí a zpracování. V tomto případě se při zpracování jenom zobrazí zpráva v konzole.

Aplikace se pozastaví pro uživatelský vstup zavoláním System.console().readLine(); , než přijme 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 main metody:

System.out.println("\nPress Enter key to receive messages and delete them from the queue...");
System.console().readLine();

// Get messages from the queue
queueClient.receiveMessages(10).forEach(
    // "Process" the message
    receivedMessage -> {
        System.out.println("Message: " + receivedMessage.getMessageText());

        // Let the service know we're finished with
        // the message and it can be safely deleted.
        queueClient.deleteMessage(receivedMessage.getMessageId(), receivedMessage.getPopReceipt());
    }
);

Při volání receiveMessages metody můžete volitelně 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í fronty

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

Přidejte tento kód na konec main metody:

System.out.println("\nPress Enter key to delete the queue...");
System.console().readLine();

// Clean up
System.out.println("Deleting queue: " + queueClient.getQueueName());
queueClient.delete();

System.out.println("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.

mvn compile

Pak balíček sestavte.

mvn package

Ke spuštění aplikace použijte následující mvn příkaz.

mvn exec:java -Dexec.mainClass="com.queues.quickstart.App" -Dexec.cleanupDaemonThreads=false

Výstup aplikace je podobný následujícímu příkladu:

Azure Queue Storage client library - Java quickstart sample

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

Press Enter key to receive 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-fbf58f33-4d5a-41ac-ac0e-1a05d01c7003
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í kódu Java. 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:

• Související ukázky kódu s využitím zastaralých sad Java verze 8 SDK najdete v ukázkách kódu s využitím Javy verze 8.
• Další ukázkové aplikace Azure Queue Storage najdete v klientské knihovně Azure Queue Storage pro Javu – ukázky.