Delen via

Quickstart: Azure Queue Storage-clientbibliotheek voor JavaScript

  • Artikel

Ga aan de slag met de Azure Queue Storage-clientbibliotheek voor JavaScript. Azure Queue Storage is een service waarmee u grote aantallen berichten kunt opslaan om later op te halen en te verwerken. Volg deze stappen om het pakket te installeren en voorbeeldcode voor basistaken uit te proberen.

API-referentiedocumentatie | -bibliotheek broncode | package (npm) | -voorbeelden

Gebruik de Azure Queue Storage-clientbibliotheek voor JavaScript om:

  • Een wachtrij maken
  • Berichten aan een wachtrij toevoegen
  • Berichten in een wachtrij bekijken
  • Een bericht in een wachtrij bijwerken
  • Lengte van de wachtrij ophalen
  • Berichten van een wachtrij ontvangen
  • Berichten uit een wachtrij verwijderen
  • Een wachtrij verwijderen

Vereisten

Instellen

In deze sectie wordt uitgelegd hoe u een project voorbereidt voor gebruik met de Azure Queue Storage-clientbibliotheek voor JavaScript.

Het project maken

Maak een Node.js-toepassing met de naam queues-quickstart.

  1. Maak in een consolevenster (zoals cmd, PowerShell of Bash) een nieuwe map voor het project:

    mkdir queues-quickstart

  2. Schakel over naar de zojuist gemaakte queues-quickstart map:

    cd queues-quickstart

  3. Maak een package.json-bestand :

    npm init -y

  4. Open het project in Visual Studio Code:

    code .

De pakketten installeren

Installeer vanuit de projectmap de volgende pakketten met behulp van de npm install opdracht.

  1. Installeer het NPM-pakket voor Azure Queue Storage:

    npm install @azure/storage-queue

  2. Installeer het Azure Identity NPM-pakket om wachtwoordloze verbindingen te ondersteunen:

    npm install @azure/identity

  3. Installeer andere afhankelijkheden die in deze quickstart worden gebruikt:

    npm install uuid dotenv

Stel het app-framework in

Ga als volgt te werk vanuit de projectmap:

  1. Open een nieuw tekstbestand in uw code-editor

  2. Voeg require-aanroepen toe om Azure- en Node.js-modules te laden

  3. Maak de structuur voor het programma, waaronder eenvoudige afhandeling van uitzonderingen

    Hier volgt de code:

    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. Sla het nieuwe bestand op zoals index.js in de queues-quickstart map.

Verifiëren bij Azure

Toepassingsaanvragen voor de meeste Azure-services moeten worden geautoriseerd. Het gebruik van de DefaultAzureCredential klasse die wordt geleverd door de Azure Identity-clientbibliotheek is de aanbevolen methode voor het implementeren van wachtwoordloze verbindingen met Azure-services in uw code.

U kunt aanvragen voor Azure-services ook rechtstreeks autoriseren met behulp van wachtwoorden, verbindingsreeks s of andere referenties. Deze aanpak moet echter met voorzichtigheid worden gebruikt. Ontwikkelaars moeten ijverig zijn om deze geheimen nooit zichtbaar te maken op een onbeveiligde locatie. Iedereen die toegang krijgt tot het wachtwoord of de geheime sleutel, kan worden geverifieerd. DefaultAzureCredential biedt verbeterde beheer- en beveiligingsvoordelen ten opzichte van de accountsleutel om verificatie zonder wachtwoord mogelijk te maken. Beide opties worden in het volgende voorbeeld gedemonstreerd.

DefaultAzureCredential is een klasse die wordt geleverd door de Azure Identity-clientbibliotheek voor JavaScript. Zie het overzicht DefaultAzureCredential voor meer DefaultAzureCredentialinformatie. DefaultAzureCredential ondersteunt meerdere verificatiemethoden en bepaalt welke methode tijdens runtime moet worden gebruikt. Met deze aanpak kan uw app verschillende verificatiemethoden gebruiken in verschillende omgevingen (lokaal versus productie) zonder omgevingsspecifieke code te implementeren.

