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

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:

• Källkod
• Paket (npm)
• API-referensdokumentation
• Produktdokumentation
• Exempel
• REST API:er för Azure Storage Queue

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.

Förutsättningar

• En Azure-prenumeration
• 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.

Kompatibilitet

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:

• document
• DOMParser
• Node
• XMLSerializer

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:

• En 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 ändra 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.
• En QueueClient representerar en enda 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.

Exempel

Importera paketet

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

const AzureStorageQueue = require("@azure/storage-queue");

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

const { QueueServiceClient, StorageSharedKeyCredential } = require("@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 – /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-portalen) – /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 – /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).

const { DefaultAzureCredential } = require("@azure/identity");
const { QueueServiceClient } = require("@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]

const { QueueServiceClient } = require("@azure/storage-queue");

const connStr = "<connection string>";

const queueServiceClient = QueueServiceClient.fromConnectionString(connStr);

med StorageSharedKeyCredential

Du kan också instansiera en QueueServiceClient med en StorageSharedKeyCredential genom att skicka kontonamn och kontonyckel som argument. (Kontonamnet och kontonyckeln kan hämtas från Azure-portalen.) [ENDAST TILLGÄNGLIGT I NODE.JS RUNTIME]

const { QueueServiceClient, StorageSharedKeyCredential } = require("@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
    telemetry: { value: "BasicSample/V11.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().

const { QueueServiceClient } = require("@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:

const { DefaultAzureCredential } = require("@azure/identity");
const { QueueServiceClient } = require("@azure/storage-queue");

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

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

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

main();

Alternativt utan for-await-of:

const { DefaultAzureCredential } = require("@azure/identity");
const { QueueServiceClient } = require("@azure/storage-queue");

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

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

async function main() {
  const iter2 = queueServiceClient.listQueues();
  let i = 1;
  let item = await iter2.next();
  while (!item.done) {
    console.log(`Queue ${i++}: ${item.value.name}`);
    item = await iter2.next();
  }
}

main();

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ö.

const { DefaultAzureCredential } = require("@azure/identity");
const { QueueServiceClient } = require("@azure/storage-queue");

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

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

const queueName = "<valid queue name>";

async function main() {
  const queueClient = queueServiceClient.getQueueClient(queueName);
  const createQueueResponse = await queueClient.create();
  console.log(
    `Created queue ${queueName} successfully, service assigned request Id: ${createQueueResponse.requestId}`
  );
}

main();

Skicka ett meddelande till kön

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

const { DefaultAzureCredential } = require("@azure/identity");
const { QueueServiceClient } = require("@azure/storage-queue");

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

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

const queueName = "<valid queue name>";

async function main() {
  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}`
  );
}

main();

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.

const { DefaultAzureCredential } = require("@azure/identity");
const { QueueServiceClient } = require("@azure/storage-queue");

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

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

const queueName = "<valid queue name>";

async function main() {
  const queueClient = queueServiceClient.getQueueClient(queueName);
  const peekMessagesResponse = await queueClient.peekMessages();
  console.log(`The peeked message is: ${peekMessagesResponse.peekedMessageItems[0].messageText}`);
}

main();

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.

const { DefaultAzureCredential } = require("@azure/identity");
const { QueueServiceClient } = require("@azure/storage-queue");

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

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

const queueName = "<valid queue name>";

async function main() {
  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}`
    );
  }
}

main();

Ta bort en kö

const { DefaultAzureCredential } = require("@azure/identity");
const { QueueServiceClient } = require("@azure/storage-queue");

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

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

const queueName = "<valid queue name>";

async function main() {
  const queueClient = queueServiceClient.getQueueClient(queueName);
  const deleteQueueResponse = await queueClient.delete();
  console.log(
    `Deleted queue successfully, service assigned request Id: ${deleteQueueResponse.requestId}`
  );
}

main();

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

Felsökning

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:

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

Nästa steg

Fler kodexempel

• Queue Storage-exempel
• testfall för kölagring

Bidragande

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 .