Azure Storage Queue-Clientbibliothek für Java – Version 12.19.1

  • Artikel

Die Warteschlangenspeicherung in Azure ist ein Dienst zur Speicherung großer Anzahlen von Nachrichten, auf die von überall auf der Welt mit authentifizierten Anrufen über HTTP oder HTTPS zugegriffen werden kann. Eine einzelne Warteschlangennachricht kann bis zu 64 KB groß sein, und eine Warteschlange kann Millionen von Nachrichten enthalten. Deren Anzahl ist nur durch die Kapazität des Speicherkontos begrenzt.

Quellcode | API-Referenzdokumentation | Produktdokumentation | Beispiele

Erste Schritte

Voraussetzungen

Einschließen des Pakets

BOM-Datei einfügen

Fügen Sie das azure-sdk-bom in Ihr Projekt ein, um die Abhängigkeit von der GA-Version der Bibliothek zu übernehmen. Ersetzen Sie im folgenden Codeausschnitt den Platzhalter {bom_version_to_target} durch die Versionsnummer. Weitere Informationen zur Stückliste finden Sie in der AZURE SDK-BOM-INFODATEI.

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

und fügen Sie dann die direkte Abhängigkeit ohne Versions-Tag in den Abschnitt „Abhängigkeit“ ein.

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

Direkte Abhängigkeiten einfügen

Wenn Sie abhängigkeiten von einer bestimmten Version der Bibliothek übernehmen möchten, die in der Stückliste nicht vorhanden ist, fügen Sie die direkte Abhängigkeit wie folgt zu Ihrem Projekt hinzu.

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

Erstellen eines Speicherkontos

Zum Erstellen eines Speicherkontos können Sie das Azure-Portal oder die Azure CLI verwenden.

az storage account create \
    --resource-group <resource-group-name> \
    --name <storage-account-name> \
    --location <location>

Authentifizieren des Clients

Um mit dem Speicherdienst (Blob, Queue, Message, MessageId, File) zu interagieren, müssen Sie eine instance der Service Client-Klasse erstellen. Um dies zu ermöglichen, benötigen Sie die Konto-SAS-Zeichenfolge (Shared Access Signature) des Speicherkontos. Weitere Informationen finden Sie unter SAS-Token.

Anmeldeinformationen abrufen

  • SAS-Token

a. Verwenden Sie den folgenden Azure CLI-Codeausschnitt , um das SAS-Token aus dem Speicherkonto abzurufen.

az storage queue generate-sas
    --name {queue name}
    --expiry {date/time to expire SAS token}
    --permission {permission to grant}
    --connection-string {connection string of the storage account}

CONNECTION_STRING=<connection-string>
az storage queue generate-sas
    --name javasdksas
    --expiry 2019-06-05
    --permission rpau
    --connection-string $CONNECTION_STRING

b. Alternativ können Sie das KONTO-SAS-Token aus dem Azure-Portal abrufen.

Go to your storage account -> Shared access signature -> Click on Generate SAS and connection string (after setup)
  • Anmeldeinformationen für freigegebene Schlüssel

a. Verwenden Sie den Kontonamen und den Kontoschlüssel. Kontoname ist Der Name Ihres Speicherkontos.

// Here is where we get the key
Go to your storage account -> Access keys -> Key 1/ Key 2 -> Key

b. Verwenden des Verbindungszeichenfolge

// Here is where we get the key
Go to your storage account -> Access Keys -> Keys 1/ Key 2 -> Connection string

Wichtige Begriffe

URL-Format

Warteschlangen können mit dem folgenden URL-Format adressiert werden: Die folgende URL adressiert eine Warteschlange im Diagramm: https://myaccount.queue.core.windows.net/images-to-download

Syntax von Ressourcen-URIs

Für das Speicherkonto schließt der Basis-URI für Warteschlangenvorgänge nur den Namen des Kontos ein:

https://myaccount.queue.core.windows.net

Bei einer Warteschlange enthält der Basis-URI den Namen des Kontos und den Namen der Warteschlange:

https://myaccount.queue.core.windows.net/myqueue

Behandeln von Ausnahmen

Verwendet den abschnitt, der queueServiceClient unten aus dem Warteschlangendienstclient generiert wurde.

String queueServiceURL = String.format("https://%s.queue.core.windows.net", ACCOUNT_NAME);
QueueServiceClient queueServiceClient = new QueueServiceClientBuilder().endpoint(queueServiceURL)
    .sasToken(SAS_TOKEN).buildClient();