Uw app kan bijvoorbeeld verifiëren met behulp van uw Aanmeldingsreferenties voor Azure CLI bij het lokaal ontwikkelen en vervolgens een beheerde identiteit gebruiken zodra deze is geïmplementeerd in Azure. Er zijn geen codewijzigingen vereist voor deze overgang.

Wanneer u lokaal ontwikkelt, moet u ervoor zorgen dat het gebruikersaccount dat toegang heeft tot de wachtrijgegevens over de juiste machtigingen beschikt. U hebt Inzender voor opslagwachtrijgegevens nodig om wachtrijgegevens te lezen en te schrijven. Als u uzelf deze rol wilt toewijzen, moet u de rol Gebruikerstoegang Beheer istrator of een andere rol met de actie Microsoft.Authorization/roleAssignments/write toegewezen krijgen. U kunt Azure RBAC-rollen toewijzen aan een gebruiker met behulp van Azure Portal, Azure CLI of Azure PowerShell. Meer informatie over de beschikbare bereiken voor roltoewijzingen vindt u op de overzichtspagina van het bereik.

In dit scenario wijst u machtigingen toe aan uw gebruikersaccount, dat is afgestemd op het opslagaccount, om het principe van minimale bevoegdheden te volgen. Deze procedure biedt gebruikers alleen de minimale machtigingen die nodig zijn en maakt veiligere productieomgevingen.

In het volgende voorbeeld wordt de rol Inzender voor opslagwachtrijgegevens toegewezen aan uw gebruikersaccount, dat zowel lees- als schrijftoegang biedt tot wachtrijgegevens in uw opslagaccount.

Belangrijk

In de meeste gevallen duurt het een of twee minuten voordat de roltoewijzing is doorgegeven in Azure, maar in zeldzame gevallen kan het maximaal acht minuten duren. Als u verificatiefouten ontvangt wanneer u de code voor het eerst uitvoert, wacht u even en probeert u het opnieuw.

  1. Zoek uw opslagaccount in Azure Portal met behulp van de hoofdzoekbalk of linkernavigatiebalk.

  2. Selecteer op de overzichtspagina van het opslagaccount toegangsbeheer (IAM) in het menu aan de linkerkant.

  3. Selecteer op de pagina Toegangsbeheer (IAM) het tabblad Roltoewijzingen .

  4. Selecteer + Toevoegen in het bovenste menu en voeg vervolgens roltoewijzing toe in de resulterende vervolgkeuzelijst.

A screenshot showing how to assign a role.

  1. Gebruik het zoekvak om de resultaten te filteren op de gewenste rol. In dit voorbeeld zoekt u inzender voor opslagwachtrijgegevens en selecteert u het overeenkomende resultaat en kiest u vervolgens Volgende.

  2. Selecteer onder Toegang toewijzen de optie Gebruiker, groep of service-principal en kies vervolgens + Leden selecteren.

  3. Zoek in het dialoogvenster naar uw Microsoft Entra-gebruikersnaam (meestal uw user@domain e-mailadres) en kies Vervolgens onderaan het dialoogvenster Selecteren .

  4. Selecteer Beoordelen + toewijzen om naar de laatste pagina te gaan en vervolgens opnieuw beoordelen en toewijzen om het proces te voltooien.

Objectmodel

Azure Queue Storage is een service om grote aantallen berichten op te slaan. Een wachtrijbericht kan maximaal 64 KB groot zijn. Een wachtrij kan miljoenen berichten bevatten, tot aan de totale capaciteitslimiet van een opslagaccount. Wachtrijen worden vaak gebruikt om een voorraad werk te maken dat asynchroon moet worden verwerkt. Queue Storage biedt drie typen resources:

  • Opslagaccount: Alle toegang tot Azure Storage wordt uitgevoerd via een opslagaccount. Zie overzicht van opslagaccounts voor meer informatie over opslagaccounts
  • Wachtrij: Een wachtrij bevat een set berichten. Alle berichten moeten zich in een wachtrij bevinden. De naam van een wachtrij mag alleen kleine letters bevatten. Zie Naming Queues and Metadata (Wachtrijen en metagegevens een naam geven) voor informatie over de naamgeving van wachtrijen.
  • Bericht: Een bericht in een willekeurige indeling, van maximaal 64 KB. Een bericht kan maximaal 7 dagen in de wachtrij blijven. Voor versie 29-07-2017 of hoger mag de maximale time-to-live elk positief getal zijn. Of -1 om aan te geven dat het bericht niet verloopt. Als deze parameter wordt weggelaten, is de standaard time-to-live zeven dagen.

