Azure Storage-Warteschlangenclientbibliothek für JavaScript– Version 12.17.0

Azure Storage Queue bietet Cloudmessaging zwischen Anwendungskomponenten. Bei der Entwicklung skalierbarer Anwendungen werden häufig einzelne Anwendungskomponenten entkoppelt, um eine unabhängige Skalierung zu ermöglichen. Queue Storage bietet asynchrones Messaging für die Kommunikation zwischen Anwendungskomponenten, egal ob diese in der Cloud, auf dem Desktop, auf einem lokalen Server oder einem mobilen Gerät ausgeführt werden. Queue Storage unterstützt auch die Verwaltung asynchroner Aufgaben und den Aufbau von Prozessworkflows.

Dieses Projekt stellt eine Clientbibliothek in JavaScript bereit, die die Nutzung des Azure Storage-Warteschlangendiensts erleichtert.

Verwenden Sie die Clientbibliotheken in diesem Paket für Folgendes:

• Abrufen/Festlegen von Warteschlangendiensteigenschaften
• Create/Auflisten/Löschen von Warteschlangen
• Senden/Empfangen/Peek/Löschen/Aktualisieren/Löschen von Warteschlangennachrichten

Wichtige Links:

• Quellcode
• Paket (npm)
• API-Referenzdokumentation
• Produktdokumentation
• Beispiele
• Azure Storage-Warteschlangen-REST-APIs

Erste Schritte

Die derzeitig unterstützten Umgebungen

• LTS-Versionen von Node.js
• Neueste Versionen von Safari, Chrome, Edge und Firefox.

Ausführlichere Informationen finden Sie in der Supportrichtlinie.

Voraussetzungen

• Ein Azure-Abonnement
• Ein Speicherkonto

Installieren des Pakets

Die bevorzugte Methode zum Installieren der Azure Storage-Warteschlangenclientbibliothek für JavaScript ist die Verwendung des npm-Paket-Managers. Geben Sie Folgendes in ein Terminalfenster ein:

npm install @azure/storage-queue

Authentifizieren des Clients

Azure Storage unterstützt mehrere Authentifizierungsmethoden. Um mit dem Azure Queue Storage-Dienst zu interagieren, müssen Sie beispielsweise eine instance eines Speicherclients QueueServiceClientQueueClient erstellen. Weitere Informationen zur Authentifizierung finden Sie in den Beispielen zum Erstellen von QueueServiceClient .

• Azure Active Directory
• Gemeinsam verwendeter Schlüssel
• Shared Access Signatures

Azure Active Directory

Der Azure Queue Storage-Dienst unterstützt die Verwendung von Azure Active Directory zum Authentifizieren von Anforderungen an seine APIs. Das @azure/identity Paket bietet eine Vielzahl von Anmeldeinformationstypen, die Ihre Anwendung dazu verwenden kann. Weitere Informationen und Beispiele für @azure/identity die ersten Schritte finden Sie in der INFODATEI.

Kompatibilität

Diese Bibliothek ist mit Node.js und Browsern kompatibel und mit LTS Node.js Versionen (>=8.16.0) und den neuesten Versionen von Chrome, Firefox und Edge überprüft.

Web Worker

Diese Bibliothek erfordert, dass bestimmte DOM-Objekte global verfügbar sind, wenn sie im Browser verwendet werden, was Webworker standardmäßig nicht verfügbar machen. Sie müssen diese polyausfüllen, damit diese Bibliothek in Web-Workern funktioniert.

Weitere Informationen finden Sie in unserer Dokumentation zur Verwendung des Azure SDK für JS in Web Workern.

Diese Bibliothek hängt von den folgenden DOM-APIs ab, die externe Polyfills laden müssen, wenn sie in Web-Workern verwendet werden:

• document
• DOMParser
• Node
• XMLSerializer

Unterschiede zwischen Node.js und Browsern

Es gibt Unterschiede zwischen Node.js und Browserlaufzeit. Achten Sie bei den ersten Schritten mit dieser Bibliothek auf APIs oder Klassen, die mit "ONLY AVAILABLE IN NODE.JS RUNTIME" oder "ONLY AVAILABLE IN BROWSERS" gekennzeichnet sind.

Die folgenden Features, Schnittstellen, Klassen oder Funktionen sind nur in Node.js

• Autorisierung mit gemeinsam genutzten Schlüsseln basierend auf Kontoname und Kontoschlüssel
  • StorageSharedKeyCredential
• Generierung von Shared Access Signature (SAS)
  • generateAccountSASQueryParameters()
  • generateQueueSASQueryParameters()