try {
    queueServiceClient.createQueue("myQueue");
} catch (QueueStorageException e) {
    logger.error("Failed to create a queue with error code: " + e.getErrorCode());
}

Warteschlangennamen

Jede Warteschlange innerhalb eines Kontos muss einen eindeutigen Namen haben. Der Warteschlangenname muss ein gültiger DNS-Name sein und kann nach der Erstellung nicht mehr geändert werden. Warteschlangennamen müssen die folgenden Regeln erfüllen:

  1. Ein Warteschlangenname muss mit einem Buchstaben oder einer Ziffer beginnen und darf nur Buchstaben, Ziffern und Bindestriche (-) enthalten.
  2. Der erste und der letzte Buchstabe im Warteschlangennamen müssen alphanumerisch sein. Der Bindestrich (-) darf nicht als erstes oder letztes Zeichen verwendet werden. Direkt aufeinander folgende Bindestriche sind im Warteschlangennamen nicht zulässig.
  3. Alle Buchstaben in einem Warteschlangennamen müssen Kleinbuchstaben sein.
  4. Ein Warteschlangenname muss zwischen 3 und 63 Zeichen lang sein.

Warteschlangendienste

Der Warteschlangendienst führen Vorgänge für die Warteschlangen im Speicherkonto aus und verwaltet die Warteschlangeneigenschaften.

Warteschlangendienstclient

Der Client führt die Interaktionen mit dem Warteschlangendienst aus, erstellt oder löscht eine Warteschlange, ruft Warteschlangeneigenschaften ab und legt sie fest, listet Warteschlangen im Konto auf und ruft Warteschlangenstatistiken ab. Im SDK ist ein asynchroner QueueServiceAsyncClient, und synchroner Client vorhanden, QueueClientder die Auswahl eines Clients basierend auf dem Anwendungsfall einer Anwendung ermöglicht. Sobald Sie über den Wert von SASToken verfügen, können Sie den Warteschlangendienstclient mit ${accountName}erstellen ${SASToken}.

String queueServiceURL = String.format("https://%s.queue.core.windows.net", ACCOUNT_NAME);
QueueServiceClient queueServiceClient = new QueueServiceClientBuilder().endpoint(queueServiceURL)
    .sasToken(SAS_TOKEN).buildClient();

QueueClient newQueueClient = queueServiceClient.createQueue("myQueue");

oder

String queueServiceAsyncURL = String.format("https://%s.queue.core.windows.net/", ACCOUNT_NAME);
QueueServiceAsyncClient queueServiceAsyncClient = new QueueServiceClientBuilder().endpoint(queueServiceAsyncURL)
    .sasToken(SAS_TOKEN).buildAsyncClient();
queueServiceAsyncClient.createQueue("newAsyncQueue").subscribe(result -> {
    // do something when new queue created
}, error -> {
    // do something if something wrong happened
}, () -> {
    // completed, do something
});

Warteschlange

Die Warteschlangenspeicherung in Azure ist ein Dienst zur Speicherung großer Anzahlen von Nachrichten, auf die von überall auf der Welt mit authentifizierten Anrufen über HTTP oder HTTPS zugegriffen werden kann. Eine einzelne Warteschlangennachricht kann bis zu 64 KB groß sein, und eine Warteschlange kann Millionen von Nachrichten enthalten. Deren Anzahl ist nur durch die Kapazität des Speicherkontos begrenzt.

QueueClient

Sobald Sie über den Wert von SASToken verfügen, können Sie den Warteschlangendienstclient mit ${accountName}, ${queueName}${SASToken}erstellen.

String queueURL = String.format("https://%s.queue.core.windows.net/%s", ACCOUNT_NAME, queueName);
QueueClient queueClient = new QueueClientBuilder().endpoint(queueURL).sasToken(SAS_TOKEN).buildClient();

// metadata is map of key-value pair
queueClient.createWithResponse(metadata, Duration.ofSeconds(30), Context.NONE);

oder

// Only one "?" is needed here. If the sastoken starts with "?", please removing one "?".
String queueAsyncURL = String.format("https://%s.queue.core.windows.net/%s?%s", ACCOUNT_NAME, queueAsyncName,
    SAS_TOKEN);