Het volgende diagram geeft de relatie tussen deze resources weer.

Diagram of Queue storage architecture

Gebruik de volgende JavaScript-klassen om te communiceren met deze resources:

  • QueueServiceClient: Een QueueServiceClient exemplaar vertegenwoordigt een verbinding met een bepaald opslagaccount in de Azure Storage Queue-service. Met deze client kunt u alle wachtrijen in uw opslagaccount beheren.
  • QueueClient: Een QueueClient exemplaar vertegenwoordigt één wachtrij in een opslagaccount. Met deze client kunt u een afzonderlijke wachtrij en de bijbehorende berichten beheren en bewerken.

Codevoorbeelden

Deze voorbeeldcodefragmenten laten zien hoe u de volgende acties kunt uitvoeren met de Azure Queue Storage-clientbibliotheek voor JavaScript:

Toegang autoriseren en een clientobject maken

Zorg ervoor dat u bent geverifieerd met hetzelfde Microsoft Entra-account waaraan u de rol hebt toegewezen. U kunt zich verifiëren via Azure CLI, Visual Studio Code of Azure PowerShell.

Meld u aan bij Azure via de Azure CLI met behulp van de volgende opdracht:

az login

Nadat u bent geverifieerd, kunt u een QueueClient object maken en autoriseren met behulp van DefaultAzureCredential toegang tot wachtrijgegevens in het opslagaccount. DefaultAzureCredential detecteert en gebruikt automatisch het account waarmee u zich in de vorige stap hebt aangemeld.

Als u het gebruik DefaultAzureCredentialwilt autoriseren, controleert u of u het @azure/identity-pakket hebt toegevoegd, zoals beschreven in De pakketten installeren. Zorg er ook voor dat u de module @azure/identity in het bestand index.js laadt:

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

Bepaal een naam voor de wachtrij en maak een exemplaar van de QueueClient klasse met behulp van DefaultAzureCredential autorisatie. We gebruiken dit clientobject om de wachtrijresource in het opslagaccount te maken en ermee te communiceren.

Belangrijk

Wachtrijnamen mogen alleen kleine letters, cijfers en afbreekstreepjes bevatten en moeten beginnen met een letter of cijfer. Elk afbreekstreepje moet worden voorafgegaan en gevolgd door een cijfer of letter. De naam moet bovendien tussen 3 en 63 tekens lang zijn. Zie Naamgeving van wachtrijen en metagegevens voor meer informatie over de naamgeving van wachtrijen.

Voeg de volgende code toe in de main methode en zorg ervoor dat u de <storage-account-name> tijdelijke aanduidingswaarde vervangt:

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

Notitie

Berichten die met de QueueClient klasse worden verzonden, moeten een indeling hebben die kan worden opgenomen in een XML-aanvraag met UTF-8-codering. Als u markeringen wilt opnemen in het bericht, moet de inhoud van het bericht XML-escaped of Base64-gecodeerd zijn.

Berichten in wachtrijen worden opgeslagen als tekenreeksen. Als u een ander gegevenstype wilt verzenden, moet u dat gegevenstype serialiseren in een tekenreeks bij het verzenden van het bericht en deserialiseren van de tekenreeksindeling bij het lezen van het bericht.

Als u JSON wilt converteren naar een tekenreeksindeling en opnieuw wilt converteren in Node.js, gebruikt u de volgende helperfuncties:

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

Een wachtrij maken

Roep met behulp van het QueueClient object de create methode aan om de wachtrij in uw opslagaccount te maken.

Voeg deze code toe aan het einde van de main-methode:

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

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

Berichten aan een wachtrij toevoegen

