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

  • Cikk

Ismerkedés az Azure Queue Storage JavaScripthez készült ü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 | (npm)Minták | |

A JavaScripthez készült Azure Queue Storage ügyfélkódtár használatával:

  • Ü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 az Azure Queue Storage JavaScripthez készült ügyfélkódtárával való együttműködésre.

A projekt létrehozása

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

  1. Egy konzolablakban (például parancsmag, PowerShell vagy Bash) hozzon létre egy új könyvtárat a projekthez:

    mkdir queues-quickstart

  2. Váltás az újonnan létrehozott queues-quickstart könyvtárra:

    cd queues-quickstart

  3. Hozzon létre egy package.json fájlt:

    npm init -y

  4. Nyissa meg a projektet a Visual Studio Code-ban:

    code .

A csomagok telepítése

A projektkönyvtárból telepítse a következő csomagokat a npm install paranccsal.

  1. Telepítse az Azure Queue Storage npm-csomagot:

    npm install @azure/storage-queue

  2. Telepítse az Azure Identity npm-csomagot a jelszó nélküli kapcsolatok támogatásához:

    npm install @azure/identity

  3. Telepítse az ebben a rövid útmutatóban használt egyéb függőségeket:

    npm install uuid dotenv

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

A projektkönyvtárból:

  1. Új szövegfájl megnyitása a kódszerkesztőben

  2. Hívások hozzáadása require az Azure- és Node.js-modulok betöltéséhez

  3. A program struktúrájának létrehozása, beleértve az alapvető kivételkezelést is

    A kód a következő:

    const { QueueClient } = require("@azure/storage-queue");
const { DefaultAzureCredential } = require('@azure/identity');
const { v1: uuidv1 } = require("uuid");

async function main() {
    console.log("Azure Queue Storage client library - JavaScript quickstart sample");

    // Quickstart code goes here
}

main().then(() => console.log("\nDone")).catch((ex) => console.log(ex.message));

  4. Mentse az új fájlt a queues-quickstart könyvtárban.index.js

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 JavaScripthez 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 JavaScript-osztályokkal kezelheti ezeket az erőforrásokat:

  • QueueServiceClient: A QueueServiceClient példányok egy adott tárfiókhoz való kapcsolatot jelölnek az Azure Storage Queue szolgáltatásban. Ez az ügyfél lehetővé teszi a tárfiók összes üzenetsorának kezelését.
  • QueueClient: A QueueClient példányok egyetlen üzenetsort jelölnek egy tárfiókban. Ez az ügyfél lehetővé teszi az egyes üzenetsorok és azok üzeneteinek kezelését és kezelését.

Kódpéldák

Ezek a példakódrészletek a következő műveleteket mutatják be a JavaScripthez készült Azure Queue Storage ügyfélkódtár használatá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 engedélyezéséhez DefaultAzureCredentialgyőződjön meg arról, hogy hozzáadta a @azure/identitáscsomagot, a csomagok telepítése című szakaszban leírtak szerint. Emellett mindenképpen töltse be a @azure/identitás modult az index.js fájlba:

