Azure Storage Queue-clientbibliotheek voor JavaScript - versie 12.23.0

Azure Storage Queue biedt cloudberichten tussen toepassingsonderdelen. Bij het ontwerpen van toepassingen voor schaal worden toepassingsonderdelen vaak losgekoppeld, zodat ze onafhankelijk kunnen worden geschaald. Queue Storage levert asynchrone berichten voor communicatie tussen toepassingsonderdelen, ongeacht of deze worden uitgevoerd in de cloud, op het bureaublad, op een on-premises server of op een mobiel apparaat. Queue Storage biedt ook ondersteuning voor het beheren van asynchrone taken en het bouwen van proceswerkstromen.

Dit project biedt een clientbibliotheek in JavaScript waarmee u de Azure Storage Queue-service eenvoudig kunt gebruiken.

Gebruik de clientbibliotheken in dit pakket om:

• Eigenschappen van wachtrijservice ophalen/instellen
• Wachtrijen maken/weergeven/verwijderen
• Wachtrijberichten verzenden/ontvangen/bekijken/wissen/bijwerken/verwijderen

Sleutelkoppelingen:

• broncode
• package (npm)
• API-referentiedocumentatie
• productdocumentatie
• voorbeelden
• REST API's van Azure Storage Queue

Slag

Momenteel ondersteunde omgevingen

• LTS-versies van Node.js
• Nieuwste versies van Safari, Chrome, Edge en Firefox.

Zie ons ondersteuningsbeleid voor meer informatie.

Voorwaarden

• Een Azure-abonnement
• Een -opslagaccount

Het pakket installeren

De voorkeursmethode voor het installeren van de Azure Storage Queue-clientbibliotheek voor JavaScript is het gebruik van npm-pakketbeheer. Typ het volgende in een terminalvenster:

npm install @azure/storage-queue

De client verifiëren

Azure Storage ondersteunt verschillende manieren om te verifiëren. Als u wilt communiceren met de Azure Queue Storage-service, moet u bijvoorbeeld een exemplaar van een Storage-client maken, QueueServiceClient of QueueClient. Zie voorbeelden voor het maken van de QueueServiceClient voor meer informatie over verificatie.

• Azure Active Directory-
• gedeelde sleutel
• handtekeningen voor gedeelde toegang

Azure Active Directory

De Azure Queue Storage-service ondersteunt het gebruik van Azure Active Directory voor het verifiëren van aanvragen voor de BIJBEHORENDE API's. Het @azure/identity-pakket biedt verschillende referentietypen die uw toepassing hiervoor kan gebruiken. Raadpleeg de LEESMIJ voor @azure/identity voor meer informatie en voorbeelden om u op weg te helpen.

Compatibiliteit

Deze bibliotheek is compatibel met Node.js en browsers en gevalideerd op basis van LTS-Node.js versies (>=8.16.0) en de nieuwste versies van Chrome, Firefox en Edge.

Webmedewerkers

Voor deze bibliotheek moeten bepaalde DOM-objecten wereldwijd beschikbaar zijn wanneer ze worden gebruikt in de browser, die webmedewerkers niet standaard beschikbaar maken. U moet deze invullen om deze bibliotheek in webwerkrollen te laten werken.

Raadpleeg onze documentatie voor het gebruik van Azure SDK voor JS in Web Workers voor meer informatie

Deze bibliotheek is afhankelijk van de volgende DOM-API's waarvoor externe polyfills moeten worden geladen wanneer ze worden gebruikt in webwerkrollen:

• document
• DOMParser
• Node
• XMLSerializer

Verschillen tussen Node.js en browsers

Er zijn verschillen tussen Node.js en runtime van browsers. Wanneer u aan de slag gaat met deze bibliotheek, moet u letten op API's of klassen die zijn gemarkeerd met 'ONLY AVAILABLE IN NODE.JS RUNTIME' of 'ONLY AVAILABLE IN BROWSERS'.