QueueAsyncClient queueAsyncClient = new QueueClientBuilder().endpoint(queueAsyncURL).buildAsyncClient();
queueAsyncClient.createWithResponse(metadata).subscribe(result -> {
    // do something when new queue created
}, error -> {
    // do something if something wrong happened
}, () -> {
    // completed, do something
});

Beispiele

Die folgenden Abschnitte enthalten mehrere Codeausschnitte, die einige der gängigsten Configuration Service-Aufgaben behandeln, einschließlich:

Erstellen eines Clients

Wir haben zwei Möglichkeiten, QueueService oder Warteschlangenclient zu erstellen. Hier wird queueServiceClient als Beispiel angegeben. Gleiches gilt für queueClient.

Erstellen Sie zunächst den Client aus der vollständigen URL/dem Endpunkt (z. B. mit queueName, mit SASToken usw.).

// Only one "?" is needed here. If the sastoken starts with "?", please removing one "?".
String queueServiceURL = String.format("https://%s.queue.core.windows.net/?%s", ACCOUNT_NAME, SAS_TOKEN);
QueueServiceClient queueServiceClient = new QueueServiceClientBuilder().endpoint(queueServiceURL).buildClient();

oder

Wir können den queueServiceClient aus dem Generator mit ${SASToken} als Anmeldeinformationen erstellen.

String queueServiceURL = String.format("https://%s.queue.core.windows.net", ACCOUNT_NAME);
QueueServiceClient queueServiceClient = new QueueServiceClientBuilder().endpoint(queueServiceURL)
        .sasToken(SAS_TOKEN).buildClient();

Erstellen einer Warteschlange

Erstellen Sie eine Warteschlange im Speicherkonto mit ${SASToken} als Anmeldeinformationen. Löst StorageException aus, wenn die Warteschlange nicht erstellt werden kann.

String queueServiceURL = String.format("https://%s.queue.core.windows.net", ACCOUNT_NAME);
QueueServiceClient queueServiceClient = new QueueServiceClientBuilder().endpoint(queueServiceURL)
    .sasToken(SAS_TOKEN).buildClient();

QueueClient newQueueClient = queueServiceClient.createQueue("myQueue");

Löschen einer Warteschlange

Löschen Sie eine Warteschlange im Speicherkonto mit ${SASToken} als Anmeldeinformationen. Löst StorageException aus, wenn die Warteschlange nicht gelöscht werden kann.

String queueServiceURL = String.format("https://%s.queue.core.windows.net", ACCOUNT_NAME);
QueueServiceClient queueServiceClient = new QueueServiceClientBuilder().endpoint(queueServiceURL)
        .sasToken(SAS_TOKEN).buildClient();

queueServiceClient.deleteQueue("myqueue");

Auflisten von Warteschlangen im Konto

Listet alle Warteschlangen im Konto mit ${SASToken} als Anmeldeinformationen auf.

String queueServiceURL = String.format("https://%s.queue.core.windows.net", ACCOUNT_NAME);
QueueServiceClient queueServiceClient = new QueueServiceClientBuilder().endpoint(queueServiceURL)
        .sasToken(SAS_TOKEN).buildClient();
// @param marker: Starting point to list the queues
// @param options: Filter for queue selection
// @param timeout: An optional timeout applied to the operation.
// @param context: Additional context that is passed through the Http pipeline during the service call.
queueServiceClient.listQueues(options, timeout, context).stream().forEach(queueItem ->
    System.out.printf("Queue %s exists in the account.", queueItem.getName()));

Abrufen von Eigenschaften im Warteschlangenkonto

Ruft Warteschlangeneigenschaften im Konto ab, einschließlich Eigenschaften für Storage Analytics- und CORS-Regeln (Cross-Origin Resource Sharing).

Verwenden Sie ${SASToken} als Anmeldeinformationen.

String queueServiceURL = String.format("https://%s.queue.core.windows.net", ACCOUNT_NAME);
QueueServiceClient queueServiceClient = new QueueServiceClientBuilder().endpoint(queueServiceURL)
        .sasToken(SAS_TOKEN).buildClient();

QueueServiceProperties properties = queueServiceClient.getProperties();

Festlegen von Eigenschaften im Warteschlangenkonto

Legen Sie Warteschlangeneigenschaften im Konto fest, einschließlich Eigenschaften für Storage Analytics- und CORS-Regeln (Cross-Origin Resource Sharing).

Verwenden Sie ${SASToken} als Anmeldeinformationen.

