Klientská knihovna Fronta služby Azure Storage pro JavaScript – verze 12.23.0

Fronta azure Storage poskytuje cloudové zasílání zpráv mezi komponentami aplikace. Při navrhování aplikací pro škálování jsou komponenty aplikací často oddělené, aby se mohly škálovat nezávisle. Queue Storage poskytuje asynchronní zasílání zpráv pro komunikaci mezi komponentami aplikace, ať už běží v cloudu, na ploše, na místním serveru nebo na mobilním zařízení. Queue Storage také podporuje správu asynchronních úloh a vytváření pracovních toků procesů.

Tento projekt poskytuje klientskou knihovnu v JavaScriptu, která usnadňuje využívání služby Fronta služby Azure Storage.

Klientské knihovny v tomto balíčku slouží k:

• Získání nebo nastavení vlastností služby fronty
• Vytvoření, výpis nebo odstranění front
• Odesílání, příjem, náhled, vymazání, aktualizace, odstranění zpráv fronty

Klíčové odkazy:

• zdrojového kódu
• balíčku (npm)
• Referenční dokumentace k rozhraní API
• dokumentace k produktu
• ukázky
• rozhraní REST API fronty služby Azure Storage

Začínáme

Aktuálně podporovaná prostředí

• LTS verze Node.js
• Nejnovější verze Safari, Chrome, Edge a Firefox.

Další podrobnosti najdete v našich zásadách podpory .

Požadavky

• Předplatné Azure
• účtu úložiště

Instalace balíčku

Upřednostňovaným způsobem instalace klientské knihovny fronty služby Azure Storage pro JavaScript je použití správce balíčků npm. Do okna terminálu zadejte následující:

npm install @azure/storage-queue

Ověření klienta

Azure Storage podporuje několik způsobů ověřování. Pokud chcete pracovat se službou Azure Queue Storage, budete muset vytvořit instanci klienta služby Storage – například QueueServiceClient nebo QueueClient. Další informace o ověřování najdete v ukázkách pro vytvoření QueueServiceClient.

• Azure Active Directory
• sdílený klíč
• sdílených přístupových podpisů

Azure Active Directory

Služba Azure Queue Storage podporuje použití Azure Active Directory k ověřování požadavků na jeho rozhraní API. Balíček @azure/identity poskytuje řadu typů přihlašovacích údajů, které může vaše aplikace použít k tomu. Další podrobnosti a ukázky, které vám pomůžou začít, najdete v souboru README pro @azure/identity.

Kompatibilita

Tato knihovna je kompatibilní s Node.js a prohlížeči a ověřuje se ve verzích LTS Node.js (>=8.16.0) a nejnovějších verzích Chromu, Firefoxu a Edge.

Webové pracovní procesy

Tato knihovna vyžaduje, aby byly určité objekty MODELU DOM globálně dostupné při použití v prohlížeči, které webové pracovní procesy ve výchozím nastavení nedostupují. Pokud chcete, aby tato knihovna fungovala ve webových pracovních pracovních procesůch, budete je muset polyfillovat.

Další informace najdete v naší dokumentaci k používání sady Azure SDK pro JS ve webových pracovních

Tato knihovna závisí na následujících rozhraních API DOM, která potřebují externí polyfilly načtené při použití ve webových pracovních procesů:

• document
• DOMParser
• Node
• XMLSerializer

Rozdíly mezi Node.js a prohlížeči

Mezi modulem runtime Node.js a prohlížečů existují rozdíly. Při zahájení práce s touto knihovnou věnujte pozornost rozhraním API nebo třídám označeným "POUZE K DISPOZICI V NODE.JS RUNTIME" nebo "POUZE DOSTUPNÉ V PROHLÍŽEČÍCH".

Následující funkce, rozhraní, třídy nebo funkce jsou k dispozici pouze v Node.js

• Autorizace sdíleného klíče na základě názvu účtu a klíče účtu
  • StorageSharedKeyCredential
• Generování sdíleného přístupového podpisu (SAS)
  • generateAccountSASQueryParameters()
  • generateQueueSASQueryParameters()

JavaScript Bundle

Pokud chcete tuto klientskou knihovnu použít v prohlížeči, musíte nejprve použít bundler. Podrobnosti o tom, jak to udělat, najdete v naší dokumentaci sdružování.

CORS

Pokud potřebujete vyvíjet prohlížeče, musíte pro svůj účet úložiště nastavit sdílení prostředků mezi zdroji (CORS) pravidla. Přejděte na Azure Portal a Průzkumníka služby Azure Storage, vyhledejte svůj účet úložiště, vytvořte nová pravidla CORS pro služby blob, queue, file/table service.

Můžete například vytvořit následující nastavení CORS pro ladění. Přizpůsobte si ale nastavení pečlivě podle svých požadavků v produkčním prostředí.

• Povolené původy: *
• Povolené příkazy: DELETE, GET, HEAD, MERGE, POST, OPTIONS, PUT
• Povolené hlavičky: *
• Vystavené hlavičky: *
• Maximální stáří (sekundy): 86400

Klíčové koncepty

Fronta je úložiště dat v rámci účtu služby Fronta služby Azure Storage pro odesílání a přijímání zpráv mezi připojenými klienty.

Klíčové datové typy v naší knihovně související s těmito službami jsou:

• QueueServiceClient představuje připojení (prostřednictvím adresy URL) k danému účtu úložiště ve službě Fronta služby Azure Storage a poskytuje rozhraní API pro manipulaci s frontami. Ověřuje se ve službě a dá se použít k vytváření QueueClient objektů a také k vytváření, odstraňování a výpisu front ze služby.
• QueueClient představuje jednu frontu v účtu úložiště. Dá se použít k manipulaci se zprávami fronty, například k odesílání, příjmu a náhledu zpráv ve frontě.

