Klientská knihovna fronty služby Azure Storage pro JavaScript – verze 12.17.0

Článek
05/13/2024

Fronta služby Azure Storage poskytuje cloudové zasílání zpráv mezi komponentami aplikace. Při navrhování aplikací pro škálování ve větším měřítku jsou jednotlivé součásti aplikací často nepropojené, aby je bylo možné škálovat nezávisle. Queue Storage zajišťuje asynchronní přenos zpráv pro komunikaci mezi součástmi aplikace bez ohledu na to, jestli běží v cloudu, na desktopu, na místním serveru nebo na mobilním zařízení. Queue Storage také podporuje správu asynchronních úloh a pracovní postupy procesů sestavování buildů.

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

Pomocí klientských knihoven v tomto balíčku:

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

Klíčové odkazy:

Začínáme

Aktuálně podporovaná prostředí

LtS verze Node.js
Nejnovější verze prohlížečů Safari, Chrome, Edge a Firefox.

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

Požadavky

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 – QueueServiceClient nebo QueueClient například . Další informace o ověřování najdete v QueueServiceClientukázkách pro vytvoření.

Azure Active Directory
Sdílený klíč
Sdílené přístupové podpisy

Azure Active Directory

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

Kompatibilita

Tato knihovna je kompatibilní s Node.js a prohlížeči a je ověřená ve verzích LTS Node.js (>=8.16.0) a nejnovějších verzích prohlížečů Chrome, Firefox a Edge.

Webové pracovní procesy

Tato knihovna vyžaduje, aby určité objekty MODELU DOM byly při použití v prohlížeči globálně dostupné, což webové pracovní procesy ve výchozím nastavení nezpřístupní. Aby tato knihovna fungovala ve webových pracovnící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 procesůch.

Tato knihovna závisí na následujících rozhraních API dom, která při použití ve webových pracovních procesů vyžadují načtení externích polyfillů:

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

Mezi modulem runtime Node.js a prohlížeče existují rozdíly. Když začínáte s touto knihovnou, věnujte pozornost rozhraním API nebo třídám označeným "POUZE K DISPOZICI V NODE.JS RUNTIME" nebo "K DISPOZICI POUZE 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žívat v prohlížeči, musíte nejprve použít nástroj bundler. Podrobnosti o tom, jak to udělat, najdete v naší dokumentaci k sdružování.

CORS

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

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í věk (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:

Představuje QueueServiceClient 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 jeho 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.
Představuje QueueClient jednu frontu v účtu úložiště. Dá se použít k manipulaci se zprávami fronty, například k odesílání, přijímání a náhledu zpráv ve frontě.

Příklady

Import balíčku

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

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

Případně můžete selektivně importovat pouze typy, které potřebujete:

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

Create klienta frontové služby

Vyžaduje QueueServiceClient 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 balíčkem `DefaultAzureCredential` z `@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 k 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
- API permissions V části 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 ke svému účtu úložiště a na kartě (v levém navigačním panelu vašeho účtu úložiště na webu azure-portal) přiřaďte zaregistrované aplikaci Access control (IAM) AAD roli Přispěvatel dat fronty úložiště.
Nastavení prostředí pro ukázku
- Na stránce přehledu vaší 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 pro úspěšné spuštění ukázky máte AZURE_TENANT_IDjako proměnné prostředí , AZURE_CLIENT_IDAZURE_CLIENT_SECRET (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é jenom pro Node.js.

pomocí připojovací řetězec

Alternativně můžete vytvořit QueueServiceClient instanci pomocí fromConnectionString() statické metody s úplným připojovací řetězec jako argumentem. (Připojovací řetězec můžete 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`

Případně můžete vytvořit instanci QueueServiceClient s argumentem StorageSharedKeyCredential account-name a account-key. (Název účtu a klíč účtu je možné získat z webu Azure Portal.) [K DISPOZICI POUZE V modulu runtime NODE.JS]

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 QueueServiceClient instanci 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

K iteraci front použijte QueueServiceClient.listQueues() funkci s novou for-await-of syntaxí:

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.

Create nové fronty

Pomocí QueueServiceClient.getQueueClient() funkce vytvořte novou frontu.

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

Slouží sendMessage() k přidání zprávy do 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);
  // 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 zobrazit jednu 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 budou zprávy neviditelné pro jiný kód, který čte zprávy z této fronty po výchozí dobu 30 sekund.
Po dokončení zpracování zprávy volejte queueClient.deleteMessage() se zprávou popReceipt.

Pokud se vašemu kódu nepodaří zpracovat zprávu kvůli selhání hardwaru nebo softwaru, tento dvoustupňový proces zajistí, že jiná instance vašeho 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ým příkladem jednoduchých QueueServiceClient scénářů je samples/v12/typescript/src/queueClient.ts.

Poradce při potížích

Povolení protokolování může pomoct odhalit užitečné informace o selháních. Pokud chcete zobrazit protokol požadavků a odpovědí HTTP, nastavte proměnnou AZURE_LOG_LEVEL prostředí na info. Případně je možné 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

Přispívání

Pokud chcete přispívat do této knihovny, přečtěte si prosím průvodce přispívání , kde se dozvíte více o tom, jak sestavit a otestovat kód.

Další informace o nastavení testovacího prostředí pro knihovny úložiště najdete také v příručce pro konkrétní úložiště.

Imprese

Sdílet prostřednictvím

Klientská knihovna fronty služby Azure Storage pro JavaScript – verze 12.17.0

Začínáme

Aktuálně podporovaná prostředí

Požadavky

Instalace balíčku

Ověření klienta

Azure Active Directory

Kompatibilita

Webové pracovní procesy

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

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

JavaScript Bundle

CORS

Klíčové koncepty

Příklady

Import balíčku

Create klienta frontové služby

s balíčkem `DefaultAzureCredential` z `@azure/identity`

pomocí připojovací řetězec

S `StorageSharedKeyCredential`

s tokenem SAS

Výpis front v tomto účtu

Create nové fronty

Odeslání zprávy do fronty

Náhled zprávy

Zpracování zprávy

Odstranění fronty

Poradce při potížích

Další kroky

Přispívání

Váš názor

Další materiály

Sdílet prostřednictvím

Klientská knihovna fronty služby Azure Storage pro JavaScript – verze 12.17.0

Začínáme

Aktuálně podporovaná prostředí

Požadavky

Instalace balíčku

Ověření klienta

Azure Active Directory

Kompatibilita

Webové pracovní procesy

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

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

JavaScript Bundle

CORS

Klíčové koncepty

Příklady

Import balíčku

Create klienta frontové služby

s balíčkem DefaultAzureCredential z @azure/identity

pomocí připojovací řetězec

S StorageSharedKeyCredential

s tokenem SAS

Výpis front v tomto účtu

Create nové fronty

Odeslání zprávy do fronty

Náhled zprávy

Zpracování zprávy

Odstranění fronty

Poradce při potížích

Další kroky

Přispívání

Váš názor

Další materiály

s balíčkem `DefaultAzureCredential` z `@azure/identity`

S `StorageSharedKeyCredential`