De volgende functies, interfaces, klassen of functies zijn alleen beschikbaar in Node.js

• Autorisatie van gedeelde sleutels op basis van accountnaam en accountsleutel
  • StorageSharedKeyCredential
• Sas-generatie (Shared Access Signature)
  • generateAccountSASQueryParameters()
  • generateQueueSASQueryParameters()

JavaScript-bundel

Als u deze clientbibliotheek in de browser wilt gebruiken, moet u eerst een bundelaar gebruiken. Raadpleeg onze bundeldocumentatievoor meer informatie over hoe u dit doet.

CORS

U moet CORS-regels (Cross-Origin Resource Sharing) instellen regels voor uw opslagaccount als u voor browsers moet ontwikkelen. Ga naar Azure Portal en Azure Storage Explorer, zoek uw opslagaccount, maak nieuwe CORS-regels voor blob/queue/file/table-service(s).

U kunt bijvoorbeeld de volgende CORS-instellingen maken voor foutopsporing. Maar pas de instellingen zorgvuldig aan op basis van uw vereisten in de productieomgeving.

• Toegestane oorsprongen: *
• Toegestane werkwoorden: DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
• Toegestane headers: *
• Weergegeven headers: *
• Maximale leeftijd (seconden): 86400

Sleutelbegrippen

Een wachtrij is een gegevensarchief in een Azure Storage Queue-serviceaccount voor het verzenden/ontvangen van berichten tussen verbonden clients.

Belangrijke gegevenstypen in onze bibliotheek met betrekking tot deze services zijn:

• Een QueueServiceClient vertegenwoordigt een verbinding (via een URL) naar een bepaald opslagaccount in de Azure Storage Queue-service en biedt API's voor het bewerken van de wachtrijen. Deze wordt geverifieerd bij de service en kan worden gebruikt voor het maken van QueueClient objecten, evenals het maken, verwijderen, vermelden van wachtrijen van de service.
• Een QueueClient vertegenwoordigt één wachtrij in het opslagaccount. Het kan worden gebruikt om de berichten van de wachtrij te bewerken, bijvoorbeeld om berichten in de wachtrij te verzenden, te ontvangen en te bekijken.

Voorbeelden

Het pakket importeren

Als u de clients wilt gebruiken, importeert u het pakket in uw bestand:

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

U kunt ook selectief alleen de typen importeren die u nodig hebt:

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

De wachtrijserviceclient maken

De QueueServiceClient vereist een URL naar de wachtrijservice en een toegangsreferentie. Het accepteert desgewenst ook bepaalde instellingen in de parameter options.

met DefaultAzureCredential uit @azure/identity pakket

Aanbevolen manier om een QueueServiceClient te instantiëren

Installatie : Naslaginformatie - Toegang tot blobs en wachtrijen autoriseren met Azure Active Directory vanuit een clienttoepassing - /azure/storage/common/storage-auth-aad-app

• Een nieuwe AAD-toepassing registreren en machtigingen verlenen voor toegang tot Azure Storage namens de aangemelde gebruiker

  • Een nieuwe toepassing registreren in Azure Active Directory (in azure-portal) - /azure/active-directory/develop/quickstart-register-app
  • Selecteer Add a permission in de sectie API permissions en kies Microsoft APIs.
  • Kies Azure Storage en schakel het selectievakje naast user_impersonation in en klik vervolgens op Add permissions. Hierdoor heeft de toepassing namens de aangemelde gebruiker toegang tot Azure Storage.

• Toegang verlenen tot Azure Storage Queue-gegevens met RBAC in azure Portal

  • RBAC-rollen voor blobs en wachtrijen : /azure/storage/common/storage-auth-aad-rbac-portal.
  • Ga in azure Portal naar uw opslagaccount en wijs rol Inzender voor opslagwachtrijgegevens toe aan de geregistreerde AAD-toepassing vanaf Access control (IAM) tabblad (in de linkernavigatiebalk van uw opslagaccount in azure-portal).