const { DefaultAzureCredential } = require('@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á a következő kódot a main metódushoz, és cserélje le a <storage-account-name> helyőrző értéket:

// Create a unique name for the queue
const queueName = "quickstart" + uuidv1();

// Instantiate a QueueClient which will be used to create and interact with a queue
// TODO: replace <storage-account-name> with the actual name
const queueClient = new QueueClient(`https://<storage-account-name>.queue.core.windows.net/${queueName}`, new DefaultAzureCredential());

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. A korrektúra üzenetbe való belefoglalásához az üzenet tartalmának XML-alapú vagy Base64-kódolásúnak kell lennie.

Az üzenetsorok üzenetei sztringekként vannak tárolva. Ha más adattípust kell elküldenie, akkor az üzenet küldésekor sztringbe kell szerializálnia az adattípust, és deszerializálnia kell a sztringformátumot az üzenet olvasásakor.

A JSON sztringformátummá alakításához és a Node.js-ben való ismételt visszaállításához használja az alábbi segédfüggvényeket:

function jsonToBase64(jsonObj) {
    const jsonString = JSON.stringify(jsonObj)
    return  Buffer.from(jsonString).toString('base64')
}
function encodeBase64ToJson(base64String) {
    const jsonString = Buffer.from(base64String,'base64').toString()
    return JSON.parse(jsonString)
}

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

console.log("\nCreating queue...");
console.log("\t", queueName);

// Create the queue
const createQueueResponse = await queueClient.create();
console.log("Queue created, requestId:", createQueueResponse.requestId);

Üzenetek hozzáadása üzenetsorhoz

Az alábbi kódrészlet a metódus meghívásával üzeneteket ad hozzá az sendMessage üzenetsorhoz. A harmadik sendMessage hívásból visszaadott adatokat is mentiQueueSendMessageResponse. A visszaadott sendMessageResponse üzenet tartalmának frissítésére szolgál a program későbbi részében.

Adja hozzá ezt a kódot a függvény végéhez main :

console.log("\nAdding messages to the queue...");

// Send several messages to the queue
await queueClient.sendMessage("First message");
await queueClient.sendMessage("Second message");
const sendMessageResponse = await queueClient.sendMessage("Third message");

console.log("Messages added, requestId:", sendMessageResponse.requestId);

Ü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. Alapértelmezés szerint peekMessages egyetlen üzenetre kell betekinteni.

Adja hozzá ezt a kódot a függvény végéhez main :

console.log("\nPeek at the messages in the queue...");

// Peek at messages in the queue
const peekedMessages = await queueClient.peekMessages({ numberOfMessages : 5 });

for (i = 0; i < peekedMessages.peekedMessageItems.length; i++) {
    // Display the peeked message
    console.log("\t", peekedMessages.peekedMessageItems[i].messageText);
}

Ü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 új tartalommal együtt adja meg és popReceipt adja meg messageId a kódban korábban mentett választ. A sendMessageResponse tulajdonságok azonosítják a frissíteni kívánt üzenetet.

console.log("\nUpdating the third message in the queue...");

// Update a message using the response saved when calling sendMessage earlier
updateMessageResponse = await queueClient.updateMessage(
    sendMessageResponse.messageId,
    sendMessageResponse.popReceipt,
    "Third message has been updated"
);

console.log("Message updated, requestId:", updateMessageResponse.requestId);

Az üzenetsor hosszának lekérése

A getProperties metódus metaadatokat ad vissza az üzenetsorról, beleértve az üzenetsorban várakozó üzenetek hozzávetőleges számát.

const properties = await queueClient.getProperties();
console.log("Approximate queue length: ", properties.approximateMessagesCount);

Üzenetek fogadása üzenetsorból

Töltse le a korábban hozzáadott üzeneteket a metódus meghívásával receiveMessages . numberOfMessages A mezőben adja meg a híváshoz fogadandó üzenetek maximális számát.

Adja hozzá ezt a kódot a függvény végéhez main :

console.log("\nReceiving messages from the queue...");

// Get messages from the queue
const receivedMessagesResponse = await queueClient.receiveMessages({ numberOfMessages : 5 });

console.log("Messages received, requestId:", receivedMessagesResponse.requestId);

A metódus meghívásakor receiveMessages igény szerint megadhat értékeket a QueueReceiveMessageOptionsban az üzenetlekérés testreszabásához. Megadhat egy értéket numberOfMessages, 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.

Üzenetek törlése üzenetsorból

A beérkezett és feldolgozott üzeneteket törölheti az üzenetsorból. Ebben az esetben a feldolgozás csak az üzenetet jeleníti meg a konzolon.

Üzenetek törlése a metódus meghívásával deleteMessage . 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 függvény végéhez main :

// 'Process' and delete messages from the queue
for (i = 0; i < receivedMessagesResponse.receivedMessageItems.length; i++) {
    receivedMessage = receivedMessagesResponse.receivedMessageItems[i];

    // 'Process' the message
    console.log("\tProcessing:", receivedMessage.messageText);

    // Delete the message
    const deleteMessageResponse = await queueClient.deleteMessage(
        receivedMessage.messageId,
        receivedMessage.popReceipt
    );
    console.log("\tMessage deleted, requestId:", deleteMessageResponse.requestId);
}

Ü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 main függvény végéhez, és mentse a fájlt:

// Delete the queue
console.log("\nDeleting queue...");
const deleteQueueResponse = await queueClient.delete();
console.log("Queue deleted, requestId:", deleteQueueResponse.requestId);

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 a fájlt tartalmazó index.js könyvtárat, majd az alábbi node paranccsal futtassa az alkalmazást.

node index.js

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

Azure Queue Storage client library - JavaScript quickstart sample

Creating queue...
         quickstart<UUID>
Queue created, requestId: 5c0bc94c-6003-011b-7c11-b13d06000000

Adding messages to the queue...
Messages added, requestId: a0390321-8003-001e-0311-b18f2c000000

Peek at the messages in the queue...
         First message
         Second message
         Third message

Updating the third message in the queue...
Message updated, requestId: cb172c9a-5003-001c-2911-b18dd6000000

Receiving messages from the queue...
Messages received, requestId: a039036f-8003-001e-4811-b18f2c000000
        Processing: First message
        Message deleted, requestId: 4a65b82b-d003-00a7-5411-b16c22000000
        Processing: Second message
        Message deleted, requestId: 4f0b2958-c003-0030-2a11-b10feb000000
        Processing: Third message has been updated
        Message deleted, requestId: 6c978fcb-5003-00b6-2711-b15b39000000

Deleting queue...
Queue deleted, requestId: 5c0bca05-6003-011b-1e11-b13d06000000

Done

Haladjon végig a hibakeresőben található kódon, és ellenőrizze az Azure Portalt a folyamat során. Ellenőrizze a tárfiókot, hogy az üzenetsorban lévő üzenetek létre lettek-e hozva és törölve.

Következő lépések

Ebben a rövid útmutatóban megtanulta, hogyan hozhat létre üzenetsort, és hogyan adhat hozzá üzeneteket JavaScript-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:

Az Azure for JavaScript dokumentációja