JavaScript-Paket

Um diese Clientbibliothek im Browser verwenden zu können, müssen Sie zunächst einen Bundler verwenden. Ausführliche Informationen dazu finden Sie in unserer Bündelungsdokumentation.

CORS

Sie müssen CORS-Regeln (Cross-Origin Resource Sharing) für Ihr Speicherkonto einrichten, wenn Sie für Browser entwickeln müssen. Wechseln Sie zu Azure-Portal und Azure Storage-Explorer, suchen Sie Ihr Speicherkonto, und erstellen Sie neue CORS-Regeln für blob/queue/file/table-Dienste.

Sie können beispielsweise die folgenden CORS-Einstellungen für das Debuggen erstellen. Passen Sie die Einstellungen jedoch sorgfältig an Ihre Anforderungen in der Produktionsumgebung an.

• Zulässige Ursprünge: *
• Zulässige Verben: DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
• Zulässige Header: *
• Verfügbar gemachte Header: *
• Maximales Alter (Sekunden): 86400

Wichtige Begriffe

Eine Warteschlange ist ein Datenspeicher innerhalb eines Azure Storage-Warteschlangendienstkontos zum Senden/Empfangen von Nachrichten zwischen verbundenen Clients.

Die wichtigsten Datentypen in unserer Bibliothek im Zusammenhang mit diesen Diensten sind:

• Ein QueueServiceClient stellt eine Verbindung (über eine URL) mit einem bestimmten Speicherkonto im Azure Storage-Warteschlangendienst dar und stellt APIs zum Bearbeiten der zugehörigen Warteschlangen bereit. Sie wird beim Dienst authentifiziert und kann zum Erstellen QueueClient von Objekten sowie zum Erstellen, Löschen und Auflisten von Warteschlangen aus dem Dienst verwendet werden.
• Ein QueueClient stellt eine einzelne Warteschlange im Speicherkonto dar. Es kann verwendet werden, um die Nachrichten der Warteschlange zu bearbeiten, z. B. zum Senden, Empfangen und Einsehen von Nachrichten in der Warteschlange.

Beispiele

Importieren des Pakets

Um die Clients zu verwenden, importieren Sie das Paket in Ihre Datei:

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

Alternativ können Sie selektiv nur die Typen importieren, die Sie benötigen:

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

Erstellen des Warteschlangendienstclients

Die QueueServiceClient erfordert eine URL für den Warteschlangendienst und eine Zugriffsanmeldeinformation. Optional werden auch einige Einstellungen im options Parameter akzeptiert.

mit DefaultAzureCredential from-Paket @azure/identity

Empfohlene Methode zum Instanziieren eines QueueServiceClient

Setup: Referenz: Autorisieren des Zugriffs auf Blobs und Warteschlangen mit Azure Active Directory über eine Clientanwendung – /azure/storage/common/storage-auth-aad-app

• Registrieren einer neuen AAD-Anwendung und Erteilen von Berechtigungen für den Zugriff auf Azure Storage im Namen des angemeldeten Benutzers

  • Registrieren einer neuen Anwendung in Azure Active Directory (im Azure-Portal): /azure/active-directory/develop/quickstart-register-app
  • Wählen Sie Add a permission im Abschnitt ausAPI permissions, und wählen Sie ausMicrosoft APIs.
  • Aktivieren Sie Azure Storage das Kontrollkästchen neben , user_impersonation und klicken Sie dann auf Add permissions. Dadurch kann die Anwendung im Namen des angemeldeten Benutzers auf Azure Storage zugreifen.

• Gewähren des Zugriffs auf Azure Storage-Warteschlangendaten mit RBAC im Azure-Portal

  • RBAC-Rollen für Blobs und Warteschlangen: /azure/storage/common/storage-auth-aad-rbac-portal.
  • Navigieren Sie im Azure-Portal zu Ihrem Speicherkonto, und weisen Sie der registrierten AAD-Anwendung Access control (IAM) über die Registerkarte (in der linken Navigationsleiste Ihres Speicherkontos im Azure-Portal) die Rolle Mitwirkender an Speicherwarteschlangendaten zu.

• Umgebungseinrichtung für das Beispiel

  • Notieren Sie sich auf der Übersichtsseite Ihrer AAD-Anwendung die CLIENT ID - und TENANT ID- . Erstellen Sie auf der Registerkarte "Zertifikate & Geheimnisse" ein Geheimnis, und notieren Sie sich das.
  • Stellen Sie sicher, dass Sie über , AZURE_CLIENT_IDAZURE_CLIENT_SECRET als Umgebungsvariablen verfügenAZURE_TENANT_ID, um das Beispiel erfolgreich auszuführen (kann process.env nutzen).

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