Met het volgende codefragment worden berichten aan de wachtrij toegevoegd door de methode sendMessage aan te roepen. Ook wordt de QueueSendMessageResponse opgeslagen die met de derde sendMessage-aanroep wordt geretourneerd. De geretourneerde sendMessageResponse wordt gebruikt om de inhoud van een bericht later in het programma bij te werken.

Voeg deze code toe aan het einde van de functie 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);

Berichten in een wachtrij bekijken

Bekijk de berichten in de wachtrij door de methode peekMessages aan te roepen. Met deze methode worden één of meer berichten vooraan in de wachtrij opgehaald, maar wordt de zichtbaarheid van het bericht niet gewijzigd. peekMessages Bekijk standaard één bericht.

Voeg deze code toe aan het einde van de functie 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);
}

Een bericht in een wachtrij bijwerken

Werk de inhoud van een bericht bij door de methode updateMessage aan te roepen. Deze methode kan de time-out voor zichtbaarheid en de inhoud van een bericht wijzigen. De inhoud van het bericht moet een UTF-8-gecodeerde tekenreeks zijn die maximaal 64 KB groot is. Geef behalve de nieuwe inhoud ook messageId en popReceipt uit het antwoord dat eerder in de code was opgeslagen. De sendMessageResponse-eigenschappen identificeren welk bericht moet worden bijgewerkt.

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

Lengte van de wachtrij ophalen

De getProperties methode retourneert metagegevens over de wachtrij, inclusief het geschatte aantal berichten dat in de wachtrij wacht.

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

Berichten van een wachtrij ontvangen

Download eerder toegevoegde berichten door de methode receiveMessages aan te roepen. Geef in het veld numberOfMessages het maximumaantal berichten op dat voor deze aanroep moet worden ontvangen.

Voeg deze code toe aan het einde van de functie 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);

Wanneer u de receiveMessages methode aanroept, kunt u desgewenst waarden opgeven in QueueReceiveMessageOptions om het ophalen van berichten aan te passen. U kunt een waarde opgeven voor numberOfMessages, wat het aantal berichten is dat uit de wachtrij moet worden opgehaald. De standaardwaarde is 1 bericht en het maximum is 32 berichten. U kunt ook een waarde opgeven waarvoor visibilityTimeoutde berichten voor de time-outperiode worden verborgen voor andere bewerkingen. De standaardwaarde is 30 seconden.

Berichten uit een wachtrij verwijderen

U kunt berichten uit de wachtrij verwijderen nadat ze zijn ontvangen en verwerkt. In dit geval betekent ‘verwerken’ gewoon dat het bericht wordt weergegeven in de console.

Verwijder berichten door de methode deleteMessage aan te roepen. Berichten die niet expliciet worden verwijderd, worden uiteindelijk weer zichtbaar in de wachtrij voor een andere kans om ze te verwerken.

Voeg deze code toe aan het einde van de functie 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);
}

Een wachtrij verwijderen

Met de volgende code worden de resources opgeschoond die met de app zijn gemaakt, door de wachtrij te verwijderen met de methode delete.

Voeg deze code toe aan het einde van het main-functie en sla het bestand op:

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

De code uitvoeren

Met deze app worden drie berichten gemaakt en aan een Azure-wachtrij toegevoegd. De code toont de berichten in de wachtrij, haalt ze op en verwijdert ze, en verwijdert uiteindelijk de wachtrij.

Navigeer in het consolevenster naar de map die het bestand index.js bevat, en voer de volgende opdracht node uit om de app uit te voeren.

node index.js

De uitvoer van de app lijkt op die in het volgende voorbeeld:

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

Neem de code in uw foutopsporingsprogramma door en controleer uw Azure-portal gedurende de hele procedure. Controleer uw opslagaccount om te controleren of er berichten in de wachtrij zijn gemaakt en verwijderd.

Volgende stappen

In deze quickstart hebt u geleerd hoe u een wachtrij maakt en berichten eraan toevoegt met behulp van JavaScript-code. Vervolgens leerde u hoe u berichten kunt bekijken, ophalen en verwijderen. Tot slot leerde u hoe u een berichtenwachtrij verwijdert.

Voor zelfstudies, voorbeelden, quickstarts en andere documentatie gaat u naar:

Documentatie over Azure voor JavaScript