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

  • Cikk

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ódcsomagja | (Maven)Minták | |

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

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

Előfeltételek

Beállí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.

Az azure-sdk-bom hozzáadása a kódtár legújabb verziójától való függőséghez. 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. Az App.java fájl megnyitása a szerkesztőben
  3. Az System.out.println("Hello, world"); utasítás törlése
  4. Irányelvek hozzáadása import

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 áttűnéshez 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. A szerepkör hozzárendeléséhez hozzá kell rendelnie a Felhasználói hozzáférés Rendszergazda istrator szerepkört, vagy egy másik szerepkört, 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.

A screenshot showing how to assign a role.

  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 szolgáltatás nagy számú üzenet tárolására szolgál. 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.

Diagram of Queue storage architecture

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.

Kódpéldák

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 létrehozhat és engedélyezheti az objektumokat QueueClientDefaultAzureCredential 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 használat DefaultAzureCredentialengedélyezéséhez győződjön meg arról, hogy hozzáadta az azure-identity függőséget pom.xmla csomagok telepítésében leírtak szerint. Emellett mindenképpen adjon hozzá egy importálási direktívát com.azure.identity az App.java fájlhoz:

import com.azure.identity.*;

Döntse el az üzenetsor nevét, és hozza létre az QueueClient osztály egy példányát engedélyezés DefaultAzureCredential céljából. Ezt az ügyfélobjektumot használjuk a tárfiók üzenetsor-erőforrásának létrehozásához és használatához.

Fontos

Az üzenetsornevek csak kisbetűket, számokat és kötőjeleket tartalmazhatnak, és betűvel vagy számmal kell kezdődniük. A kötőjelek előtt és után csak nem kötőjel karakter állhat. 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.

Üzenetsor létrehozása

QueueClient Az objektum használatával hívja meg a metódust, create hogy létrehozza az üzenetsort a tárfiókban.

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 sendMessage visszaadott fájlt is mentSendMessageResult. 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

A metódus meghívásával peekMessages pillanthat meg az üzenetsor üzeneteibe. 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 üzenet azonosítóját és a pop nyugtát a SendMessageResult kódban korábban mentett adatok használatával. Az üzenetazonosító és a pop-nyugta 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));

Az üzenetsor hosszának lekérése

Megbecsülheti egy üzenetsorban található üzenetek számát.

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.

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