Azure Storage Queue-klientbibliotek för JavaScript – version 12.28.1

2025-10-17

Azure Storage Queue tillhandahåller molnmeddelanden mellan programkomponenter. När program utformas för skalning är programkomponenter ofta frikopplade, så att de kan skalas separat. Queue Storage levererar asynkrona meddelanden för kommunikation mellan programkomponenter, oavsett om de körs i molnet, på skrivbordet, på en lokal server eller på en mobil enhet. Kölagring stöder också hantering av asynkrona uppgifter och skapande av processarbetsflöden.

Det här projektet tillhandahåller ett klientbibliotek i JavaScript som gör det enkelt att använda Azure Storage Queue-tjänsten.

Använd klientbiblioteken i det här paketet för att:

Egenskaper för get/set-kötjänsten
Skapa/lista/ta bort köer
Skicka/ta emot/granska/rensa/uppdatera/ta bort kömeddelanden

Nyckellänkar:

Komma igång

Miljöer som stöds för närvarande

LTS-versioner av Node.js
De senaste versionerna av Safari, Chrome, Edge och Firefox.

Mer information finns i vår supportprincip.

Prerequisites

En prenumeration på Azure
Ett lagringskonto

Installera paketet

Det bästa sättet att installera Azure Storage Queue-klientbiblioteket för JavaScript är att använda npm-pakethanteraren. Skriv följande i ett terminalfönster:

npm install @azure/storage-queue

Autentisera klienten

Azure Storage stöder flera sätt att autentisera. För att interagera med Azure Queue Storage-tjänsten måste du till exempel skapa en instans av en Lagringsklient – QueueServiceClient eller QueueClient. Mer information om autentisering finns i exempel för att skapa QueueServiceClient.

Azure Active Directory
Delad nyckel
Signaturer för delad åtkomst

Azure Active Directory

Azure Queue Storage-tjänsten stöder användning av Azure Active Directory för att autentisera begäranden till dess API:er. @azure/identity-paketet innehåller en mängd olika typer av autentiseringsuppgifter som programmet kan använda för att göra detta. Mer information och exempel finns i README för @azure/identity för att komma igång.

Compatibility

Det här biblioteket är kompatibelt med Node.js och webbläsare och verifieras mot LTS-Node.js versioner (>=8.16.0) och de senaste versionerna av Chrome, Firefox och Edge.

Webbarbetare

Det här biblioteket kräver att vissa DOM-objekt är globalt tillgängliga när de används i webbläsaren, vilket webbarbetare inte gör tillgängliga som standard. Du måste polyfylla dessa för att det här biblioteket ska fungera i webbarbetare.

Mer information finns i vår dokumentation för att använda Azure SDK för JS i Web Workers

Det här biblioteket är beroende av följande DOM-API:er som behöver externa polyfyller som läses in när de används i webbarbetare:

Skillnader mellan Node.js och webbläsare

Det finns skillnader mellan Node.js och webbläsarkörning. När du kommer igång med det här biblioteket bör du vara uppmärksam på API:er eller klasser som har markerats med "ONLY AVAILABLE IN NODE.JS RUNTIME" eller "ONLY AVAILABLE IN BROWSERS".

Följande funktioner, gränssnitt, klasser eller funktioner är endast tillgängliga i Node.js

Auktorisering av delad nyckel baserat på kontonamn och kontonyckel
- StorageSharedKeyCredential
Generering av signatur för delad åtkomst (SAS)
- generateAccountSASQueryParameters()
- generateQueueSASQueryParameters()

JavaScript-paket

Om du vill använda det här klientbiblioteket i webbläsaren måste du först använda en bundler. Mer information om hur du gör detta finns i vår paketeringsdokumentation.

CORS

Du måste konfigurera CORS (Cross-Origin Resource Sharing) regler för ditt lagringskonto om du behöver utveckla för webbläsare. Gå till Azure-portalen och Azure Storage Explorer, leta reda på ditt lagringskonto, skapa nya CORS-regler för blob/kö/fil/tabelltjänster.

Du kan till exempel skapa följande CORS-inställningar för felsökning. Men anpassa inställningarna noggrant enligt dina krav i produktionsmiljön.

Tillåtet ursprung: *
Tillåtna verb: DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
Tillåtna rubriker: *
Synliga rubriker: *
Maximal ålder (sekunder): 86400

Viktiga begrepp

En kö är ett datalager i ett Azure Storage Queue-tjänstkonto för att skicka/ta emot meddelanden mellan anslutna klienter.

Viktiga datatyper i vårt bibliotek som är relaterade till dessa tjänster är:

