Azure Storage Queue-Clientbibliothek für JavaScript – Version 12.25.0

Artikel
11/20/2024

Azure Storage Queue bietet Cloud-Messaging zwischen Anwendungskomponenten. Beim Entwerfen von Anwendungen für die Skalierung werden Anwendungskomponenten häufig entkoppelt, sodass sie unabhängig voneinander skaliert werden können. Der Warteschlangenspeicher liefert asynchrones Messaging für die Kommunikation zwischen Anwendungskomponenten, unabhängig davon, ob sie in der Cloud, auf dem Desktop, auf einem lokalen Server oder auf einem mobilen Gerät ausgeführt werden. Der Warteschlangenspeicher unterstützt auch die Verwaltung asynchroner Aufgaben und das Erstellen von Prozessarbeitsabläufen.

Dieses Projekt stellt eine Clientbibliothek in JavaScript bereit, die das Verwenden des Azure Storage Queue-Diensts erleichtert.

Verwenden Sie die Clientbibliotheken in diesem Paket, um:

Abrufen/Festlegen von Warteschlangendiensteigenschaften
Erstellen/Listen-/Löschen von Warteschlangen
Senden/Empfangen/Vorschau/Löschen/Aktualisieren/Löschen von Warteschlangennachrichten

Wichtige Links:

Erste Schritte

Derzeit unterstützte Umgebungen

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

Weitere Informationen finden Sie in unserer Supportrichtlinie.

Voraussetzungen

Ein Azure-Abonnement
Ein Speicherkonto

Installieren des Pakets

Die bevorzugte Methode zum Installieren der Azure Storage Queue-Clientbibliothek 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 Möglichkeiten zur Authentifizierung. Um mit dem Azure Queue Storage-Dienst zu interagieren, müssen Sie beispielsweise eine Instanz eines Speicherclients erstellen – QueueServiceClient oder QueueClient. Weitere Informationen zur Authentifizierung finden Sie in Beispielen zum Erstellen des QueueServiceClient.

Azure Active Directory-
freigegebenen Schlüssel
Freigegebene Zugriffssignaturen

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 verwenden kann, um dies zu tun. Weitere Details und Beispiele für die ersten Schritte finden Sie in der README für @azure/identity.

Kompatibilität

Diese Bibliothek ist mit Node.js und Browsern kompatibel und wird 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, die Web-Worker 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 Workers

Diese Bibliothek hängt von den folgenden DOM-APIs ab, die externe Polyfills benötigen, die bei Verwendung in Web-Workern geladen werden:

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 "NUR IN NODE.JS RUNTIME VERFÜGBAR" gekennzeichnet sind, oder "NUR IN BROWSERN VERFÜGBAR".

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

Gemeinsame Schlüsselautorisierung basierend auf Kontoname und Kontoschlüssel
- StorageSharedKeyCredential
Generierung von Shared Access Signature(SAS)
- generateAccountSASQueryParameters()
- generateQueueSASQueryParameters()

JavaScript-Bündel

Um diese Clientbibliothek im Browser zu verwenden, müssen Sie zuerst einen Bundler verwenden. Ausführliche Informationen dazu finden Sie in unserer Bündelungsdokumentation.

CORS

Sie müssen Cross-Origin Resource Sharing (CORS) Regeln 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, erstellen Sie neue CORS-Regeln für blob/queue/file/table service(s).

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

Zulässige Ursprünge: *
Zulässige Verben: DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
Zulässige Kopfzeilen: *
Verfügbar gemachte Kopfzeilen: *
Höchstalter (Sekunden): 86400

Schlüsselkonzepte

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

Wichtige 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 Queue-Dienst dar und stellt APIs zum Bearbeiten seiner Warteschlangen bereit. Sie wird beim Dienst authentifiziert und kann zum Erstellen QueueClient Objekte sowie zum Erstellen, Löschen, Listenwarteschlangen aus dem Dienst verwendet werden.
Ein QueueClient stellt eine einzelne Warteschlange im Speicherkonto dar. Sie kann verwendet werden, um die Nachrichten der Warteschlange zu bearbeiten, z. B. zum Senden, Empfangen und Anzeigen 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 nur die benötigten Typen selektiv importieren:

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

Erstellen des Warteschlangendienstclients

Für die QueueServiceClient ist eine URL zum Warteschlangendienst und eine Zugriffsanmeldeinformationen erforderlich. Sie akzeptiert optional auch einige Einstellungen im options-Parameter.

mit `DefaultAzureCredential` aus `@azure/identity` Paket

Empfohlene Methode zum Instanziieren eines QueueServiceClient

Setup: Referenz – Autorisieren des Zugriffs auf Blobs und Warteschlangen mit Azure Active Directory aus einer 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 im Azure Active Directory(im Azure-Portal) – /azure/active-directory/develop/quickstart-register-app
- Wählen Sie im Abschnitt API permissionsAdd a permission aus, und wählen Sie Microsoft APIsaus.
- Wählen Sie Azure Storage aus, und aktivieren Sie 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 Queue-Daten mit RBAC im Azure-Portal
- RBAC-Rollen für Blobs und Warteschlangen – /azure/storage/common/storage-auth-aad-rbac-portal.
- Wechseln Sie im Azure-Portal zu Ihrem Speicherkonto, und weisen Sie der registrierten AAD-Anwendung Rolle Speicherwarteschlangendatenmitwirkenden von Registerkarte zu (in der linken Navigationsleiste Ihres Speicherkontos im Azure-Portal).
Umgebungssetup 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 & Geheime Schlüssel" einen geheimen Schlüssel, und notieren Sie sich dies unten.
- Stellen Sie sicher, dass Sie über AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET als Umgebungsvariablen verfügen, 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 - Oben aufgeführte Schritte sind nur für Node.js]

