Freigeben über

Schnellstart: Azure Queue Storage-Clientbibliothek für Java

Erste Schritte mit der Azure Queue Storage-Clientbibliothek für Java. Azure Queue Storage ist ein Dienst zum Speichern großer Anzahl von Nachrichten zum späteren Abrufen und Verarbeiten. Führen Sie die folgenden Schritte aus, um das Paket zu installieren und Beispielcode für grundlegende Aufgaben auszuprobieren.

API-Referenzdokumentation | Quellcode | der BibliothekPaket (Maven) | Proben

Verwenden Sie die Azure Queue Storage-Clientbibliothek für Java, um:

  • Erstellen einer Warteschlange
  • Hinzufügen von Nachrichten zu einer Warteschlange
  • Nachrichten in einer Warteschlange einsehen
  • Aktualisieren einer Nachricht in einer Warteschlange
  • Die Warteschlangenlänge abrufen
  • Empfangen von Nachrichten aus einer Warteschlange
  • Löschen von Nachrichten aus einer Warteschlange
  • Löschen einer Warteschlange

Voraussetzungen

Einrichten

Dieser Abschnitt führt Sie durch die Vorbereitung eines Projekts für die Arbeit mit der Azure Queue Storage-Clientbibliothek für Java.

Erstelle das Projekt

Erstellen Sie eine Java-Anwendung namens "Queues-Quickstart".

  1. Verwenden Sie in einem Konsolenfenster (z. B. cmd, PowerShell oder Bash) Maven, um eine neue Konsolen-App mit dem Namen queues-quickstart zu erstellen. Geben Sie den folgenden mvn Befehl ein, um ein "Hello, world!" zu erstellen. Java-Projekt.

    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. 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
