Quickstart: Azure Queue Storage-clientbibliotheek voor Java

  • Artikel

Aan de slag met de Azure Queue Storage-clientbibliotheek voor Java. Azure Queue Storage is een service waarmee u grote aantallen berichten kunt opslaan om later op te halen en te verwerken. Volg deze stappen om het pakket te installeren en voorbeeldcode voor basistaken uit te proberen.

API-referentiedocumentatie | Broncode van bibliotheek | Pakket (Maven) | Samples

Gebruik de Azure Queue Storage-clientbibliotheek voor Java om het volgende te doen:

  • Een wachtrij maken
  • Berichten aan een wachtrij toevoegen
  • Berichten in een wachtrij bekijken
  • Een bericht in een wachtrij bijwerken
  • Lengte van de wachtrij ophalen
  • Berichten van een wachtrij ontvangen
  • Berichten uit een wachtrij verwijderen
  • Een wachtrij verwijderen

Vereisten

Instellen

In deze sectie wordt uitgelegd hoe u een project voorbereidt voor gebruik met de Azure Queue Storage-clientbibliotheek voor Java.

Het project maken

Maak een Java-toepassing met de naam wachtrijen-quickstart.

  1. Gebruik Maven in een consolevenster (zoals cmd, PowerShell of Bash) om een nieuwe console-app te maken met de quickstart voor naamwachtrijen. Typ de volgende mvn opdracht om een 'Hallo wereld!' te maken Java-project.

    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. De uitvoer van het project zou er ongeveer als volgt moeten uitzien:

    [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. Schakel over naar de zojuist gemaakte wachtrijen-quickstart-map .

    cd queues-quickstart

De pakketten installeren

Open het pom.xml bestand in de teksteditor.

Voeg azure-sdk-bom toe om een afhankelijkheid te maken van de nieuwste versie van de bibliotheek. Vervang in het volgende codefragment de {bom_version_to_target} tijdelijke aanduiding door het versienummer. Als u azure-sdk-bom gebruikt, hoeft u niet de versie van elke afzonderlijke afhankelijkheid op te geven. Zie de Azure SDK BOM README voor meer informatie over de BOM.

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

Voeg vervolgens de volgende afhankelijkheidselementen toe aan de groep afhankelijkheden. De azure-identity-afhankelijkheid is nodig voor verbindingen zonder wachtwoord met Azure-services.

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

Stel het app-framework in

Ga als volgt te werk vanuit de projectmap:

  1. Ga naar de map /src/main/java/com/queues/quickstart
  2. Open het bestand App.java in uw editor
  3. Verwijder de System.out.println("Hello, world");-instructie
  4. Voeg import-instructies toe

Hier volgt de code:

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

Verifiëren bij Azure

Toepassingsaanvragen voor de meeste Azure-services moeten worden geautoriseerd. Het gebruik van de DefaultAzureCredential klasse die wordt geleverd door de Azure Identity-clientbibliotheek is de aanbevolen methode voor het implementeren van wachtwoordloze verbindingen met Azure-services in uw code.

U kunt aanvragen voor Azure-services ook rechtstreeks autoriseren met behulp van wachtwoorden, verbindingsreeks s of andere referenties. Deze aanpak moet echter met voorzichtigheid worden gebruikt. Ontwikkelaars moeten ijverig zijn om deze geheimen nooit zichtbaar te maken op een onbeveiligde locatie. Iedereen die toegang krijgt tot het wachtwoord of de geheime sleutel, kan worden geverifieerd. DefaultAzureCredential biedt verbeterde beheer- en beveiligingsvoordelen ten opzichte van de accountsleutel om verificatie zonder wachtwoord mogelijk te maken. Beide opties worden in het volgende voorbeeld gedemonstreerd.

DefaultAzureCredential is een klasse die wordt geleverd door de Azure Identity-clientbibliotheek voor Java. Zie het overzicht DefaultAzureCredential voor meer DefaultAzureCredentialinformatie. DefaultAzureCredential ondersteunt meerdere verificatiemethoden en bepaalt welke methode tijdens runtime moet worden gebruikt. Met deze aanpak kan uw app verschillende verificatiemethoden gebruiken in verschillende omgevingen (lokaal versus productie) zonder omgevingsspecifieke code te implementeren.

Uw app kan bijvoorbeeld verifiëren met behulp van uw Aanmeldingsreferenties voor Azure CLI bij het lokaal ontwikkelen en vervolgens een beheerde identiteit gebruiken zodra deze is geïmplementeerd in Azure. Er zijn geen codewijzigingen vereist voor deze overgang.

Wanneer u lokaal ontwikkelt, moet u ervoor zorgen dat het gebruikersaccount dat toegang heeft tot de wachtrijgegevens over de juiste machtigingen beschikt. U hebt Inzender voor opslagwachtrijgegevens nodig om wachtrijgegevens te lezen en te schrijven. Als u uzelf deze rol wilt toewijzen, moet u de rol Gebruikerstoegang Beheer istrator of een andere rol met de actie Microsoft.Authorization/roleAssignments/write toegewezen krijgen. U kunt Azure RBAC-rollen toewijzen aan een gebruiker met behulp van Azure Portal, Azure CLI of Azure PowerShell. Meer informatie over de beschikbare bereiken voor roltoewijzingen vindt u op de overzichtspagina van het bereik.

In dit scenario wijst u machtigingen toe aan uw gebruikersaccount, dat is afgestemd op het opslagaccount, om het principe van minimale bevoegdheden te volgen. Deze procedure biedt gebruikers alleen de minimale machtigingen die nodig zijn en maakt veiligere productieomgevingen.

In het volgende voorbeeld wordt de rol Inzender voor opslagwachtrijgegevens toegewezen aan uw gebruikersaccount, dat zowel lees- als schrijftoegang biedt tot wachtrijgegevens in uw opslagaccount.

Belangrijk

In de meeste gevallen duurt het een of twee minuten voordat de roltoewijzing is doorgegeven in Azure, maar in zeldzame gevallen kan het maximaal acht minuten duren. Als u verificatiefouten ontvangt wanneer u de code voor het eerst uitvoert, wacht u even en probeert u het opnieuw.

  1. Zoek uw opslagaccount in Azure Portal met behulp van de hoofdzoekbalk of linkernavigatiebalk.

  2. Selecteer op de overzichtspagina van het opslagaccount toegangsbeheer (IAM) in het menu aan de linkerkant.

  3. Selecteer op de pagina Toegangsbeheer (IAM) het tabblad Roltoewijzingen .

  4. Selecteer + Toevoegen in het bovenste menu en voeg vervolgens roltoewijzing toe in de resulterende vervolgkeuzelijst.

A screenshot showing how to assign a role.

  1. Gebruik het zoekvak om de resultaten te filteren op de gewenste rol. In dit voorbeeld zoekt u inzender voor opslagwachtrijgegevens en selecteert u het overeenkomende resultaat en kiest u vervolgens Volgende.

  2. Selecteer onder Toegang toewijzen de optie Gebruiker, groep of service-principal en kies vervolgens + Leden selecteren.

  3. Zoek in het dialoogvenster naar uw Microsoft Entra-gebruikersnaam (meestal uw user@domain e-mailadres) en kies Vervolgens onderaan het dialoogvenster Selecteren .

  4. Selecteer Beoordelen + toewijzen om naar de laatste pagina te gaan en vervolgens opnieuw beoordelen en toewijzen om het proces te voltooien.

Objectmodel

Azure Queue Storage is een service om grote aantallen berichten op te slaan. Een wachtrijbericht kan maximaal 64 KB groot zijn. Een wachtrij kan miljoenen berichten bevatten, tot aan de totale capaciteitslimiet van een opslagaccount. Wachtrijen worden vaak gebruikt om een voorraad werk te maken dat asynchroon moet worden verwerkt. Queue Storage biedt drie typen resources:

  • Opslagaccount: Alle toegang tot Azure Storage wordt uitgevoerd via een opslagaccount. Zie overzicht van opslagaccounts voor meer informatie over opslagaccounts
  • Wachtrij: Een wachtrij bevat een set berichten. Alle berichten moeten zich in een wachtrij bevinden. De naam van een wachtrij mag alleen kleine letters bevatten. Zie Naming Queues and Metadata (Wachtrijen en metagegevens een naam geven) voor informatie over de naamgeving van wachtrijen.
  • Bericht: Een bericht in een willekeurige indeling, van maximaal 64 KB. Een bericht kan maximaal 7 dagen in de wachtrij blijven. Voor versie 29-07-2017 of hoger mag de maximale time-to-live elk positief getal zijn. Of -1 om aan te geven dat het bericht niet verloopt. Als deze parameter wordt weggelaten, is de standaard time-to-live zeven dagen.

Het volgende diagram geeft de relatie tussen deze resources weer.

Diagram of Queue storage architecture

Gebruik de volgende Java-klassen om te communiceren met deze resources:

  • QueueClientBuilder: De QueueClientBuilder klasse configureert en instantieert een QueueClient object.
  • QueueServiceClient: Hiermee QueueServiceClient kunt u alle wachtrijen in uw opslagaccount beheren.
  • QueueClient: Met de QueueClient klasse kunt u een afzonderlijke wachtrij en de bijbehorende berichten beheren en bewerken.
  • QueueMessageItem: De QueueMessageItem klasse vertegenwoordigt de afzonderlijke objecten die worden geretourneerd bij het aanroepen ReceiveMessages van een wachtrij.

Codevoorbeelden

Deze voorbeeldcodefragmenten laten zien hoe u de volgende acties kunt uitvoeren met de Azure Queue Storage-clientbibliotheek voor Java:

Toegang autoriseren en een clientobject maken

Zorg ervoor dat u bent geverifieerd met hetzelfde Microsoft Entra-account waaraan u de rol hebt toegewezen. U kunt zich verifiëren via Azure CLI, Visual Studio Code of Azure PowerShell.

Meld u aan bij Azure via de Azure CLI met behulp van de volgende opdracht:

az login

Nadat u bent geverifieerd, kunt u een QueueClient object maken en autoriseren met behulp van DefaultAzureCredential toegang tot wachtrijgegevens in het opslagaccount. DefaultAzureCredential detecteert en gebruikt automatisch het account waarmee u zich in de vorige stap hebt aangemeld.

Als u het gebruik DefaultAzureCredentialwilt autoriseren, moet u ervoor zorgen dat u de azure-identity-afhankelijkheid hebt toegevoegd, pom.xmlzoals beschreven in De pakketten installeren. Zorg er ook voor dat u een importrichtlijn toevoegt voor com.azure.identity in het App.java-bestand :

import com.azure.identity.*;

Bepaal een naam voor de wachtrij en maak een exemplaar van de QueueClient klasse met behulp van DefaultAzureCredential autorisatie. We gebruiken dit clientobject om de wachtrijresource in het opslagaccount te maken en ermee te communiceren.

Belangrijk

Wachtrijnamen mogen alleen kleine letters, cijfers en afbreekstreepjes bevatten en moeten beginnen met een letter of cijfer. Elk afbreekstreepje moet worden voorafgegaan en gevolgd door een cijfer of letter. De naam moet bovendien tussen 3 en 63 tekens lang zijn. Zie Naamgeving van wachtrijen en metagegevens voor meer informatie over de naamgeving van wachtrijen.

Voeg deze code toe aan de main methode en zorg ervoor dat u de <storage-account-name> tijdelijke aanduidingswaarde vervangt:

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

Notitie

Berichten die met de QueueClient klasse worden verzonden, moeten een indeling hebben die kan worden opgenomen in een XML-aanvraag met UTF-8-codering. U kunt desgewenst de optie QueueMessageEncoding instellen om niet-compatibele berichten te BASE64 verwerken.

Een wachtrij maken

Roep met behulp van het QueueClient object de create methode aan om de wachtrij in uw opslagaccount te maken.

Voeg deze code toe aan het einde van de main-methode:

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

// Create the queue
queueClient.create();

Berichten aan een wachtrij toevoegen

Met het volgende codefragment worden berichten aan de wachtrij toegevoegd door de methode sendMessage aan te roepen. Ook wordt een SendMessageResult opgeslagen die met een sendMessage-aanroep wordt geretourneerd. De resultaat wordt gebruikt om het bericht later in het programma bij te werken.

Voeg deze code toe aan het einde van de main-methode:

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

Berichten in een wachtrij bekijken

Bekijk de berichten in de wachtrij door de methode peekMessages aan te roepen. Met deze methode worden één of meer berichten vooraan in de wachtrij opgehaald, maar wordt de zichtbaarheid van het bericht niet gewijzigd.

Voeg deze code toe aan het einde van de main-methode:

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

Een bericht in een wachtrij bijwerken

Werk de inhoud van een bericht bij door de methode updateMessage aan te roepen. Deze methode kan de time-out voor zichtbaarheid en de inhoud van een bericht wijzigen. De inhoud van het bericht moet een UTF-8-gecodeerde tekenreeks zijn die maximaal 64 KB groot is. Gebruik de SendMessageResult die eerder werd opgeslagen in de code om het bericht-ID en de POP-ontvangstbevestiging samen met de nieuwe inhoud voor het bericht door te geven. De bericht-ID en de POP-ontvangstbevestiging identificeren het bericht dat bijgewerkt moet worden.

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

Lengte van de wachtrij ophalen

U kunt een schatting ophalen van het aantal berichten in de wachtrij.

De getProperties methode retourneert verschillende waarden, waaronder het aantal berichten dat zich momenteel in een wachtrij bevindt. Het aantal is alleen bij benadering omdat berichten na uw aanvraag kunnen worden toegevoegd of verwijderd. De getApproximateMessageCount methode retourneert de laatste waarde die is opgehaald door de aanroep naar, zonder Queue Storage aan te getPropertiesroepen.

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

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

Berichten uit een wachtrij ontvangen en verwijderen

Download eerder toegevoegde berichten door de methode receiveMessages aan te roepen. De voorbeeldcode verwijdert ook berichten uit de wachtrij nadat ze zijn ontvangen en verwerkt. In dit geval betekent ‘verwerken’ gewoon dat het bericht wordt weergegeven in de console.

De app pauzeert voor gebruikersinvoer door System.console().readLine(); aan te roepen voordat deze de berichten ontvangt en verwijdert. Verifieer in uw Azure-portal dat de resources correct zijn gemaakt, voordat ze worden verwijderd. Berichten die niet expliciet worden verwijderd, worden uiteindelijk weer zichtbaar in de wachtrij voor een andere kans om ze te verwerken.

Voeg deze code toe aan het einde van de main-methode:

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

Wanneer u de receiveMessages methode aanroept, kunt u desgewenst een waarde opgeven voor maxMessages, wat het aantal berichten is dat uit de wachtrij moet worden opgehaald. De standaardwaarde is 1 bericht en het maximum is 32 berichten. U kunt ook een waarde opgeven waarvoor visibilityTimeoutde berichten voor de time-outperiode worden verborgen voor andere bewerkingen. De standaardwaarde is 30 seconden.

Een wachtrij verwijderen

Met de volgende code worden de resources opgeschoond die met de app zijn gemaakt, door de wachtrij te verwijderen met de methode Delete.

Voeg deze code toe aan het einde van de main-methode:

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

De code uitvoeren

Met deze app worden drie berichten gemaakt en aan een Azure-wachtrij toegevoegd. De code toont de berichten in de wachtrij, haalt ze op en verwijdert ze, en verwijdert uiteindelijk de wachtrij.

Navigeer in uw consolevenster naar de toepassingsmap, bouw de toepassing en voer deze uit.

mvn compile

Bouw vervolgens het pakket.

mvn package

Voer de volgende opdracht mvn uit om de app uit te voeren.

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

De uitvoer van de app lijkt op die in het volgende voorbeeld:

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

Wanneer de app pauzeert voordat deze berichten ontvangt, controleert u uw opslagaccount in de Azure-portal. Verifieer dat de berichten in de wachtrij staan.

Druk op de Enter toets om de berichten te ontvangen en te verwijderen. Wanneer u hierom wordt gevraagd, drukt u nogmaals op de Enter toets om de wachtrij te verwijderen en de demo te voltooien.

Volgende stappen

In deze quickstart hebt u geleerd hoe u een wachtrij maakt en berichten eraan toevoegt met behulp van Java-code. Vervolgens leerde u hoe u berichten kunt bekijken, ophalen en verwijderen. Tot slot leerde u hoe u een berichtenwachtrij verwijdert.

Voor zelfstudies, voorbeelden, quickstarts en andere documentatie gaat u naar:

Azure voor Java-cloudontwikkelaars