verwenden der Verbindungszeichenfolge

Alternativ können Sie eine QueueServiceClient mithilfe der fromConnectionString() statischen Methode mit der vollständigen Verbindungszeichenfolge als Argument instanziieren. (Die Verbindungszeichenfolge kann aus dem 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 eine QueueServiceClient mit einem StorageSharedKeyCredential, indem Sie Kontoname und Kontoschlüssel 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 eine QueueServiceClient mit einer freigegebenen Zugriffssignatur (SAS) instanziieren. Sie können das SAS-Token aus dem Azure-Portal abrufen oder mithilfe von 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}`
);

Listen von Warteschlangen in diesem Konto

Verwenden Sie QueueServiceClient.listQueues() 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() {
  const 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() {
  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();

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

Erstellen einer neuen Warteschlange

Verwenden Sie QueueServiceClient.getQueueClient() 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();

Vorschau einer Nachricht

QueueClient.peekMessages() ermöglicht das Betrachten einer oder mehrerer Nachrichten vor der Warteschlange. Dieser Aufruf verhindert nicht, dass anderer Code auf vorschauierte 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.

Erster Anruf queueClient.receiveMessages(). Dadurch werden die Nachrichten für andere Codelesenachrichten aus dieser Warteschlange für einen Standardzeitraum von 30 Sekunden unsichtbar.
Wenn die Verarbeitung einer Nachricht abgeschlossen ist, rufen Sie queueClient.deleteMessage() mit der popReceiptder Nachricht auf.

Wenn ihr Code aufgrund von Hardware- oder Softwarefehlern keine Nachricht verarbeitet, stellt dieser zweistufige Prozess sicher, dass eine andere Instanz des Codes dieselbe Nachricht abrufen 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.

Fehlerbehebung

Das Aktivieren der Protokollierung kann hilfreiche Informationen zu Fehlern aufdecken. Um ein Protokoll von HTTP-Anforderungen und -Antworten anzuzeigen, legen Sie die AZURE_LOG_LEVEL Umgebungsvariable auf infofest. Alternativ kann die Protokollierung zur Laufzeit durch Aufrufen von setLogLevel im @azure/loggeraktiviert werden:

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

setLogLevel("info");

Nächste Schritte

Weitere Codebeispiele

- für Warteschlangenspeicherbeispiele

Beitragend

Wenn Sie an dieser Bibliothek mitwirken möchten, lesen Sie bitte den mitwirkenden Leitfaden, um mehr über das Erstellen und Testen des Codes zu erfahren.

Weitere Informationen zum Einrichten der Testumgebung für Speicherbibliotheken finden Sie auch in speicherspezifischen Leitfaden.

Aufrufe

Freigeben über

Azure Storage Queue-Clientbibliothek für JavaScript – Version 12.25.0

Erste Schritte

Derzeit unterstützte Umgebungen

Voraussetzungen

Installieren des Pakets

Authentifizieren des Clients

Azure Active Directory

Kompatibilität

Web Worker

Unterschiede zwischen Node.js und Browsern

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

JavaScript-Bündel

CORS

Schlüsselkonzepte

Beispiele

Importieren des Pakets

Erstellen des Warteschlangendienstclients

mit `DefaultAzureCredential` aus `@azure/identity` Paket

verwenden der Verbindungszeichenfolge

mit `StorageSharedKeyCredential`

mit SAS-Token

Listen von Warteschlangen in diesem Konto

Erstellen einer neuen Warteschlange

Senden einer Nachricht an die Warteschlange

Vorschau einer Nachricht

Verarbeiten einer Nachricht

Löschen einer Warteschlange

Fehlerbehebung

Nächste Schritte

Beitragend

Zusätzliche Ressourcen

Freigeben über

Azure Storage Queue-Clientbibliothek für JavaScript – Version 12.25.0

Erste Schritte

Derzeit unterstützte Umgebungen

Voraussetzungen

Installieren des Pakets

Authentifizieren des Clients

Azure Active Directory

Kompatibilität

Web Worker

Unterschiede zwischen Node.js und Browsern

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

JavaScript-Bündel

CORS

Schlüsselkonzepte

Beispiele

Importieren des Pakets

Erstellen des Warteschlangendienstclients

mit DefaultAzureCredential aus @azure/identity Paket

verwenden der Verbindungszeichenfolge

mit StorageSharedKeyCredential

mit SAS-Token

Listen von Warteschlangen in diesem Konto

Erstellen einer neuen Warteschlange

Senden einer Nachricht an die Warteschlange

Vorschau einer Nachricht

Verarbeiten einer Nachricht

Löschen einer Warteschlange

Fehlerbehebung

Nächste Schritte

Beitragend

Zusätzliche Ressourcen

mit `DefaultAzureCredential` aus `@azure/identity` Paket

mit `StorageSharedKeyCredential`