Rövid útmutató: Azure Queue Storage-ügyfélkódtár Java-hoz

Ismerkedés a Java Azure Queue Storage ügyfélkódtárával. Az Azure Queue Storage szolgáltatás nagy mennyiségű üzenet tárolására szolgál későbbi lekéréshez és feldolgozáshoz. Az alábbi lépések végrehajtásával telepítheti a csomagot, és kipróbálhatja az alapműveletek példakódját.

API-referenciadokumentáció | Kódtár forráskódja | Csomag (Maven) | Minták

Az Azure Queue Storage Java-ügyfélkódtárával a következő célokra használhatja:

  • Sor létrehozása
  • Üzenetek hozzáadása üzenetsorhoz
  • Üzenetsor üzeneteibe való betekintés
  • Üzenet frissítése üzenetsorban
  • A sor hosszának lekérése
  • Üzenetek fogadása üzenetsorból
  • Üzenetek törlése üzenetsorból
  • Sor törlése

Előfeltételek

Előkészítés

Ez a szakasz végigvezeti egy projekt előkészítésén a Java Azure Queue Storage ügyfélkódtárával való együttműködésre.

A projekt létrehozása

Hozzon létre egy queues-quickstart nevű Java-alkalmazást.

  1. Egy konzolablakban (például cmd, PowerShell vagy Bash) a Maven használatával hozzon létre egy új konzolalkalmazást a queues-quickstart névvel. Írja be a következő mvn parancsot a "Hello, world!" létrehozásához 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. A projekt generálásának kimenetének a következőhöz hasonlóan kell kinéznie:

    [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áltson az újonnan létrehozott queues-quickstart könyvtárra .

    cd queues-quickstart

A csomagok telepítése

Nyissa meg a pom.xml fájlt a szövegszerkesztőben.

Add hozzá az azure-sdk-bom-ot a könyvtár legújabb verziójának függőségéhez. Az alábbi kódrészletben cserélje le a {bom_version_to_target} helyőrzőt a verziószámra. Az Azure-sdk-bom használatával nem kell megadnia az egyes függőségek verzióját. A BOM-ról további információt az Azure SDK BOM README-ben talál.

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

Ezután adja hozzá a következő függőségi elemeket a függőségek csoportjához. Az Azure-szolgáltatásokhoz való jelszó nélküli kapcsolatokhoz azure-identitásfüggőség szükséges.

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

Az alkalmazás-keretrendszer beállítása

A projektkönyvtárból:

  1. Lépjen a /src/main/java/com/queues/quickstart könyvtárra
  2. Nyissa meg a App.java fájlt a szerkesztőben
  3. Az System.out.println("Hello, world"); utasítás törlése
  4. Adj hozzá import irányelveket

A kód a következő:

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

Hitelesítés az Azure-ban

A legtöbb Azure-szolgáltatáshoz irányuló alkalmazáskéréseket engedélyezni kell. DefaultAzureCredential Az Azure Identity-ügyfélkódtár által biztosított osztály használata ajánlott módszer az Azure-szolgáltatásokhoz való jelszó nélküli kapcsolatok implementálásához a kódban.

Az Azure-szolgáltatásokra irányuló kéréseket közvetlenül jelszóval, kapcsolati sztring vagy más hitelesítő adatokkal is engedélyezheti. Ezt a megközelítést azonban körültekintően kell alkalmazni. A fejlesztőknek szorgalmasnak kell lenniük ahhoz, hogy ezeket a titkos kulcsokat soha ne fedje fel nem biztonságos helyen. Bárki, aki hozzáfér a jelszóhoz vagy titkos kulcshoz, hitelesítheti magát. DefaultAzureCredential továbbfejlesztett felügyeleti és biztonsági előnyöket kínál a fiókkulcson keresztül a jelszó nélküli hitelesítés engedélyezéséhez. Az alábbi példában mindkét lehetőség látható.

DefaultAzureCredential A Java-hoz készült Azure Identity-ügyfélkódtár által biztosított osztály. További információkért DefaultAzureCredentialtekintse meg a DefaultAzureCredential áttekintését. DefaultAzureCredential több hitelesítési módszert támogat, és meghatározza, hogy melyik metódust kell használni futásidőben. Ez a megközelítés lehetővé teszi, hogy az alkalmazás különböző hitelesítési módszereket használjon különböző környezetekben (helyi és éles környezetben) környezetspecifikus kód implementálása nélkül.

Az alkalmazás például hitelesítheti az Azure CLI bejelentkezési hitelesítő adataival a helyi fejlesztés során, majd használhat felügyelt identitást az Azure-ban való üzembe helyezés után. Ehhez az átálláshoz nincs szükség kódmódosításra.

Helyi fejlesztéskor győződjön meg arról, hogy az üzenetsor-adatokat elérő felhasználói fiók rendelkezik a megfelelő engedélyekkel. A várólista adatainak olvasásához és írásához tárolósoradat-közreműködőre lesz szükség. Önmagának e szerepkör hozzárendeléséhez rendelkeznie kell a Felhasználói hozzáférés rendszergazda szerepkörrel, vagy egy másik szerepkörrel, amely tartalmazza a Microsoft.Authorization/roleAssignments/write műveletet. Azure RBAC-szerepköröket rendelhet egy felhasználóhoz az Azure Portal, az Azure CLI vagy az Azure PowerShell használatával. A szerepkör-hozzárendelések elérhető hatóköreiről a hatókör áttekintési oldalán tudhat meg többet.

Ebben a forgatókönyvben engedélyeket rendel hozzá a felhasználói fiókjához, amely a tárfiókra terjed ki, hogy kövesse a minimális jogosultság elvét. Ez a gyakorlat csak a minimálisan szükséges engedélyeket biztosítja a felhasználóknak, és biztonságosabb éles környezeteket hoz létre.

Az alábbi példa a Storage Queue Data Contributor szerepkört rendeli hozzá a felhasználói fiókjához, amely olvasási és írási hozzáférést biztosít a tárfiók üzenetsoradataihoz.

Fontos

A szerepkör-hozzárendelés propagálása a legtöbb esetben egy-két percet vesz igénybe az Azure-ban, de ritkán akár nyolc percet is igénybe vehet. Ha hitelesítési hibákat kap a kód első futtatásakor, várjon néhány percet, és próbálkozzon újra.

  1. Az Azure Portalon keresse meg a tárfiókot a fő keresősávon vagy a bal oldali navigációs sávon.

  2. A tárfiók áttekintési lapján válassza a Hozzáférés-vezérlés (IAM) lehetőséget a bal oldali menüben.

  3. A Hozzáférés-vezérlés (IAM) lapon válassza a Szerepkör-hozzárendelések lapot.

  4. Válassza a +Hozzáadás lehetőséget a felső menüből, majd a szerepkör-hozzárendelés hozzáadása lehetőséget az eredményül kapott legördülő menüből.

Képernyőkép egy szerepkör hozzárendeléséről.

  1. A keresőmezővel szűrheti az eredményeket a kívánt szerepkörre. Ebben a példában keresse meg a Tárolási várólista adatszolgáltatóját, és válassza ki a megfelelő eredményt, majd válassza a Tovább gombot.

  2. A Hozzáférés hozzárendelése területen válassza a Felhasználó, csoport vagy szolgáltatásnév lehetőséget, majd válassza a + Tagok kijelölése lehetőséget.

  3. A párbeszédpanelen keresse meg a Microsoft Entra-felhasználónevet (általában a user@domain e-mail-címét), majd válassza a Párbeszédpanel alján található Kiválasztás lehetőséget.

  4. Válassza a Véleményezés + hozzárendelés lehetőséget a végső lapra való ugráshoz, majd a folyamat befejezéséhez a Véleményezés + hozzárendelés lehetőséget.

Objektummodell

Az Azure Queue Storage nagy mennyiségű üzenet tárolására szolgáló szolgáltatás. Az üzenetsor-üzenetek mérete legfeljebb 64 KB lehet. Az üzenetsorok több millió üzenetet tartalmazhatnak, akár a tárfiók teljes kapacitáskorlátját is. Az üzenetsorokat gyakran használják az aszinkron feldolgozáshoz használt teendőlista létrehozásához. A Queue Storage három típusú erőforrást kínál:

  • Tárfiók: Az Azure Storage-hoz való minden hozzáférés egy tárfiókon keresztül történik. További információ a tárfiókokról: Tárfiókok áttekintése
  • Üzenetsor: Az üzenetsorok üzenetek készleteit tartalmazzák. Az összes üzenetnek üzenetsorban kell lennie. Vegye figyelembe, hogy az üzenetsor neve csak kisbetűket tartalmazhat. Az üzenetsorok elnevezésével kapcsolatos információkat lásd: Naming Queues and Metadata (Üzenetsorok és metaadatok elnevezése).
  • Üzenet: Egy legfeljebb 64 KB méretű, tetszőleges méretű üzenet. Egy üzenet legfeljebb 7 napig maradhat az üzenetsorban. A 2017-07-29-es vagy újabb verzió esetén a maximális élettartam bármilyen pozitív szám lehet, vagy -1, amely azt jelzi, hogy az üzenet nem jár le. Ha ez a paraméter nincs megadva, az alapértelmezett élettartam hét nap.

Az alábbi ábra az ezen erőforrások közötti kapcsolatot mutatja be.

A Queue Storage architektúrájának diagramja

Az alábbi Java-osztályok használatával kezelheti ezeket az erőforrásokat:

  • QueueClientBuilder: Az QueueClientBuilder osztály konfigurál és példányosít egy QueueClient objektumot.
  • QueueServiceClient: Ez QueueServiceClient lehetővé teszi a tárfiók összes üzenetsorának kezelését.
  • QueueClient: Az QueueClient osztály lehetővé teszi az egyes üzenetsorok és azok üzeneteinek kezelését és kezelését.
  • QueueMessageItem: Az QueueMessageItem osztály az üzenetsor hívása ReceiveMessages során visszaadott egyes objektumokat jelöli.

Példakódok

Ezek a példakódrészletek a következő műveleteket mutatják be a Java Azure Queue Storage ügyfélkódtárával:

Hozzáférés engedélyezése és ügyfélobjektum létrehozása

Győződjön meg arról, hogy ugyanazzal a Microsoft Entra-fiókkal van hitelesítve, amelyhez a szerepkört hozzárendelte. Hitelesítést az Azure CLI-vel, a Visual Studio Code-tal vagy az Azure PowerShell-lel végezhet.

Jelentkezzen be az Azure-ba az Azure CLI-vel a következő paranccsal:

az login

A hitelesítés után a QueueClient használatával létrehozhat és engedélyezhet egy DefaultAzureCredential objektumot a tárfiók üzenetsoradatainak eléréséhez. DefaultAzureCredential automatikusan felderíti és használja az előző lépésben bejelentkezett fiókot.

A DefaultAzureCredential használatának engedélyezéséhez győződjön meg arról, hogy hozzáadta az azure-identity függőséget pom.xml, ahogy a csomagok telepítése részben le van írva. Emellett mindenképpen adjon hozzá egy importálási com.azure.identity irányelvet a App.java fájlhoz:

import com.azure.identity.*;

Döntsön a sor nevéről, és hozza létre az QueueClient osztály egy példányát, DefaultAzureCredential használatával az engedélyezéshez. Az ügyfélobjektumot arra használjuk, hogy létrehozzuk és kezeljük a tárfiókban található sor erőforrást.

Fontos

Az üzenetsornevek csak kisbetűket, számokat és kötőjeleket tartalmazhatnak, és betűvel vagy számmal kell kezdődniük. Minden kötőjelet meg kell előznie és követnie egy nem kötőjel karakternek. A névnek 3 és 63 karakter közötti hosszúságúnak kell lennie. Az üzenetsorok elnevezésével kapcsolatos további információkért lásd az elnevezési üzenetsorokat és a metaadatokat.

Adja hozzá ezt a kódot a main metódushoz, és cserélje le a <storage-account-name> helyőrző értékét:

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

Megjegyzés:

Az osztály használatával QueueClient küldött üzeneteknek olyan formátumban kell lenniük, amely szerepelhet egy UTF-8 kódolású XML-kérelemben. Igény szerint beállíthatja a QueueMessageEncoding beállítást BASE64 a nem megfelelő üzenetek kezelésére.

Sor létrehozása

Az QueueClient objektumot használva hívja meg a create metódust, hogy létrehozza az üzenetsort a tárfiókjában.

Adja hozzá ezt a kódot a metódus végéhez main :

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

// Create the queue
queueClient.create();

Üzenetek hozzáadása üzenetsorhoz

Az alábbi kódrészlet a metódus meghívásával üzeneteket ad hozzá az sendMessage üzenetsorhoz. Emellett egy hívásból SendMessageResult visszaadott fájlt is mentsendMessage. Az eredmény az üzenet frissítésére szolgál a program későbbi részében.

Adja hozzá ezt a kódot a metódus végéhez main :

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

Üzenetsor üzeneteibe való betekintés

Az peekMessages metódus meghívásával betekinthet a várakozó üzenetekbe. Ez a metódus egy vagy több üzenetet kér le az üzenetsor elejéről, de nem módosítja az üzenet láthatóságát.

Adja hozzá ezt a kódot a metódus végéhez main :

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

Üzenet frissítése üzenetsorban

Frissítse az üzenet tartalmát a updateMessage metódus meghívásával. Ez a módszer módosíthatja az üzenetek láthatóságának időtúllépését és tartalmát. Az üzenet tartalmának legfeljebb 64 KB méretű UTF-8 kódolt sztringnek kell lennie. Az üzenet új tartalma mellett adja meg az üzenetazonosítót és a vételi nyugtát a korábban a kódban mentett adatok használatával. Az üzenetazonosító és a pop-átvételi igazolás azonosítja a frissíteni kívánt üzenetet.

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

A sor hosszának lekérése

Az üzenetsorokban lévő üzenetek számának becslését is lekérheti.

A getProperties metódus több értéket ad vissza, beleértve az üzenetsorban lévő üzenetek számát is. A szám csak hozzávetőleges, mert az üzenetek a kérés után hozzáadhatók vagy eltávolíthatók. A getApproximateMessageCount metódus a Queue Storage meghívása nélkül adja vissza a hívás getPropertiesáltal lekért utolsó értéket.

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

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

Üzenetek fogadása és törlése üzenetsorból

Töltse le a korábban hozzáadott üzeneteket a metódus meghívásával receiveMessages . A példakód a beérkezett és feldolgozott üzeneteket is törli az üzenetsorból. Ebben az esetben a feldolgozás csak az üzenetet jeleníti meg a konzolon.

Az alkalmazás az üzenetek fogadása és törlése előtt hívással System.console().readLine(); szünetelteti a felhasználói bevitelt. A törlés előtt ellenőrizze az Azure Portalon , hogy az erőforrások megfelelően lettek-e létrehozva. A kifejezetten nem törölt üzenetek végül ismét láthatóvá válnak az üzenetsorban, hogy újra feldolgozzák őket.

Adja hozzá ezt a kódot a metódus végéhez main :

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

A metódus meghívásakor receiveMessages megadhat egy értéket maxMessages, amely az üzenetsorból lekérendő üzenetek száma. Az alapértelmezett érték 1 üzenet, a maximum 32 üzenet. Megadhat egy értéket visibilityTimeoutis, amely elrejti az üzeneteket más műveletekből az időtúllépési időszakra vonatkozóan. Az alapértelmezett érték 30 másodperc.

Sor törlése

Az alábbi kód megtisztítja az alkalmazás által létrehozott erőforrásokat az üzenetsor törlésével a Delete metódus használatával.

Adja hozzá ezt a kódot a metódus végéhez main :

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

A kód futtatása

Ez az alkalmazás három üzenetet hoz létre és ad hozzá egy Azure-üzenetsorhoz. A kód felsorolja az üzenetsorban lévő üzeneteket, majd lekéri és törli őket, mielőtt véglegesen törölené az üzenetsort.

A konzolablakban keresse meg az alkalmazás könyvtárát, majd hozza létre és futtassa az alkalmazást.

mvn compile

Ezután hozza létre a csomagot.

mvn package

Az alkalmazás futtatásához használja az alábbi mvn parancsot.

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

Az alkalmazás kimenete a következő példához hasonló:

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

Amikor az alkalmazás szünetelteti az üzenetek fogadását, ellenőrizze a tárfiókot az Azure Portalon. Ellenőrizze, hogy az üzenetek szerepelnek-e az üzenetsorban.

Nyomja le a billentyűt az Enter üzenetek fogadásához és törléséhez. Amikor a rendszer kéri, nyomja le ismét a billentyűt az Enter üzenetsor törléséhez és a bemutató befejezéséhez.

Következő lépések

Ebben a rövid útmutatóban megtanulta, hogyan hozhat létre üzenetsort, és hogyan adhat hozzá üzeneteket Java-kóddal. Ezután megtanulta betekinteni, lekérni és törölni az üzeneteket. Végül megtanulta, hogyan törölhet egy üzenetsort.

Oktatóanyagok, minták, rövid útmutatók és egyéb dokumentációk:

Azure Java felhőfejlesztőknek

  • Last updated on