A QueueServiceClient representerar en anslutning (via en URL) till ett visst lagringskonto i Azure Storage Queue-tjänsten och tillhandahåller API:er för att manipulera dess köer. Den autentiseras till tjänsten och kan användas för att skapa QueueClient objekt, samt skapa, ta bort, lista köer från tjänsten.
A QueueClient representerar en enskild kö i lagringskontot. Den kan användas för att ändra köns meddelanden, till exempel för att skicka, ta emot och granska meddelanden i kön.

Examples

Importera paketet

Om du vill använda klienterna importerar du paketet till filen:

import * as AzureStorageQueue from "@azure/storage-queue";

Alternativt kan du selektivt importera endast de typer som du behöver:

import { QueueServiceClient, StorageSharedKeyCredential } from "@azure/storage-queue";

Skapa kötjänstklienten

QueueServiceClient kräver en URL till kötjänsten och en åtkomstautentiseringsuppgift. Du kan också välja att acceptera vissa inställningar i parametern options.

med `DefaultAzureCredential` från `@azure/identity`-paketet

Rekommenderat sätt att instansiera en QueueServiceClient

Installation: Referens – Auktorisera åtkomst till blobar och köer med Azure Active Directory från ett klientprogram – https://free.blessedness.top/azure/storage/common/storage-auth-aad-app

Registrera ett nytt AAD-program och ge behörighet att få åtkomst till Azure Storage för den inloggade användarens räkning
- Registrera ett nytt program i Azure Active Directory (i azure-portal) – https://free.blessedness.top/azure/active-directory/develop/quickstart-register-app
- I avsnittet API permissions väljer du Add a permission och väljer Microsoft APIs.
- Välj Azure Storage och markera kryssrutan bredvid user_impersonation och klicka sedan på Add permissions. Detta skulle göra det möjligt för programmet att komma åt Azure Storage för den inloggade användarens räkning.
Bevilja åtkomst till Azure Storage Queue-data med RBAC i Azure-portalen
- RBAC-roller för blobar och köer – https://free.blessedness.top/azure/storage/common/storage-auth-aad-rbac-portal.
- I Azure-portalen går du till ditt lagringskonto och tilldelar Storage Queue Data Contributor roll till det registrerade AAD-programmet från fliken Access control (IAM) (i navigeringsfältet till vänster i lagringskontot i Azure-portalen).
Miljökonfiguration för exemplet
- På översiktssidan för ditt AAD-program noterar du CLIENT ID och TENANT ID. På fliken "Certifikat & hemligheter" skapar du en hemlighet och noterar den nedåt.
- Kontrollera att du har AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET som miljövariabler för att köra exemplet (kan utnyttja process.env).

import { DefaultAzureCredential } from "@azure/identity";
import { QueueServiceClient } from "@azure/storage-queue";

const account = "<account>";
const credential = new DefaultAzureCredential();

const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  credential,
);

[Obs! Stegen ovan gäller endast för Node.js]

använda anslutningssträng

Du kan också instansiera en QueueServiceClient med hjälp av den fromConnectionString() statiska metoden med den fullständiga anslutningssträngen som argument. (Anslutningssträngen kan hämtas från Azure-portalen.) [ENDAST TILLGÄNGLIGT I NODE.JS RUNTIME]

import { QueueServiceClient } from "@azure/storage-queue";

const connectionString = "<connection string>";

const queueServiceClient = QueueServiceClient.fromConnectionString(connectionString);

med `StorageSharedKeyCredential`

Du kan också instansiera a QueueServiceClient med a StorageSharedKeyCredential genom att skicka accountName och accountKey som argument. (Värdena för kontonamn och kontonyckel kan hämtas från Azure Portal.) [ENDAST TILLGÄNGLIGT I NODE.JS KÖRNING]

import { StorageSharedKeyCredential, QueueServiceClient } from "@azure/storage-queue";

// Enter your storage account name and shared key
const account = "<account>";
const accountKey = "<accountkey>";

// Use StorageSharedKeyCredential with storage account and account key
// StorageSharedKeyCredential is only available in Node.js runtime, not in browsers
const sharedKeyCredential = new StorageSharedKeyCredential(account, accountKey);

const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  sharedKeyCredential,
  {
    retryOptions: { maxTries: 4 }, // Retry options
    userAgentOptions: {
      userAgentPrefix: "BasicSample V10.0.0",
    }, // Customized telemetry string
  },
);

med SAS-token

Du kan också instansiera en QueueServiceClient med en signatur för delad åtkomst (SAS). Du kan hämta SAS-token från Azure-portalen eller generera en med hjälp av generateAccountSASQueryParameters().