[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. Wechseln Sie zum neu erstellten queues-quickstart-Verzeichnis.

    cd queues-quickstart

Installieren der Pakete

Öffnen Sie die Datei pom.xml in Ihrem Text-Editor.

Fügen Sie azure-sdk-bom hinzu, um eine Abhängigkeit von der neuesten Version der Bibliothek zu übernehmen. Ersetzen Sie im folgenden Codeausschnitt den {bom_version_to_target} Platzhalter durch die Versionsnummer. Die Verwendung von azure-sdk-bom verhindert, dass Sie die Version jeder einzelnen Abhängigkeit angeben müssen. Weitere Informationen zur BOM finden Sie im Azure SDK BOM README.

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

Fügen Sie dann der Gruppe der Abhängigkeiten die folgenden Abhängigkeitselemente hinzu. Die Azure-Identity-Abhängigkeit wird für kennwortlose Verbindungen mit Azure-Diensten benötigt.

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

Einrichten des App-Frameworks

Aus dem Projektverzeichnis:

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

Der Code lautet wie folgt:

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

Für Azure authentifizieren

Anwendungsanforderungen an die meisten Azure-Dienste müssen autorisiert werden. Die Verwendung der DefaultAzureCredential von der Azure Identity-Clientbibliothek bereitgestellten Klasse ist der empfohlene Ansatz für die Implementierung kennwortloser Verbindungen mit Azure-Diensten in Ihrem Code.

Sie können Auch Anforderungen an Azure-Dienste mithilfe von Kennwörtern, Verbindungszeichenfolgen oder anderen Anmeldeinformationen direkt autorisieren. Dieser Ansatz sollte jedoch mit Vorsicht verwendet werden. Entwickler müssen fleißig sein, diese Geheimnisse niemals an einem unsicheren Ort verfügbar zu machen. Jeder, der Zugriff auf das Kennwort oder den geheimen Schlüssel erhält, kann sich authentifizieren. DefaultAzureCredential bietet verbesserte Verwaltungs- und Sicherheitsvorteile gegenüber dem Kontoschlüssel, um die kennwortlose Authentifizierung zu ermöglichen. Beide Optionen werden im folgenden Beispiel veranschaulicht.

DefaultAzureCredential ist eine Klasse, die von der Azure Identity-Clientbibliothek für Java bereitgestellt wird. Weitere DefaultAzureCredentialInformationen finden Sie in der Übersicht über DefaultAzureCredential. DefaultAzureCredential unterstützt mehrere Authentifizierungsmethoden und bestimmt, welche Methode zur Laufzeit verwendet werden soll. Mit diesem Ansatz kann Ihre App unterschiedliche Authentifizierungsmethoden in verschiedenen Umgebungen (lokal im Vergleich zur Produktion) verwenden, ohne umgebungsspezifischen Code zu implementieren.

Ihre App kann sich beispielsweise bei der lokalen Entwicklung mithilfe Ihrer Azure CLI-Anmeldeinformationen authentifizieren und dann eine verwaltete Identität verwenden, nachdem sie in Azure bereitgestellt wurde. Für diesen Übergang sind keine Änderungen am Code erforderlich.

Stellen Sie beim lokalen Entwickeln sicher, dass das Benutzerkonto, das auf die Warteschlangendaten zugreift, über die richtigen Berechtigungen verfügt. Sie benötigen Storage Queue Data Contributor, um Warteschlangendaten zu lesen und zu schreiben. Um sich selbst diese Rolle zuweisen zu können, benötigen Sie die Rolle Benutzerzugriffsadministrator oder eine andere Rolle, die die Aktion Microsoft.Authorization/roleAssignments/Write enthält. Sie können einem Benutzer Azure RBAC-Rollen über das Azure-Portal, die Azure CLI oder mit Azure PowerShell zuweisen. Weitere Informationen zu den verfügbaren Bereichen für Rollenzuweisungen finden Sie auf der Seite Bereichsübersicht.

In diesem Szenario weisen Sie Ihrem Benutzerkonto Berechtigungen zu, die auf das Speicherkonto festgelegt sind, um dem Prinzip der geringsten Rechte zu folgen. Auf diese Weise erhalten Benutzer nur die erforderlichen Mindestberechtigungen, und es entstehen sicherere Produktionsumgebungen.

Im folgenden Beispiel wird Ihrem Benutzerkonto die Rolle "Beitragsberechtigter für Speicherwarteschlangendaten" zugewiesen, die sowohl Lese- als auch Schreibzugriff auf Warteschlangendaten in Ihrem Storage-Konto gewährt.

Von Bedeutung

In den meisten Fällen dauert es eine oder zwei Minute(n), bis die Rollenzuweisung in Azure weitergegeben wird. In seltenen Fällen kann es aber bis zu acht Minuten dauern. Wenn bei der ersten Ausführung Ihres Codes Authentifizierungsfehler auftreten, warten Sie einige Momente, und versuchen Sie es dann erneut.

  1. Suchen Sie im Azure-Portal Ihr Speicherkonto mithilfe der Hauptsuchleiste oder der linken Navigationsleiste.

  2. Wählen Sie auf der Übersichtsseite des Speicherkontos im linken Menü die Zugriffssteuerung (IAM) aus.

  3. Wählen Sie auf der Seite Zugriffssteuerung (IAM) die Registerkarte Rollenzuweisungen aus.

  4. Wählen Sie im oberen Menü +Hinzufügen aus, und fügen Sie dann die Rollenzuweisung aus dem resultierenden Dropdownmenü hinzu.

Ein Screenshot zeigt, wie eine Rolle zugewiesen wird.

  1. Über das Suchfeld können Sie die Ergebnisse für die gewünschte Rolle filtern. Suchen Sie in diesem Beispiel nach Mitwirkender an Speicherwarteschlangendaten, und wählen Sie das übereinstimmende Ergebnis und dann Weiter aus.

  2. Wählen Sie unter Zugriff zuweisen zu die Option Benutzer, Gruppe oder Dienstprinzipal und dann die Option + Mitglieder auswählen aus.

  3. Suchen Sie im Dialogfeld nach Ihrem Microsoft Entra-Benutzernamen (in der Regel Ihre user@domain-E-Mail-Adresse), und wählen Sie dann unten im Dialogfeld Auswählen aus.

  4. Wählen Sie Überprüfen und zuweisen aus, um zur letzten Seite zu gelangen, und wählen Sie erneut Überprüfen und zuweisen aus, um den Vorgang abzuschließen.

Objektmodell

Azure Queue Storage ist ein Dienst zum Speichern großer Anzahl von Nachrichten. Eine Warteschlangennachricht kann bis zu 64 KB groß sein. Eine Warteschlange kann Millionen von Nachrichten bis zum Gesamtkapazitätslimit eines Speicherkontos enthalten. Warteschlangen werden häufig verwendet, um einen Arbeitsbestand zu erstellen, der asynchron verarbeitet werden kann. Queue Storage bietet drei Arten von Ressourcen:

  • Speicherkonto: Der gesamte Zugriff auf Azure Storage erfolgt über ein Speicherkonto. Weitere Informationen zu Speicherkonten finden Sie unter Übersicht über das Speicherkonto
  • Warteschlange: Eine Warteschlange enthält eine Reihe von Nachrichten. Alle Nachrichten müssen sich in einer Warteschlange befinden. Beachten Sie, dass der Warteschlangenname in Kleinbuchstaben geschrieben sein muss. Informationen zu Benennungswarteschlangen finden Sie unter Benennen von Warteschlangen und Metadaten.
  • Nachricht: Eine Nachricht in einem beliebigen Format von bis zu 64 KB. Eine Nachricht kann maximal 7 Tage lang in der Warteschlange verbleiben. Für Version 2017-07-29 oder höher kann die maximale Zeit bis zum Live eine beliebige positive Zahl sein, oder -1 angibt, dass die Nachricht nicht abläuft. Wenn dieser Parameter nicht angegeben wird, beträgt die Standardzeit für die Lebensdauer sieben Tage.

Das folgende Diagramm zeigt die Beziehung zwischen diesen Ressourcen.

Diagramm der Architektur des Warteschlangenspeichers

Verwenden Sie die folgenden Java-Klassen, um mit diesen Ressourcen zu interagieren:

  • QueueClientBuilder: Die QueueClientBuilder Klasse konfiguriert und instanziiert ein QueueClient Objekt.
  • QueueServiceClient: Mit QueueServiceClient dieser Option können Sie alle Warteschlangen in Ihrem Speicherkonto verwalten.
  • QueueClient: Mit der QueueClient Klasse können Sie eine einzelne Warteschlange und deren Nachrichten verwalten und bearbeiten.
  • QueueMessageItem: Die QueueMessageItem-Klasse repräsentiert die individuellen Objekte, die bei einem Aufruf von ReceiveMessages auf einer Warteschlange zurückgegeben werden.

Code-Beispiele

Diese Beispielcodeausschnitte zeigen Ihnen, wie Sie die folgenden Aktionen mit der Azure Queue Storage-Clientbibliothek für Java ausführen:

Autorisieren des Zugriffs und Erstellen eines Clientobjekts

Stellen Sie sicher, dass Sie mit demselben Microsoft Entra-Konto authentifiziert sind, dem Sie die Rolle zugewiesen haben. Sie können sich über Azure CLI, Visual Studio Code oder Azure PowerShell authentifizieren.

Melden Sie sich mit dem folgenden Befehl über die Azure-Befehlszeilenschnittstelle bei Azure an:

az login

Nach der Authentifizierung können Sie ein QueueClient Objekt erstellen und autorisieren, um auf Warteschlangendaten im Speicherkonto zuzugreifen, indem Sie DefaultAzureCredential verwenden. DefaultAzureCredential ermittelt und verwendet automatisch das Konto, mit dem Sie sich im vorherigen Schritt angemeldet haben.

Um die Verwendung DefaultAzureCredentialzu autorisieren, stellen Sie sicher, dass Sie die Azure-Identity-Abhängigkeitpom.xmlhinzugefügt haben, wie in "Installieren der Pakete" beschrieben. Stellen Sie außerdem sicher, dass eine Import-Anweisung für com.azure.identity in die Datei App.java hinzugefügt wird.

import com.azure.identity.*;

Entscheiden Sie sich für einen Namen für die Warteschlange und erstellen Sie eine Instanz der QueueClient Klasse unter Verwendung von DefaultAzureCredential zur Autorisierung. Wir verwenden dieses Client-Objekt, um die Warteschlangenressource im Speicherkonto zu erstellen und mit ihr zu interagieren.

Von Bedeutung

Warteschlangennamen dürfen nur Kleinbuchstaben, Zahlen und Bindestriche enthalten und müssen mit einem Buchstaben oder einer Zahl beginnen. Vor und nach jedem Bindestrich muss ein Zeichen stehen, das kein Bindestrich ist. Der Name muss auch zwischen 3 und 63 Zeichen lang sein. Weitere Informationen zu Benennungswarteschlangen finden Sie unter Benennungswarteschlangen und Metadaten.

Fügen Sie diesen Code innerhalb der main Methode hinzu, und stellen Sie sicher, dass Sie den <storage-account-name> Platzhalterwert ersetzen:

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

Hinweis

Nachrichten, die mit der QueueClient Klasse gesendet werden, müssen in einem Format vorliegen, das in einer XML-Anforderung mit UTF-8-Codierung enthalten sein kann. Optionalerweise können Sie die QueueMessageEncoding-Option auf BASE64 festlegen, um nicht kompatible Nachrichten zu verarbeiten.

Erstellen einer Warteschlange

Rufen Sie mithilfe des QueueClient Objekts die create Methode auf, um die Warteschlange in Ihrem Speicherkonto zu erstellen.

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

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

// Create the queue
queueClient.create();

Hinzufügen von Nachrichten zu einer Warteschlange

Der folgende Codeausschnitt fügt nachrichten zur Warteschlange hinzu, indem die sendMessage Methode aufgerufen wird. Außerdem speichert er einen SendMessageResult, der von einem sendMessage-Aufruf zurückgegeben wird. Das Ergebnis wird verwendet, um die Nachricht später im Programm zu aktualisieren.

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

Nachrichten in einer Warteschlange einsehen

Werfen Sie einen Blick auf die Nachrichten in der Warteschlange, indem Sie die peekMessages Methode aufrufen. Diese Methode ruft eine oder mehrere Nachrichten von der Vorderseite der Warteschlange ab, ändert jedoch 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, indem Sie die updateMessage Methode aufrufen. Diese Methode kann das Sichtbarkeits-Timeout und den Inhalt einer Nachricht ändern. Der Nachrichteninhalt muss eine UTF-8-codierte Zeichenfolge sein, die bis zu 64 KB groß ist. Ü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, welche Nachricht 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));

