Schnellstart: Azure Queue Storage-Clientbibliothek v12 für Java

Beginnen Sie mit dem Einsatz der Azure Queue Storage-Clientbibliothek v12 für Java. Azure Queue Storage ist ein Dienst zum Speichern einer großen Anzahl von Nachrichten, die später abgerufen und verarbeitet werden. Führen Sie die nachfolgenden Schritte aus, um das Paket zu installieren und den Beispielcode für grundlegende Aufgaben zu testen.

Mit der Azure Queue Storage-Clientbibliothek v12 für Java können Sie Folgendes ausführen:

  • Erstellen einer Warteschlange
  • Hinzufügen von Nachrichten zu einer Warteschlange
  • Einsehen von Nachrichten in einer Warteschlange
  • Aktualisieren einer Nachricht in einer Warteschlange
  • Empfangen und Löschen von Nachrichten aus einer Warteschlange
  • Löschen einer Warteschlange

Zusätzliche Ressourcen:

Voraussetzungen

Einrichten

In diesem Abschnitt wird beschrieben, wie Sie ein Projekt zum Arbeiten mit der Azure Queue Storage-Clientbibliothek v12 für Java vorbereiten.

Erstellen des Projekts

Erstellen Sie eine Java-Anwendung mit dem Namen queues-quickstart-v12.

  1. Verwenden Sie in einem Konsolenfenster (z. B. cmd, PowerShell oder Bash) Maven zum Erstellen einer neuen Konsolen-App mit dem Namen queues-quickstart-v12. Geben Sie den folgenden mvn-Befehl ein, um ein „Hallo Welt!“-Java-Projekt zu erstellen.

    mvn archetype:generate `
        --define interactiveMode=n `
        --define groupId=com.queues.quickstart `
        --define artifactId=queues-quickstart-v12 `
        --define archetypeArtifactId=maven-archetype-quickstart `
        --define archetypeVersion=1.4
    
  2. Die Ausgabe der Erstellung des Projekts sollte in etwa wie folgt aussehen:

    [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-v12
    [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-v12
    [INFO] Project created from Archetype in dir: C:\quickstarts\queues\queues-quickstart-v12
    [INFO] ------------------------------------------------------------------------
    [INFO] BUILD SUCCESS
    [INFO] ------------------------------------------------------------------------
    [INFO] Total time:  6.394 s
    [INFO] Finished at: 2019-12-03T09:58:35-08:00
    [INFO] ------------------------------------------------------------------------
    
  3. Wechseln Sie zum neu erstellten Verzeichnis queues-quickstart-v12.

    cd queues-quickstart-v12
    

Installieren des Pakets

Öffnen Sie die Datei pom.xml in Ihrem Text-Editor. Fügen Sie der Gruppe „dependencies“ das folgende Abhängigkeitselement hinzu.

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

Einrichten des App-Frameworks

Über das Projektverzeichnis:

  1. Navigieren Sie zum Verzeichnis /src/main/java/com/queues/quickstart.
  2. Öffnen Sie die Datei App.java in Ihrem Editor.
  3. Löschen Sie die Anweisung System.out.println("Hello, world");.
  4. Fügen Sie Anweisungen vom Typ import hinzu.

Der Code lautet wie folgt:

package com.queues.quickstart;

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

public class App
{
    public static void main( String[] args ) throws IOException
    {
    }
}

Kopieren Ihrer Anmeldeinformationen aus dem Azure-Portal

Wenn die Beispielanwendung eine Anforderung an Azure Storage sendet, muss diese autorisiert werden. Fügen Sie zum Autorisieren einer Anforderung die Anmeldeinformationen für Ihr Speicherkonto in Form einer Verbindungszeichenfolge hinzu. Führen Sie zum Anzeigen der Anmeldeinformationen Ihres Speicherkontos die folgenden Schritte aus:

  1. Melden Sie sich beim Azure-Portal an.

  2. Suchen Sie nach Ihrem Speicherkonto.

  3. Wählen Sie im Speicherkonto-Menübereich unter Sicherheit + Netzwerkbetrieb die Option Zugriffsschlüssel aus. Hier können Sie die Kontozugriffsschlüssel und die vollständige Verbindungszeichenfolge für jeden Schlüssel anzeigen.

    Screenshot that shows where the access key settings are in the Azure portal

  4. Wählen Sie im Bereich Zugriffsschlüssel die Option Schlüssel anzeigen aus.

  5. Suchen Sie im Abschnitt key1 nach dem Wert Verbindungszeichenfolge. Wählen Sie das Symbol In Zwischenablage kopieren zum Kopieren der Verbindungszeichenfolge aus. Im nächsten Abschnitt fügen Sie den Wert der Verbindungszeichenfolge in eine Umgebungsvariable ein.

    Screenshot showing how to copy a connection string from the Azure portal

Konfigurieren der Speicherverbindungszeichenfolge

Schreiben Sie die Verbindungszeichenfolge nach dem Kopieren in eine neue Umgebungsvariable auf dem lokalen Computer, auf dem die Anwendung ausgeführt wird. Öffnen Sie zum Festlegen der Umgebungsvariablen ein Konsolenfenster, und befolgen Sie die Anleitung für Ihr Betriebssystem. Ersetzen Sie <yourconnectionstring> durch Ihre Verbindungszeichenfolge.

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

Sie müssen nach dem Hinzufügen der Umgebungsvariablen unter Windows eine neue Instanz des Befehlsfensters öffnen.

Neustarten von Programmen

Nachdem Sie die Umgebungsvariable hinzugefügt haben, starten Sie alle ausgeführten Programme neu, in denen die Umgebungsvariable gelesen werden muss. Starten Sie beispielsweise die Entwicklungsumgebung oder den Editor neu, bevor Sie fortfahren.

Objektmodell

Azure Queue Storage ist ein Dienst für die Speicherung großer Nachrichtenmengen. Eine Warteschlangennachricht kann bis zu 64 KB groß sein. Eine Warteschlange kann Millionen Nachrichten enthalten, bis die maximale Kapazität eines Speicherkontos erreicht ist. Warteschlangen werden häufig verwendet, um ein Arbeits-Backlog zur asynchronen Verarbeitung zu erstellen. Queue Storage bietet drei Arten von Ressourcen:

  • Das Speicherkonto
  • Eine Warteschlange im Speicherkonto
  • Nachrichten in der Warteschlange

Im folgenden Diagramm ist die Beziehung zwischen diesen Ressourcen dargestellt.

Diagram of Queue storage architecture

Verwenden Sie die folgenden Java-Klassen zur Interaktion mit folgenden Ressourcen:

  • QueueClientBuilder: Die QueueClientBuilder-Klasse konfiguriert und instanziiert ein QueueClient-Objekt.
  • QueueServiceClient: Mit dem QueueServiceClient können Sie alle Warteschlangen in Ihrem Speicherkonto verwalten.
  • QueueClient: Mit der QueueClient-Klasse können Sie eine einzelne Warteschlange und die darin enthaltenen Nachrichten verwalten und bearbeiten.
  • QueueMessageItem: Die QueueMessageItem-Klasse repräsentiert die einzelnen Objekte, die beim Aufrufen von ReceiveMessages in einer Warteschlange zurückgegeben werden.

Codebeispiele

Diese Beispielcodeausschnitte veranschaulichen, wie folgende Aktionen mit der Azure Queue Storage-Clientbibliothek für Java ausgeführt werden:

Abrufen der Verbindungszeichenfolge

Der folgende Code ruft die Verbindungszeichenfolge für das Speicherkonto ab. Die Verbindungszeichenfolge ist in der Umgebungsvariable gespeichert, die Sie im Abschnitt Konfigurieren der Speicherverbindungszeichenfolge erstellt haben.

Fügen Sie diesen Code in der main-Methode hinzu:

System.out.println("Azure Queue Storage client library v12 - 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");

Erstellen einer Warteschlange

Legen Sie einen Namen für die neue Warteschlange fest. Der folgende Code fügt einen GUID-Wert an den Warteschlangennnamen an, um sicherzustellen, dass er eindeutig ist.

Wichtig

Warteschlangennamen dürfen nur Kleinbuchstaben, Ziffern und Bindestriche enthalten und müssen mit einem Buchstaben oder einer Ziffer beginnen. Vor und nach jedem Bindestrich muss ein Zeichen stehen, das kein Bindestrich ist. Der Name muss außerdem zwischen 3 und 63 Zeichen lang sein. Weitere Informationen zum Benennen von Warteschlangen finden Sie unter Benennen von Warteschlangen und Metadaten.

Erstellen Sie eine Instanz der QueueClient-Klasse. Rufen Sie dann die Create-Methode auf, um die Warteschlange in Ihrem Speicherkonto zu erstellen.

Fügen Sie diesen Code am Ende der main-Methode hinzu:

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

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

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

// Create the queue
queueClient.create();

Hinzufügen von Nachrichten zu einer Warteschlange

Der folgende Codeausschnitt fügt der Warteschlange durch Aufrufen der sendMessage-Methode Nachrichten hinzu. Außerdem wird ein von einem sendMessage-Aufruf zurückgegebenes SendMessageResult gespeichert. Das Ergebnis wird später im Programm zum Aktualisieren der Nachricht verwendet.

Fügen Sie diesen Code am Ende der main-Methode hinzu:

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");

Einsehen von Nachrichten in einer Warteschlange

Durch Aufrufen der peekMessages-Methode können Sie die Nachrichten in der Warteschlange einsehen. Diese Methode ruft mindestens eine Nachricht vom Anfang der Warteschlange ab, ändert aber nicht die Sichtbarkeit der Nachricht.

Fügen Sie diesen Code am Ende der main-Methode hinzu:

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()));

Aktualisieren einer Nachricht in einer Warteschlange

Aktualisieren Sie den Inhalt einer Nachricht durch Aufrufen der updateMessage-Methode. Diese Methode kann das Sichtbarkeitstimeout und den Inhalt einer Nachricht ändern. Beim Nachrichteninhalt muss es sich um eine UTF-8-codierte Zeichenfolge handeln, die bis zu 64 KB groß sein darf. Übergeben Sie die Nachrichten-ID und die pop-Bestätigung zusammen mit dem neuen Inhalt für die Nachricht mithilfe des weiter oben im Code gespeicherten SendMessageResult-Objekts. Die Nachrichten-ID und die pop-Bestätigung identifizieren die Nachricht, die aktualisiert werden soll.

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));

Empfangen und Löschen von Nachrichten aus einer Warteschlange

Laden Sie zuvor hinzugefügte Nachrichten durch Aufrufen der receiveMessages-Methode herunter. Der Beispielcode löscht auch Nachrichten aus der Warteschlange, nachdem sie empfangen und verarbeitet wurden. In diesem Fall besteht die Verarbeitung nur darin, dass die Nachricht in der Konsole angezeigt wird.

Die App wird angehalten und wartet auf Benutzereingaben, indem System.console().readLine(); aufgerufen wird, bevor die Nachrichten empfangen und gelöscht werden. Überprüfen Sie im Azure-Portal, ob die Ressourcen ordnungsgemäß erstellt wurden, bevor sie gelöscht werden. Alle Nachrichten, die nicht explizit gelöscht werden, werden schlussendlich wieder in der Warteschlange angezeigt und ggf. erneut verarbeitet.

Fügen Sie diesen Code am Ende der main-Methode hinzu:

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());
    }
);

Löschen einer Warteschlange

Der folgende Code bereinigt die von der App erstellten Ressourcen, indem die Warteschlange mithilfe der Delete-Methode gelöscht wird.

Fügen Sie diesen Code am Ende der main-Methode hinzu:

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");

Ausführen des Codes

Diese App erstellt drei Nachrichten und fügt sie einer Azure-Warteschlange hinzu. Der Code listet die Nachrichten in der Warteschlange auf, ruft sie ab und löscht sie, bevor er letztendlich die Warteschlange löscht.

Navigieren Sie im Konsolenfenster zu Ihrem Anwendungsverzeichnis, erstellen Sie die Anwendung, und führen Sie sie aus.

mvn compile

Erstellen Sie dann das Paket.

mvn package

Führen Sie die App mit dem folgenden mvn-Befehl aus.

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

Die Ausgabe der App sieht etwa wie das folgende Beispiel aus:

Azure Queue Storage client library v12 - 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

Wenn die App vor dem Empfangen von Nachrichten angehalten wird, überprüfen Sie Ihr Speicherkonto im Azure-Portal. Überprüfen Sie, ob sich in der Warteschlange Nachrichten befinden.

Drücken Sie die Enter, um Nachrichten zu empfangen und zu löschen. Wenn Sie dazu aufgefordert werden, drücken Sie erneut die Enter, um die Warteschlange zu löschen und die Demo zu beenden.

Nächste Schritte

In dieser Schnellstartanleitung haben Sie gelernt, wie Sie mithilfe von Java-Code eine Warteschlange erstellen und dieser Nachrichten hinzufügen. Danach haben Sie erfahren, wie Sie Nachrichten einsehen, abrufen und löschen. Zum Schluss haben Sie gelernt, wie Sie eine Nachrichtenwarteschlange löschen.

Tutorials, Beispiele, Schnellstartanleitungen und weiteres Dokumentationsmaterial finden Sie hier: