Snabbstart: Azure Queue Storage-klientbibliotek för Java

  • Artikel

Kom igång med Azure Queue Storage-klientbiblioteket för Java. Azure Queue Storage är en tjänst för lagring av ett stort antal meddelanden för senare hämtning och bearbetning. Följ de här stegen för att installera paketet och prova exempelkod för grundläggande uppgifter.

API-referensdokumentation | Källkod | för bibliotekPaket (Maven) | Prover

Använd Azure Queue Storage-klientbiblioteket för Java för att:

  • Skapa en kö
  • Lägga till meddelanden i en kö
  • Titta på meddelanden i en kö
  • Uppdatera ett meddelande i en kö
  • Hämta kölängden
  • Ta emot meddelanden från en kö
  • Ta bort meddelanden från en kö
  • Ta bort en kö

Förutsättningar

Inrätta

Det här avsnittet vägleder dig genom att förbereda ett projekt för att arbeta med Azure Queue Storage-klientbiblioteket för Java.

Skapa projektet

Skapa ett Java-program med namnet queues-quickstart.

  1. I ett konsolfönster (till exempel cmd, PowerShell eller Bash) använder du Maven för att skapa en ny konsolapp med namnköer-snabbstarten. Skriv följande mvn kommando för att skapa en "Hello, world!" 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. Utdata från att generera projektet bör se ut ungefär så här:

    [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. Växla till den nyligen skapade katalogen queues-quickstart .

    cd queues-quickstart

Installera paketen

pom.xml Öppna filen i textredigeraren.

Lägg till azure-sdk-bom för att ta ett beroende av den senaste versionen av biblioteket. I följande kodfragment ersätter du {bom_version_to_target} platshållaren med versionsnumret. Om du använder azure-sdk-bom behöver du inte ange versionen av varje enskilt beroende. Mer information om bommen finns i 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>

Lägg sedan till följande beroendeelement i gruppen med beroenden. Azure-identitetsberoendet behövs för lösenordslösa anslutningar till Azure-tjänster .

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

Konfigurera appramverket

Från projektkatalogen:

  1. Gå till katalogen /src/main/java/com/queues/quickstart
  2. Öppna Filen App.java i redigeringsprogrammet
  3. Ta bort -instruktionen System.out.println("Hello, world");
  4. Lägga till import direktiv

Här är koden:

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

Autentisera till Azure

Programbegäranden till de flesta Azure-tjänster måste auktoriseras. Att använda klassen DefaultAzureCredential som tillhandahålls av Azure Identity-klientbiblioteket är den rekommenderade metoden för att implementera lösenordslösa anslutningar till Azure-tjänster i koden.

Du kan också auktorisera begäranden till Azure-tjänster med hjälp av lösenord, anslutningssträngar eller andra autentiseringsuppgifter direkt. Den här metoden bör dock användas med försiktighet. Utvecklare måste vara noggranna med att aldrig exponera dessa hemligheter på en osäker plats. Alla som får åtkomst till lösenordet eller den hemliga nyckeln kan autentisera sig. DefaultAzureCredential ger bättre hanterings- och säkerhetsfördelar jämfört med kontonyckeln för att tillåta lösenordslös autentisering. Båda alternativen visas i följande exempel.

DefaultAzureCredential är en klass som tillhandahålls av Azure Identity-klientbiblioteket för Java. Mer information om DefaultAzureCredentialfinns i Översikt över DefaultAzureCredential. DefaultAzureCredential stöder flera autentiseringsmetoder och avgör vilken metod som ska användas vid körning. Med den här metoden kan din app använda olika autentiseringsmetoder i olika miljöer (lokalt jämfört med produktion) utan att implementera miljöspecifik kod.

Din app kan till exempel autentisera med dina Inloggningsuppgifter för Azure CLI när du utvecklar lokalt och sedan använda en hanterad identitet när den har distribuerats till Azure. Inga kodändringar krävs för den här övergången.

När du utvecklar lokalt kontrollerar du att det användarkonto som har åtkomst till ködata har rätt behörigheter. Du behöver Storage Queue Data-deltagare för att läsa och skriva ködata. Om du vill tilldela dig själv den här rollen måste du tilldelas rollen Administratör för användaråtkomst eller en annan roll som innehåller åtgärden Microsoft.Authorization/roleAssignments/write . Du kan tilldela Azure RBAC-roller till en användare med hjälp av Azure Portal, Azure CLI eller Azure PowerShell. Du kan läsa mer om tillgängliga omfång för rolltilldelningar på översiktssidan för omfång .

I det här scenariot tilldelar du behörigheter till ditt användarkonto, begränsat till lagringskontot, för att följa principen om lägsta behörighet. Den här metoden ger användarna bara de minsta behörigheter som krävs och skapar säkrare produktionsmiljöer.

I följande exempel tilldelas rollen Lagringsködatadeltagare till ditt användarkonto, vilket ger både läs- och skrivåtkomst till ködata i ditt lagringskonto.

Viktigt

I de flesta fall tar det en minut eller två innan rolltilldelningen sprids i Azure, men i sällsynta fall kan det ta upp till åtta minuter. Om du får autentiseringsfel när du först kör koden väntar du en stund och försöker igen.

  1. Leta upp ditt lagringskonto i Azure Portal med hjälp av huvudsökfältet eller det vänstra navigeringsfältet.

  2. På översiktssidan för lagringskontot väljer du Åtkomstkontroll (IAM) på den vänstra menyn.

  3. På sidan Åtkomstkontroll (IAM) väljer du fliken Rolltilldelningar .

  4. Välj + Lägg till på den översta menyn och sedan Lägg till rolltilldelning från den resulterande listrutan.

En skärmbild som visar hur du tilldelar en roll.

  1. Använd sökrutan för att filtrera resultatet till önskad roll. I det här exemplet söker du efter Storage Queue Data Contributor och väljer matchande resultat och sedan Nästa.

  2. Under Tilldela åtkomst till väljer du Användare, grupp eller tjänstens huvudnamn och sedan + Välj medlemmar.

  3. I dialogrutan söker du efter ditt Azure AD användarnamn (vanligtvis din user@domain e-postadress) och väljer sedan Välj längst ned i dialogrutan.

  4. Välj Granska + tilldela för att gå till den sista sidan och sedan Granska + tilldela igen för att slutföra processen.

Objektmodell

Azure Queue Storage är en tjänst för lagring av ett stort antal meddelanden. Ett kömeddelande kan vara upp till 64 kB stort. En kö kan innehålla miljontals meddelanden, upp till den totala kapacitetsgränsen för ett lagringskonto. Köer används ofta för att skapa en kvarvarande arbetslogg för att bearbeta asynkront. Queue Storage erbjuder tre typer av resurser:

  • Lagringskonto: All åtkomst till Azure Storage sker via ett lagringskonto. Mer information om lagringskonton finns i Översikt över lagringskonto
  • Kö: En kö innehåller en uppsättning meddelanden. Alla meddelanden måste vara i en kö. Observera att könamnet måste vara helt i gemener. Mer information om namngivning av köer finns i namngivning av köer och metadata.
  • Meddelande: Ett meddelande, i alla format, på upp till 64 kB. Ett meddelande kan finnas kvar i kön i högst 7 dagar. För version 2017-07-29 eller senare kan den maximala time-to-live vara ett positivt tal, eller -1 som anger att meddelandet inte upphör att gälla. Om den här parametern utelämnas är standardtiden att leva sju dagar.

Följande diagram visar relationen mellan de här resurserna.

Diagram över arkitektur för kölagring

Använd följande Java-klasser för att interagera med dessa resurser:

  • QueueClientBuilder: Klassen QueueClientBuilder konfigurerar och instansierar ett QueueClient objekt.
  • QueueServiceClientQueueServiceClient: Gör att du kan hantera alla köer i ditt lagringskonto.
  • QueueClient: Med QueueClient klassen kan du hantera och ändra en enskild kö och dess meddelanden.
  • QueueMessageItem: Klassen QueueMessageItem representerar de enskilda objekt som returneras när de anropas ReceiveMessages i en kö.

Kodexempel

Dessa exempelkodfragment visar hur du utför följande åtgärder med Azure Queue Storage-klientbiblioteket för Java:

Auktorisera åtkomst och skapa ett klientobjekt

Kontrollera att du är autentiserad med samma Azure AD konto som du tilldelade rollen till. Du kan autentisera via Azure CLI, Visual Studio Code eller Azure PowerShell.

Logga in på Azure via Azure CLI med följande kommando:

az login

När du har autentiserats kan du skapa och auktorisera ett QueueClient objekt med hjälp av DefaultAzureCredential för att komma åt ködata i lagringskontot. DefaultAzureCredential identifierar och använder automatiskt det konto som du loggade in med i föregående steg.

Om du vill auktorisera med hjälp av DefaultAzureCredentialkontrollerar du att du har lagt till azure-identity-beroendet i pom.xml, enligt beskrivningen i Installera paketen. Se också till att lägga till ett importdirektiv för com.azure.identity i App.java-filen :

import com.azure.identity.*;

Bestäm ett namn för kön och skapa en instans av QueueClient klassen med auktorisering DefaultAzureCredential . Vi använder det här klientobjektet för att skapa och interagera med köresursen i lagringskontot.

Viktigt

Könamn får bara innehålla gemener, siffror och bindestreck och måste börja med en bokstav eller ett tal. Varje bindestreck måste föregås och följas av ett tecken som inte är ett bindestreck. Namnet måste också vara mellan 3 och 63 tecken långt. Mer information om namngivning av köer finns i Namngivning av köer och metadata.

Lägg till den main här koden i metoden och ersätt <storage-account-name> platshållarvärdet:

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

Anteckning

Meddelanden som skickas med QueueClient klassen måste vara i ett format som kan ingå i en XML-begäran med UTF-8-kodning. Du kan också ange alternativet QueueMessageEncoding till för att BASE64 hantera icke-kompatibla meddelanden.

Skapa en kö

Med hjälp av QueueClient objektet anropar create du metoden för att skapa kön i ditt lagringskonto.

Lägg till den här koden i slutet av main metoden:

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

// Create the queue
queueClient.create();

Lägga till meddelanden i en kö

Följande kodfragment lägger till meddelanden i kön genom att anropa sendMessage metoden . Det sparar också ett SendMessageResult som returneras från ett sendMessage anrop. Resultatet används för att uppdatera meddelandet senare i programmet.

Lägg till den här koden i slutet av main metoden:

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

Granska meddelanden i en kö

Granska meddelandena i kön genom att anropa peekMessages metoden . Den här metoden hämtar ett eller flera meddelanden längst fram i kön, men ändrar inte meddelandets synlighet.

Lägg till den här koden i slutet av main metoden:

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

Uppdatera ett meddelande i en kö

Uppdatera innehållet i ett meddelande genom att anropa updateMessage metoden . Den här metoden kan ändra ett meddelandes synlighetstimeout och innehåll. Meddelandeinnehållet måste vara en UTF-8-kodad sträng som är upp till 64 kB stort. Tillsammans med nytt innehåll för meddelandet skickar du meddelande-ID:t och popkvittot med hjälp SendMessageResult av som sparades tidigare i koden. Meddelande-ID:t och popkvittot identifierar vilket meddelande som ska uppdateras.

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

Hämta kölängden

Du kan hämta en uppskattning av antalet meddelanden i en kö.

Metoden getProperties returnerar flera värden, inklusive antalet meddelanden som för närvarande finns i en kö. Antalet är bara ungefärligt eftersom meddelanden kan läggas till eller tas bort efter din begäran. Metoden getApproximateMessageCount returnerar det sista värdet som hämtades av anropet till , utan att getPropertiesanropa Queue Storage.

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

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

Ta emot och ta bort meddelanden från en kö

Ladda ned tidigare tillagda meddelanden genom att receiveMessages anropa metoden . Exempelkoden tar också bort meddelanden från kön när de har tagits emot och bearbetats. I det här fallet visar bearbetningen bara meddelandet på konsolen.

Appen pausar för användarindata genom att anropa System.console().readLine(); innan den tar emot och tar bort meddelandena. Kontrollera i Azure Portal att resurserna har skapats korrekt innan de tas bort. Meddelanden som inte uttryckligen tas bort blir så småningom synliga i kön igen för en ny chans att bearbeta dem.

Lägg till den här koden i slutet av main metoden:

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

När du anropar receiveMessages metoden kan du ange ett värde för maxMessages, vilket är antalet meddelanden som ska hämtas från kön. Standardvärdet är 1 meddelande och maxvärdet är 32 meddelanden. Du kan också ange ett värde för visibilityTimeout, som döljer meddelanden från andra åtgärder under tidsgränsperioden. Standardvärdet är 30 sekunder.

Ta bort en kö

Följande kod rensar de resurser som appen skapade genom att ta bort kön med hjälp av Delete metoden .

Lägg till den här koden i slutet av main metoden:

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

Kör koden

Den här appen skapar och lägger till tre meddelanden i en Azure-kö. Koden visar meddelandena i kön och hämtar och tar bort dem innan kön slutligen tas bort.

I konsolfönstret navigerar du till programkatalogen och skapar och kör sedan programmet.

mvn compile

Skapa sedan paketet.

mvn package

Kör appen med följande mvn kommando.

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

Utdata från appen liknar följande exempel:

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

När appen pausar innan du tar emot meddelanden kontrollerar du lagringskontot i Azure Portal. Kontrollera att meddelandena finns i kön.

Tryck på tangenten Enter för att ta emot och ta bort meddelandena. När du uppmanas att göra det trycker du på tangenten Enter igen för att ta bort kön och slutföra demonstrationen.

Nästa steg

I den här snabbstarten har du lärt dig hur du skapar en kö och lägger till meddelanden i den med hjälp av Java-kod. Sedan lärde du dig att granska, hämta och ta bort meddelanden. Slutligen lärde du dig att ta bort en meddelandekö.

Självstudier, exempel, snabbstarter och annan dokumentation finns i:

Azure för Java-molnutvecklare