• Omgeving instellen voor het voorbeeld

  • Noteer op de overzichtspagina van uw AAD-toepassing de CLIENT ID en TENANT ID. Maak op het tabblad Certificaten & Geheimen een geheim en noteer dat.
  • Zorg ervoor dat u AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET als omgevingsvariabelen hebt om het voorbeeld uit te voeren (kan gebruikmaken van 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
);

[Opmerking: bovenstaande stappen zijn alleen bedoeld voor Node.js]

verbindingsreeks gebruiken

U kunt ook een QueueServiceClient maken met behulp van de statische methode fromConnectionString() met de volledige verbindingsreeks als argument. (De verbindingsreeks kan worden verkregen via azure Portal.) [ALLEEN BESCHIKBAAR IN NODE.JS RUNTIME]

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

const connStr = "<connection string>";

const queueServiceClient = QueueServiceClient.fromConnectionString(connStr);

met StorageSharedKeyCredential

U kunt ook een QueueServiceClient maken met een StorageSharedKeyCredential door accountnaam en accountsleutel door te geven als argumenten. (De accountnaam en accountsleutel kunnen worden verkregen via de Azure-portal.) [ALLEEN BESCHIKBAAR IN 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
  }
);

met SAS-token

U kunt ook een QueueServiceClient maken met shared access signatures (SAS). U kunt het SAS-token ophalen uit azure Portal of er een genereren met behulp van 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}`
);

Wachtrijen in dit account weergeven

Gebruik QueueServiceClient.listQueues() functie om de wachtrijen te herhalen, met de nieuwe for-await-of syntaxis:

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

U kunt ook zonder 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();

Zie samples/v12/typescript/listQueues.tsvoor een volledig voorbeeld van het herhalen van wachtrijen.

Een nieuwe wachtrij maken

Gebruik QueueServiceClient.getQueueClient() functie om een nieuwe wachtrij te maken.

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

Een bericht naar de wachtrij verzenden

Gebruik sendMessage() om een bericht toe te voegen aan de wachtrij:

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

Een bericht bekijken

QueueClient.peekMessages() kunt u een of meer berichten voor de wachtrij bekijken. Met deze aanroep wordt niet voorkomen dat andere code toegang heeft tot bekeken berichten.

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

Een bericht verwerken

Berichten worden in twee stappen verwerkt.

• Bel eerst queueClient.receiveMessages(). Hierdoor zijn de berichten onzichtbaar voor andere code die berichten uit deze wachtrij lezen gedurende een standaardperiode van 30 seconden.
• Wanneer het verwerken van een bericht is voltooid, roept u queueClient.deleteMessage() aan met de popReceiptvan het bericht.

Als uw code een bericht niet kan verwerken vanwege hardware- of softwarefouten, zorgt dit proces in twee stappen ervoor dat een ander exemplaar van uw code hetzelfde bericht kan krijgen en het opnieuw kan proberen.

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

Een wachtrij verwijderen

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

Een volledig voorbeeld van eenvoudige QueueServiceClient scenario's bevindt zich in samples/v12/typescript/src/queueClient.ts.

Probleemoplossing

Het inschakelen van logboekregistratie kan helpen nuttige informatie over fouten te ontdekken. Als u een logboek met HTTP-aanvragen en -antwoorden wilt zien, stelt u de omgevingsvariabele AZURE_LOG_LEVEL in op info. U kunt logboekregistratie ook tijdens runtime inschakelen door setLogLevel aan te roepen in de @azure/logger:

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

setLogLevel("info");

Volgende stappen

Meer codevoorbeelden

• Queue Storage-voorbeelden
• Queue Storage-testcases

Bijdragen

Als u een bijdrage wilt leveren aan deze bibliotheek, leest u de gids voor bijdragen voor meer informatie over het bouwen en testen van de code.

Raadpleeg ook storage-specifieke handleiding voor aanvullende informatie over het instellen van de testomgeving voor opslagbibliotheken.