Rövid útmutató: Azure Queue Storage-ügyfélkódtár JavaScripthez
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
- Azure-előfizetés – hozzon létre egyet ingyenesen
- Azure Storage-fiók – tárfiók létrehozása
- Az operációs rendszer aktuális Node.js-jei .
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
.
Egy konzolablakban (például parancsmag, PowerShell vagy Bash) hozzon létre egy új könyvtárat a projekthez:
mkdir queues-quickstart
Váltás az újonnan létrehozott
queues-quickstart
könyvtárra:cd queues-quickstart
Hozzon létre egy package.json fájlt:
npm init -y
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.
Telepítse az Azure Queue Storage npm-csomagot:
npm install @azure/storage-queue
Telepítse az Azure Identity npm-csomagot a jelszó nélküli kapcsolatok támogatásához:
npm install @azure/identity
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:
Új szövegfájl megnyitása a kódszerkesztőben
Hívások hozzáadása
require
az Azure- és Node.js-modulok betöltéséhezA 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));
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 DefaultAzureCredential
tekintse 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.
Az Azure Portalon keresse meg a tárfiókot a fő keresősávon vagy a bal oldali navigációs sávon.
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.
A Hozzáférés-vezérlés (IAM) lapon válassza a Szerepkör-hozzárendelések lapot.
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 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.
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.
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.
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.
Az alábbi JavaScript-osztályokkal kezelheti ezeket az erőforrásokat:
QueueServiceClient
: AQueueServiceClient
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
: AQueueClient
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
- Ü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
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 QueueClient
DefaultAzureCredential
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 DefaultAzureCredential
győ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 visibilityTimeout
is, 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:
- További információkért tekintse meg az Azure Queue Storage JavaScripthez készült ügyfélkódtárát.
- További Azure Queue Storage-mintaalkalmazásokért tekintse meg az Azure Queue Storage JavaScript-mintákhoz készült ügyfélkódtárát.