Die Warteschlangenlänge abrufen

Sie können eine Schätzung der Anzahl der Nachrichten in einer Warteschlange erhalten.

Die getProperties Methode gibt mehrere Werte zurück, einschließlich der Anzahl der Nachrichten, die sich derzeit in einer Warteschlange befinden. Die Anzahl ist nur ungefähr, da Nachrichten nach Ihrer Anforderung hinzugefügt oder entfernt werden können. Die Methode getApproximateMessageCount gibt den letzten Wert zurück, der durch den Aufruf von getProperties ermittelt wurde, ohne dass Queue Storage aufgerufen wird.

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

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

Empfangen und Löschen von Nachrichten aus einer Warteschlange

Laden Sie zuvor hinzugefügte Nachrichten herunter, indem Sie die receiveMessages Methode aufrufen. Der Beispielcode löscht auch Nachrichten aus der Warteschlange, nachdem sie empfangen und verarbeitet wurden. In diesem Fall zeigt die Verarbeitung nur die Meldung auf der Konsole an.

Die App pausiert durch einen Aufruf von System.console().readLine();, um Benutzereingaben zu erhalten, bevor sie die Nachrichten empfängt und löscht. Überprüfen Sie in Ihrem Azure-Portal , ob die Ressourcen ordnungsgemäß erstellt wurden, bevor sie gelöscht werden. Alle Nachrichten, die nicht explizit gelöscht wurden, werden schließlich wieder in der Warteschlange sichtbar, um eine weitere Möglichkeit zur Bearbeitung zu erhalten.

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