String queueServiceURL = String.format("https://%s.queue.core.windows.net", ACCOUNT_NAME);
QueueServiceClient queueServiceClient = new QueueServiceClientBuilder().endpoint(queueServiceURL)
        .sasToken(SAS_TOKEN).buildClient();

QueueServiceProperties properties = queueServiceClient.getProperties();
properties.setCors(Collections.emptyList());
queueServiceClient.setProperties(properties);

Abrufen von Warteschlangendienststatistiken

Der Get Queue Service Stats-Vorgang ruft Statistiken zur Replikation für den Warteschlangendienst ab.

Verwenden Sie ${SASToken} als Anmeldeinformationen. Er ist nur über den sekundären Standortendpunkt verfügbar, wenn die georedundante Replikation mit Lesezugriff für das Speicherkonto aktiviert ist.

String queueServiceURL = String.format("https://%s.queue.core.windows.net", ACCOUNT_NAME);
QueueServiceClient queueServiceClient = new QueueServiceClientBuilder().endpoint(queueServiceURL)
        .sasToken(SAS_TOKEN).buildClient();

QueueServiceStatistics queueStats = queueServiceClient.getStatistics();

Nachricht in eine Warteschlange einreihen

Der Vorgang fügt eine neue Nachricht auf der Rückseite der Nachrichtenwarteschlange hinzu. Es kann auch ein Sichtbarkeitstimeout angegeben werden, um die Nachricht nicht sichtbar zu machen, bis das Sichtbarkeitstimeout abläuft.

Verwenden Sie ${SASToken} als Anmeldeinformationen. Nachrichten müssen ein Format aufweisen, das in eine XML-Anforderung mit UTF-8-Codierung eingeschlossen werden kann. Die Größe der codierten Nachricht kann für Version 2011-08-18 und höher bis zu 64 KB und für frühere Versionen bis zu 8 KB betragen.

String queueURL = String.format("https://%s.queue.core.windows.net", ACCOUNT_NAME);
QueueClient queueClient = new QueueClientBuilder().endpoint(queueURL).sasToken(SAS_TOKEN).queueName("myqueue")
        .buildClient();

queueClient.sendMessage("myMessage");

Aktualisieren einer Nachricht in einer Warteschlange

Der Vorgang aktualisiert eine Nachricht in der Nachrichtenwarteschlange. Verwenden Sie ${SASToken} als Anmeldeinformationen.

String queueURL = String.format("https://%s.queue.core.windows.net", ACCOUNT_NAME);
QueueClient queueClient = new QueueClientBuilder().endpoint(queueURL).sasToken(SAS_TOKEN).queueName("myqueue")
        .buildClient();
// @param messageId: Id of the message
// @param popReceipt: Unique identifier that must match the message for it to be updated
// @param visibilityTimeout: How long the message will be invisible in the queue in seconds
queueClient.updateMessage(messageId, popReceipt, "new message", visibilityTimeout);

Einsehen von Nachrichten in einer Warteschlange

Der Vorgang sieht eine oder mehrere Nachrichten von der Vorderseite der Warteschlange ein. Verwenden Sie ${SASToken} als Anmeldeinformationen.

String queueURL = String.format("https://%s.queue.core.windows.net", ACCOUNT_NAME);
QueueClient queueClient = new QueueClientBuilder().endpoint(queueURL).sasToken(SAS_TOKEN).queueName("myqueue")
        .buildClient();
// @param key: The key with which the specified value should be associated.
// @param value: The value to be associated with the specified key.
queueClient.peekMessages(5, Duration.ofSeconds(1), new Context(key, value)).forEach(message ->
    System.out.println(message.getBody().toString()));

Empfangen von Nachrichten aus einer Warteschlange

Der Vorgang ruft eine oder mehrere Nachrichten von der Vorderseite der Warteschlange ab. Verwenden Sie ${SASToken} als Anmeldeinformationen.

String queueURL = String.format("https://%s.queue.core.windows.net", ACCOUNT_NAME);
QueueClient queueClient = new QueueClientBuilder().endpoint(queueURL).sasToken(SAS_TOKEN).queueName("myqueue")
        .buildClient();
// Try to receive 10 messages: Maximum number of messages to get
queueClient.receiveMessages(10).forEach(message ->
    System.out.println(message.getBody().toString()));

Löschen einer Nachricht aus einer Warteschlange