Příklady

Import balíčku

Pokud chcete použít klienty, naimportujte balíček do souboru:

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

Alternativně selektivně importujte jenom ty typy, které potřebujete:

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

Vytvoření klienta frontové služby

QueueServiceClient vyžaduje adresu URL služby fronty a přihlašovací údaje pro přístup. Volitelně také přijímá některá nastavení v parametru options.

s DefaultAzureCredential z balíčku @azure/identity

Doporučený způsob vytvoření instance QueueServiceClient

Nastavení: Referenční informace – Autorizace přístupu k objektům blob a frontám pomocí Azure Active Directory z klientské aplikace – /azure/storage/common/storage-auth-aad-app

• Registrace nové aplikace AAD a udělení oprávnění pro přístup ke službě Azure Storage jménem přihlášeného uživatele

  • Registrace nové aplikace v Azure Active Directory (na webu azure-portal) – /azure/active-directory/develop/quickstart-register-app
  • V části API permissions vyberte Add a permission a zvolte Microsoft APIs.
  • Vyberte Azure Storage a zaškrtněte políčko vedle user_impersonation a potom klikněte na Add permissions. To by aplikaci umožnilo přístup ke službě Azure Storage jménem přihlášeného uživatele.

• Udělení přístupu k datům fronty služby Azure Storage pomocí RBAC na webu Azure Portal

  • Role RBAC pro objekty blob a fronty – /azure/storage/common/storage-auth-aad-rbac-portal.
  • Na webu Azure Portal přejděte do svého účtu úložiště a přiřaďte Roli Přispěvatel dat fronty služby Storage zaregistrované aplikaci AAD na kartě Access control (IAM) (na levém navigačním panelu vašeho účtu úložiště na webu Azure-Portal).

• Nastavení prostředí pro ukázku

  • Na stránce přehledu aplikace AAD si poznamenejte CLIENT ID a TENANT ID. Na kartě Certifikáty & Tajné kódy vytvořte tajný kód a poznamenejte si ho.
  • Ujistěte se, že máte AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET jako proměnné prostředí k úspěšnému spuštění ukázky (může využít 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
);

[Poznámka: Výše uvedené kroky jsou určené pouze pro Node.js]

pomocí připojovacího řetězce

Alternativně můžete vytvořit instanci QueueServiceClient pomocí fromConnectionString() statické metody s úplným připojovacím řetězcem jako argumentem. (Připojovací řetězec lze získat z webu Azure Portal.) [K DISPOZICI POUZE V NODE.JS RUNTIME]

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

const connStr = "<connection string>";

const queueServiceClient = QueueServiceClient.fromConnectionString(connStr);

s StorageSharedKeyCredential

Alternativně vytvoříte instanci QueueServiceClient s StorageSharedKeyCredential předáním názvu účtu a klíče účtu jako argumentů. (Název účtu a klíč účtu je možné získat z webu Azure Portal.) [K DISPOZICI POUZE V 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
  }
);

s tokenem SAS

Můžete také vytvořit instanci QueueServiceClient se sdílenými přístupovými podpisy (SAS). Token SAS můžete získat z webu Azure Portal nebo ho vygenerovat pomocí 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}`
);

Výpis front v tomto účtu

Pomocí funkce QueueServiceClient.listQueues() iterujte fronty s novou syntaxí 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 iter1 = queueServiceClient.listQueues();
  let i = 1;
  for await (const item of iter1) {
    console.log(`Queue${i}: ${item.name}`);
    i++;
  }
}

main();

Alternativně bez 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();

Kompletní ukázku iterace front najdete v tématu samples/v12/typescript/listQueues.ts.

Vytvoření nové fronty

K vytvoření nové fronty použijte funkci QueueServiceClient.getQueueClient().

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

Odeslání zprávy do fronty

K přidání zprávy do fronty použijte sendMessage():

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

Náhled zprávy

QueueClient.peekMessages() umožňuje zobrazení jedné nebo více zpráv před frontou. Toto volání nezabrání jinému kódu v přístupu k náhledovým zprávám.

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

Zpracování zprávy

Zprávy se zpracovávají ve dvou krocích.

• První volání queueClient.receiveMessages(). Díky tomu jsou zprávy neviditelné pro ostatní kódy, které čtou zprávy z této fronty po dobu 30 sekund.
• Při zpracování zprávy zavolejte queueClient.deleteMessage() pomocí popReceiptzprávy .

Pokud se vašemu kódu nepodaří zpracovat zprávu kvůli selhání hardwaru nebo softwaru, tento dvoustupňový proces zajistí, že další instance kódu může získat stejnou zprávu a zkusit to znovu.

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

Odstranění fronty

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

Úplný příklad jednoduchých scénářů QueueServiceClient je v samples/v12/typescript/src/queueClient.ts.

Řešení problémů

Povolení protokolování může pomoct odhalit užitečné informace o chybách. Pokud chcete zobrazit protokol požadavků a odpovědí HTTP, nastavte proměnnou prostředí AZURE_LOG_LEVEL na info. Případně můžete protokolování povolit za běhu voláním setLogLevel v @azure/logger:

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

setLogLevel("info");

Další kroky

Další ukázky kódu

• Ukázky Queue Storage
• testovací případy Queue Storage

Přispívající

Pokud chcete přispívat do této knihovny, přečtěte si průvodce přispívání a přečtěte si další informace o vytváření a testování kódu.

Další informace o nastavení testovacího prostředí pro knihovny úložiště najdete také v průvodci Storage.