Snabbstart: Azure Queue Storage-klientbibliotek för JavaScript

Kom igång med Azure Queue Storage-klientbiblioteket för JavaScript. 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 Bibliotek källkodspaket | (npm)Exempel | |

Använd Azure Queue Storage-klientbiblioteket för JavaScript 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

• Azure-prenumeration – skapa en kostnadsfritt
• Azure Storage-konto – skapa ett lagringskonto
• Aktuella Node.js för operativsystemet.

Konfigurera

Det här avsnittet beskriver hur du förbereder ett projekt för att arbeta med Azure Queue Storage-klientbiblioteket för JavaScript.

Skapa projektet

Skapa ett Node.js-program med namnet queues-quickstart.

1. I ett konsolfönster (till exempel cmd, PowerShell eller Bash) skapar du en ny katalog för projektet:

   mkdir queues-quickstart
   

2. Växla till den nyligen skapade queues-quickstart katalogen:

   cd queues-quickstart
   

3. Skapa en package.json-fil :

   npm init -y
   

4. Öppna projektet i Visual Studio Code:

   code .
   

Installera paketen

Från projektkatalogen installerar du följande paket med hjälp av npm install kommandot .

1. Installera Azure Queue Storage npm-paketet:

   npm install @azure/storage-queue
   

2. Installera Azure Identity npm-paketet för att stödja lösenordslösa anslutningar:

   npm install @azure/identity
   

3. Installera andra beroenden som används i den här snabbstarten:

   npm install uuid dotenv
   

Konfigurera appramverket

Från projektkatalogen:

1. Öppna en ny textfil i kodredigeraren

2. Lägga till require anrop för att läsa in Azure- och Node.js-moduler

3. Skapa strukturen för programmet, inklusive grundläggande undantagshantering

   Här är koden:

   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. Spara den nya filen som index.js i queues-quickstart katalogen.

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 din kod.

Du kan också auktorisera begäranden till Azure-tjänster med hjälp av lösenord, anslutningssträng eller andra autentiseringsuppgifter direkt. Den här metoden bör dock användas med försiktighet. Utvecklare måste vara noggranna för 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.

Lösenordsfri (rekommenderas)

DefaultAzureCredential är en klass som tillhandahålls av Azure Identity-klientbiblioteket för JavaScript. 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-portalen, Azure CLI eller Azure PowerShell. Du kan lära dig 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 endast 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å för rolltilldelningen att spridas 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.

Azure-portalen

1. Leta upp ditt lagringskonto i Azure-portalen 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 nedrullningsbara menyn.

5. 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 väljer sedan Nästa.

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

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

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

Azure CLI

Om du vill tilldela en roll på resursnivå med hjälp av Azure CLI måste du först hämta resurs-ID:t med kommandot az storage account show . Du kan filtrera utdataegenskaperna med hjälp av parametern --query .

az storage account show --resource-group '<your-resource-group-name>' --name '<your-storage-account-name>' --query id

Kopiera utdata Id från föregående kommando. Du kan sedan tilldela roller med kommandot az role för Azure CLI.

az role assignment create --assignee "<user@domain>" \
    --role "Storage Queue Data Contributor" \
    --scope "<your-resource-id>"

PowerShell

Om du vill tilldela en roll på resursnivå med Hjälp av Azure PowerShell måste du först hämta resurs-ID:t med kommandot Get-AzResource .

Get-AzResource -ResourceGroupName "<yourResourceGroupname>" -Name "<yourStorageAccountName>"

Kopiera värdet Id från föregående kommandoutdata. Du kan sedan tilldela roller med kommandot New-AzRoleAssignment i PowerShell.

New-AzRoleAssignment -SignInName <user@domain> `
    -RoleDefinitionName "Storage Queue Data Contributor" `
    -Scope <yourStorageAccountId>

Anslutningssträng

Kopiera dina autentiseringsuppgifter från Azure-portalen