Der Vorgang löscht eine Nachricht aus der Warteschlange. Verwenden Sie ${SASToken} als Anmeldeinformationen.

String queueURL = String.format("https://%s.queue.core.windows.net", ACCOUNT_NAME);
QueueClient queueClient = new QueueClientBuilder().endpoint(queueURL).sasToken(SAS_TOKEN).queueName("myqueue")
        .buildClient();

queueClient.deleteMessage(messageId, popReceipt);

Abrufen von Warteschlangeneigenschaften

Der Vorgang ruft benutzerdefinierte Metadaten und Warteschlangeneigenschaften für die angegebene Warteschlange ab. Metadaten werden der Warteschlange als Name-Wert-Paare zugeordnet.

Verwenden Sie ${SASToken} als Anmeldeinformationen.

String queueURL = String.format("https://%s.queue.core.windows.net", ACCOUNT_NAME);
QueueClient queueClient = new QueueClientBuilder().endpoint(queueURL).sasToken(SAS_TOKEN).queueName("myqueue")
        .buildClient();

QueueProperties properties = queueClient.getProperties();

Festlegen von Warteschlangenmetadaten

Der Vorgang legt benutzerdefinierte Metadaten für die angegebene Warteschlange fest. Metadaten werden der Warteschlange als Name-Wert-Paare zugeordnet.

Verwenden Sie ${SASToken} als Anmeldeinformationen.

String queueURL = String.format("https://%s.queue.core.windows.net", ACCOUNT_NAME);
QueueClient queueClient = new QueueClientBuilder().endpoint(queueURL).sasToken(SAS_TOKEN).queueName("myqueue")
        .buildClient();

Map<String, String> metadata = new HashMap<>();
metadata.put("key1", "val1");
metadata.put("key2", "val2");
queueClient.setMetadata(metadata);

Problembehandlung

Allgemein

Wenn Sie mit der Warteschlange mithilfe dieser Java-Clientbibliothek interagieren, entsprechen vom Dienst zurückgegebene Fehler denselben HTTP-status Codes, die für REST-API-Anforderungen zurückgegeben werden. Wenn Sie beispielsweise versuchen, eine Warteschlange abzurufen, die in Ihrem Speicherkonto nicht vorhanden ist, wird ein 404 Fehler zurückgegeben, der angibt Not Found.

HTTP-Standardclient

Alle Clientbibliotheken verwenden standardmäßig den Netty-HTTP-Client. Durch Hinzufügen der obigen Abhängigkeit wird die Clientbibliothek automatisch für die Verwendung des Netty-HTTP-Clients konfiguriert. Das Konfigurieren oder Ändern des HTTP-Clients wird detailliert im Wiki zu HTTP-Clients beschrieben.

SSL-Standardbibliothek

Alle Clientbibliotheken verwenden standardmäßig die Tomcat-native Boring-SSL-Bibliothek, um die Leistung auf nativer Ebene für SSL-Vorgänge zu ermöglichen. Die Boring-SSL-Bibliothek ist eine Uber-JAR-Datei mit nativen Bibliotheken für Linux/macOS/Windows und bietet im Vergleich zur SSL-Standardimplementierung im JDK eine bessere Leistung. Weitere Informationen, einschließlich zur Reduzierung der Abhängigkeitsgröße, finden Sie im Abschnitt Leistungsoptimierung des Wikis.

Nächste Schritte

Im GitHub-Repository des SDK stehen Ihnen mehrere Beispiele für das Java SDK zur Verfügung. Diese Beispiele enthalten Beispielcode für zusätzliche Szenarien, die häufig bei der Arbeit mit Key Vault auftreten:

Beispiele für nächste Schritte

Die Beispiele werden hier ausführlich erläutert.

Mitwirken

Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Ausführliche Informationen finden Sie unter https://cla.microsoft.com.

Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen (z.B. mit einer Bezeichnung oder einem Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Repositorys ausführen, die unsere CLA verwenden.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.

Ausführliche Informationen zum Mitwirken an diesem Repository finden Sie im Leitfaden zum Mitwirken.

  1. Verzweigen sie
  2. Erstellen Ihrer Featurebranch (git checkout -b my-new-feature)
  3. Committen Ihrer Änderungen (git commit -am 'Add some feature')
  4. Pushen in den Branch (git push origin my-new-feature)
  5. Erstellen eines neuen Pull Requests

Aufrufe