[Hinweis: Die obigen Schritte sind nur für Node.js]

Verwenden von Verbindungszeichenfolge

Alternativ können Sie eine QueueServiceClient instanziieren, indem Sie die fromConnectionString() statische Methode mit dem vollständigen Verbindungszeichenfolge als Argument verwenden. (Die Verbindungszeichenfolge kann über das Azure-Portal abgerufen werden.) [NUR IN NODE.JS RUNTIME VERFÜGBAR]

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

const connStr = "<connection string>";

const queueServiceClient = QueueServiceClient.fromConnectionString(connStr);

Mit StorageSharedKeyCredential

Alternativ instanziieren Sie ein QueueServiceClient mit einem StorageSharedKeyCredential , indem Sie kontoname und account-key als Argumente übergeben. (Der Kontoname und der Kontoschlüssel können über das Azure-Portal abgerufen werden.) [NUR IN NODE.JS RUNTIME VERFÜGBAR]

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

mit SAS-Token

Außerdem können Sie ein QueueServiceClient mit einer SAS (Shared Access Signatures) instanziieren. Sie können das SAS-Token aus dem Azure-Portal abrufen oder mit generateAccountSASQueryParameters()generieren.

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

Auflisten von Warteschlangen in diesem Konto

Verwenden Sie QueueServiceClient.listQueues() die Funktion, um die Warteschlangen mit der neuen for-await-of Syntax zu durchlaufen:

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() {
  let iter1 = queueServiceClient.listQueues();
  let i = 1;
  for await (const item of iter1) {
    console.log(`Queue${i}: ${item.name}`);
    i++;
  }
}

main();

Alternativ ohne 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() {
  let 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();

Ein vollständiges Beispiel zum Durchlaufen von Warteschlangen finden Sie unter samples/v12/typescript/listQueues.ts.

Erstellen einer neuen Warteschlange

Verwenden Sie QueueServiceClient.getQueueClient() die Funktion, um eine neue Warteschlange zu erstellen.

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

Senden einer Nachricht an die Warteschlange

Verwenden Sie sendMessage() , um der Warteschlange eine Nachricht hinzuzufügen:

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

Einsehen einer Nachricht

QueueClient.peekMessages() ermöglicht das Anzeigen einer oder mehrerer Nachrichten vor der Warteschlange. Dieser Aufruf verhindert nicht, dass anderer Code auf eingesehene Nachrichten zugreift.

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

Verarbeiten einer Nachricht

Nachrichten werden in zwei Schritten verarbeitet.

• Rufen Sie zuerst auf queueClient.receiveMessages(). Dadurch werden die Nachrichten für anderen Code unsichtbar, der Nachrichten aus dieser Warteschlange für einen Standardzeitraum von 30 Sekunden liest.
• Wenn die Verarbeitung einer Nachricht abgeschlossen ist, rufen Sie queueClient.deleteMessage() mit der -Nachricht auf popReceipt.

Wenn ihr Code eine Nachricht aufgrund eines Hardware- oder Softwarefehlers nicht verarbeiten kann, stellt dieser zweistufige Prozess sicher, dass ein anderer instance Ihres Codes dieselbe Nachricht erhalten und es erneut versuchen kann.

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

Löschen einer Warteschlange

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

Ein vollständiges Beispiel für einfache QueueServiceClient Szenarien finden Sie unter samples/v12/typescript/src/queueClient.ts.

Problembehandlung

Die Aktivierung der Protokollierung kann hilfreiche Informationen über Fehler aufdecken. Um ein Protokoll von HTTP-Anforderungen und -Antworten anzuzeigen, legen Sie die Umgebungsvariable AZURE_LOG_LEVEL auf info fest. Alternativ kann die Protokollierung zur Laufzeit aktiviert werden, indem Sie setLogLevel in @azure/logger aufrufen:

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

setLogLevel("info");

Nächste Schritte

Weitere Codebeispiele

• Speicherbeispiele für Warteschlangen
• Warteschlangenspeichertestfälle

Mitwirken

Wenn Sie an dieser Bibliothek mitwirken möchten, lesen Sie die Anleitung für Mitwirkende, um mehr darüber zu erfahren, wie Sie den Code erstellen und testen können.

Weitere Informationen zum Einrichten der Testumgebung für Speicherbibliotheken finden Sie auch im Speicherspezifischen Leitfaden .