När exempelprogrammet skickar en begäran till Azure Storage måste det vara auktoriserat. Om du vill auktorisera en begäran lägger du till dina autentiseringsuppgifter för lagringskontot i programmet som en anslutningssträng. Följ dessa steg för att visa dina autentiseringsuppgifter för lagringskontot:

1. Logga in på Azure-portalen.

2. Leta rätt på ditt lagringskonto.

3. I menyfönstret för lagringskonto går du till Säkerhet + nätverk och väljer Åtkomstnycklar. Här kan du visa kontoåtkomstnycklarna och hela anslutningssträng för varje nyckel.

   

4. I fönstret Åtkomstnycklar väljer du Visa nycklar.

5. Leta upp värdet för Anslut ionssträngen i avsnittet key1. Välj ikonen Kopiera till Urklipp för att kopiera anslutningssträng. Du lägger till värdet anslutningssträng i en miljövariabel i nästa avsnitt.

   

Konfigurera anslutningssträngen för lagring

När du har kopierat anslutningssträng skriver du den till en ny miljövariabel på den lokala dator som kör programmet. Konfigurera miljövariabeln genom att öppna ett konsolfönster och följa anvisningarna för ditt operativsystem. Ersätt <yourconnectionstring> med din faktiska anslutningssträng.

Windows

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

Linux och macOS

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

När du har lagt till miljövariabeln i Windows måste du starta en ny instans av kommandofönstret.

Starta om program

När du har lagt till miljövariabeln startar du om alla program som körs och som behöver läsa miljövariabeln. Starta till exempel om utvecklingsmiljön eller redigeringsprogrammet innan du fortsätter.

Viktigt!

Kontoåtkomstnyckeln bör användas med försiktighet. Om din kontoåtkomstnyckel går förlorad eller oavsiktligt placeras på en osäker plats kan tjänsten bli sårbar. Alla som har åtkomstnyckeln kan auktorisera begäranden mot lagringskontot och har effektivt åtkomst till alla data. DefaultAzureCredential ger förbättrade säkerhetsfunktioner och fördelar och är den rekommenderade metoden för att hantera auktorisering till Azure-tjänster.

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 görs 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 valfritt format, som är 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 tiden till 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 till live sju dagar.

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

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

• QueueServiceClient: En QueueServiceClient instans representerar en anslutning till ett visst lagringskonto i Azure Storage Queue-tjänsten. Med den här klienten kan du hantera alla köer i ditt lagringskonto.
• QueueClient: En QueueClient instans representerar en enskild kö i ett lagringskonto. Med den här klienten kan du hantera och ändra en enskild kö och dess meddelanden.

Kodexempel

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

• Auktorisera åtkomst och skapa ett klientobjekt
• 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ö

Lösenordsfri (rekommenderas)

Auktorisera åtkomst och skapa ett klientobjekt

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

Azure CLI

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

az login

Visual Studio Code

Du måste installera Azure CLI för att arbeta med DefaultAzureCredential via Visual Studio Code.

Gå till Terminal > Ny terminal på huvudmenyn i Visual Studio Code.

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

az login

PowerShell

Logga in på Azure med hjälp av PowerShell via följande kommando:

Connect-AzAccount

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 paketet @azure/identitet enligt beskrivningen i Installera paketen. Läs också in modulen @azure/identitet i filen index.js :

const { DefaultAzureCredential } = require('@azure/identity');

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

Viktigt!

Könamn får endast 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 följande kod i main metoden och ersätt <storage-account-name> platshållarvärdet:

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

Anslutningssträng

Hämta anslutningssträng och skapa en klient

Följande kod hämtar anslutningssträng för lagringskontot. Anslutningssträng lagras i miljövariabeln som skapas i avsnittet Konfigurera lagring anslutningssträng.

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

// Retrieve the connection string for use with the application. The storage
// connection string is stored in an environment variable on the machine
// running the application called AZURE_STORAGE_CONNECTION_STRING. If the
// environment variable is created after the application is launched in a
// console or with Visual Studio, the shell or application needs to be
// closed and reloaded to take the environment variable into account.
const AZURE_STORAGE_CONNECTION_STRING = process.env.AZURE_STORAGE_CONNECTION_STRING;

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