Beim Aufrufen der receiveMessages Methode können Sie optional einen Wert angeben, für maxMessagesden es sich um die Anzahl der Nachrichten handelt, die aus der Warteschlange abgerufen werden sollen. Der Standardwert ist 1 Nachricht und maximal 32 Nachrichten. Sie können auch einen Wert für visibilityTimeout angeben, bei dem Nachrichten von anderen Vorgängen für den Timeoutzeitraum ausgeblendet werden. Der Standardwert ist 30 Sekunden.

Löschen einer Warteschlange

Der folgende Code bereinigt die Ressourcen, die die App durch Löschen der Warteschlange mithilfe der Delete Methode erstellt hat.

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 und fügt einer Azure-Warteschlange drei Nachrichten hinzu. Der Code listet die Nachrichten in der Warteschlange auf, ruft sie dann ab und löscht sie, bevor die Warteschlange endgültig gelöscht wird.

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

mvn compile

Erstellen Sie dann das Paket.

mvn package

Verwenden Sie den folgenden mvn Befehl, um die App auszuführen.

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

Die Ausgabe der App ähnelt dem folgenden Beispiel:

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

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

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

Nächste Schritte

In dieser Schnellstartanleitung haben Sie erfahren, wie Sie eine Warteschlange erstellen und ihr Nachrichten mithilfe von Java-Code hinzufügen. Dann haben Sie gelernt, Nachrichten anzuzeigen, abzurufen und zu löschen. Schließlich haben Sie erfahren, wie Sie eine Nachrichtenwarteschlange löschen.

Für Lernprogramme, Beispiele, Schnellstarts und andere Dokumentationen besuchen Sie:

Azure für Java-Cloudentwickler

  • Last updated on