import { QueueServiceClient } from "@azure/storage-queue";

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";
const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net?${sas}`,
);

Lista köer i det här kontot

Använd funktionen QueueServiceClient.listQueues() för att iterera köerna med den nya for-await-of syntaxen:

import { QueueServiceClient } from "@azure/storage-queue";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  new DefaultAzureCredential(),
);

let i = 1;
for await (const item of queueServiceClient.listQueues()) {
  console.log(`Queue${i++}: ${item.name}`);
}

Alternativt utan for-await-of:

import { QueueServiceClient } from "@azure/storage-queue";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  new DefaultAzureCredential(),
);

let i = 1;
const iterator = queueServiceClient.listQueues();
let { done, value } = await iterator.next();
while (!done) {
  console.log(`Queue${i++}: ${value.name}`);
  ({ done, value } = await iterator.next());
}

Ett fullständigt exempel på iterering av köer finns i samples/v12/typescript/listQueues.ts.

Skapa en ny kö

Använd funktionen QueueServiceClient.getQueueClient() för att skapa en ny kö.

import { QueueServiceClient } from "@azure/storage-queue";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  new DefaultAzureCredential(),
);

const queueName = "<valid queue name>";
const queueClient = queueServiceClient.getQueueClient(queueName);
const createQueueResponse = await queueClient.create();
console.log(
  `Created queue ${queueName} successfully, service assigned request Id: ${createQueueResponse.requestId}`,
);

Skicka ett meddelande till kön

Använd sendMessage() för att lägga till ett meddelande i kön:

import { QueueServiceClient } from "@azure/storage-queue";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  new DefaultAzureCredential(),
);

const queueName = "<valid queue name>";
const queueClient = queueServiceClient.getQueueClient(queueName);
// Send a message into the queue using the sendMessage method.
const sendMessageResponse = await queueClient.sendMessage("Hello World!");
console.log(
  `Sent message successfully, service assigned message Id: ${sendMessageResponse.messageId}, service assigned request Id: ${sendMessageResponse.requestId}`,
);

Granska ett meddelande

QueueClient.peekMessages() tillåter att du tittar på ett eller flera meddelanden framför kön. Det här anropet hindrar inte annan kod från att komma åt kikade meddelanden.

import { QueueServiceClient } from "@azure/storage-queue";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  new DefaultAzureCredential(),
);

const queueName = "<valid queue name>";
const queueClient = queueServiceClient.getQueueClient(queueName);
const peekMessagesResponse = await queueClient.peekMessages();
console.log(`The peeked message is: ${peekMessagesResponse.peekedMessageItems[0].messageText}`);

Bearbeta ett meddelande

Meddelanden bearbetas i två steg.

Anropa först queueClient.receiveMessages(). Detta gör meddelandena osynliga för andra kodläsningsmeddelanden från den här kön under en standardperiod på 30 sekunder.
När bearbetningen av ett meddelande är klar anropar du queueClient.deleteMessage() med meddelandets popReceipt.

Om koden inte kan bearbeta ett meddelande på grund av maskinvaru- eller programvarufel säkerställer den här tvåstegsprocessen att en annan instans av koden kan få samma meddelande och försöka igen.

import { QueueServiceClient } from "@azure/storage-queue";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  new DefaultAzureCredential(),
);

const queueName = "<valid queue name>";
const queueClient = queueServiceClient.getQueueClient(queueName);
const response = await queueClient.receiveMessages();
if (response.receivedMessageItems.length === 1) {
  const receivedMessageItem = response.receivedMessageItems[0];
  console.log(`Processing & deleting message with content: ${receivedMessageItem.messageText}`);
  const deleteMessageResponse = await queueClient.deleteMessage(
    receivedMessageItem.messageId,
    receivedMessageItem.popReceipt,
  );
  console.log(
    `Delete message successfully, service assigned request Id: ${deleteMessageResponse.requestId}`,
  );
}

Ta bort en kö

import { QueueServiceClient } from "@azure/storage-queue";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  new DefaultAzureCredential(),
);

const queueName = "<valid queue name>";
const queueClient = queueServiceClient.getQueueClient(queueName);
const deleteQueueResponse = await queueClient.delete();
console.log(
  `Deleted queue successfully, service assigned request Id: ${deleteQueueResponse.requestId}`,
);

Ett fullständigt exempel på enkla QueueServiceClient scenarier finns på samples/v12/typescript/src/queueClient.ts.

Troubleshooting

Aktivering av loggning kan hjälpa dig att hitta användbar information om fel. Om du vill se en logg med HTTP-begäranden och svar anger du AZURE_LOG_LEVEL miljövariabeln till info. Du kan också aktivera loggning vid körning genom att anropa setLogLevel i @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Nästa steg

Fler kodexempel

Contributing

Om du vill bidra till det här biblioteket kan du läsa bidragsguide för att lära dig mer om hur du skapar och testar koden.

Mer information om hur du konfigurerar testmiljön för lagringsbibliotek finns i storage specific guide .

Feedback

Var den här sidan till hjälp?