Viktigt!

Könamn får endast 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 finns i Namngivning av köer och metadata.

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

// 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
const queueClient = new QueueClient(AZURE_STORAGE_CONNECTION_STRING, queueName);

Kommentar

Meddelanden som skickas med QueueClient klassen måste vara i ett format som kan ingå i en XML-begäran med UTF-8-kodning. Om du vill inkludera markering i meddelandet måste innehållet i meddelandet antingen vara XML-undantaget eller Base64-kodat.

Kömeddelanden lagras som strängar. Om du behöver skicka en annan datatyp måste du serialisera datatypen till en sträng när du skickar meddelandet och deserialisera strängformatet när du läser meddelandet.

Om du vill konvertera JSON till ett strängformat och gå tillbaka igen i Node.js använder du följande hjälpfunktioner:

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

Skapa en kö

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

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

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

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

Lägga till meddelanden i en kö

Följande kodfragment lägger till meddelanden i kön genom att anropa sendMessage metoden. Den sparar även de QueueSendMessageResponse returnerade från det tredje sendMessage anropet. Den returnerade sendMessageResponse används för att uppdatera meddelandeinnehållet senare i programmet.

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

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

Titta på meddelanden i en kö

Titta på 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. Som standard peekMessages tittar du på ett enda meddelande.

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

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

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 tidsgräns för synlighet och innehåll. Meddelandeinnehållet måste vara en UTF-8-kodad sträng som är upp till 64 KB stor. Tillsammans med det nya innehållet skickar du in messageId och popReceipt från svaret som sparades tidigare i koden. Egenskaperna sendMessageResponse identifierar vilket meddelande som ska uppdateras.

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

Hämta kölängden

Metoden getProperties returnerar metadata om kön, inklusive det ungefärliga antalet meddelanden som väntar i kön.

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

Ta emot meddelanden från en kö

Ladda ned tidigare tillagda meddelanden genom att anropa receiveMessages metoden. I fältet numberOfMessages skickar du det maximala antalet meddelanden som ska ta emot för det här anropet.

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

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

När du anropar receiveMessages metoden kan du ange värden i QueueReceiveMessageOptions för att anpassa meddelandehämtningen. Du kan ange ett värde för numberOfMessages, vilket är antalet meddelanden som ska hämtas från kön. Standardvärdet är 1 meddelande och det maximala är 32 meddelanden. Du kan också ange ett värde för visibilityTimeout, som döljer meddelandena från andra åtgärder under tidsgränsperioden. Standardvärdet är 30 sekunder.

Ta bort meddelanden från en kö

Du kan ta bort meddelanden från kön när de har tagits emot och bearbetats. I det här fallet visar bearbetningen bara meddelandet i konsolen.

Ta bort meddelanden genom att anropa deleteMessage metoden. Meddelanden som inte uttryckligen tas bort visas så småningom i kön igen för en ny chans att bearbeta dem.

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

// '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);
}

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 funktionen och spara filen:

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

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 sedan bort dem innan du slutligen tar bort kön.

I konsolfönstret navigerar du till katalogen som innehåller index.js filen och använder sedan följande node kommando för att köra appen.

node index.js

Utdata från appen liknar följande exempel:

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

Gå igenom koden i felsökningsprogrammet och kontrollera Azure-portalen under hela processen. Kontrollera lagringskontot för att kontrollera att meddelanden i kön har skapats och tagits bort.

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 JavaScript-kod. Sedan lärde du dig att granska, hämta och ta bort meddelanden. Slutligen har du lärt dig hur du tar bort en meddelandekö.

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

Dokumentation om Azure for JavaScript

• Mer information finns i Azure Queue Storage-klientbiblioteket för JavaScript.
• Fler Azure Queue Storage-exempelappar finns i Azure Queue Storage-klientbiblioteket för JavaScript – exempel.