Biblioteka klienta kolejki usługi Azure Storage dla języka JavaScript — wersja 12.25.0

Kolejka usługi Azure Storage zapewnia obsługę komunikatów w chmurze między składnikami aplikacji. W projektowaniu aplikacji na potrzeby skalowania składniki aplikacji są często oddzielone, dzięki czemu można je skalować niezależnie. Usługa Queue Storage dostarcza asynchroniczne komunikaty na potrzeby komunikacji między składnikami aplikacji, niezależnie od tego, czy są one uruchomione w chmurze, na pulpicie, na serwerze lokalnym, czy na urządzeniu przenośnym. Usługa Queue Storage obsługuje również zarządzanie zadaniami asynchronicznymi i przepływami pracy procesu tworzenia.

Ten projekt udostępnia bibliotekę klienta w języku JavaScript, która ułatwia korzystanie z usługi Azure Storage Queue.

Użyj bibliotek klienckich w tym pakiecie, aby:

• Pobieranie/ustawianie właściwości usługi kolejki
• Tworzenie/wyświetlanie/usuwanie kolejek
• Wysyłanie/odbieranie/podgląd/czyszczenie/aktualizowanie/usuwanie komunikatów kolejki

Kluczowe linki:

• Kod źródłowy
• pakiet (npm)
• Dokumentacja referencyjna interfejsu API
• dokumentacja produktu
• Samples
• interfejsy API REST kolejki usługi Azure Storage

Wprowadzenie

Obecnie obsługiwane środowiska

• wersje Node.js LTS
• Najnowsze wersje przeglądarek Safari, Chrome, Edge i Firefox.

Aby uzyskać więcej informacji, zobacz nasze zasad pomocy technicznej.

Warunki wstępne

• subskrypcji platformy Azure
• Konto magazynu

Instalowanie pakietu

Preferowanym sposobem zainstalowania biblioteki klienta kolejki usługi Azure Storage dla języka JavaScript jest użycie menedżera pakietów npm. Wpisz następujące polecenie w oknie terminalu:

npm install @azure/storage-queue

Uwierzytelnianie klienta

Usługa Azure Storage obsługuje kilka sposobów uwierzytelniania. Aby móc korzystać z usługi Azure Queue Storage, musisz na przykład utworzyć wystąpienie klienta usługi Storage — QueueServiceClient lub QueueClient. Zobacz przykłady tworzenia QueueServiceClient, aby dowiedzieć się więcej na temat uwierzytelniania.

• usługi Azure Active Directory
• klucza współużytkowanego
• sygnatury dostępu współdzielonego

Azure Active Directory

Usługa Azure Queue Storage obsługuje używanie usługi Azure Active Directory do uwierzytelniania żądań w swoich interfejsach API. Pakiet @azure/identity udostępnia różne typy poświadczeń, których aplikacja może użyć do tego celu. Aby uzyskać więcej szczegółów i przykładów, zobacz README dla @azure/identity.

Zgodność

Ta biblioteka jest zgodna z Node.js i przeglądarkami oraz jest weryfikowana w wersjach Node.js LTS (>=8.16.0) i najnowszych wersjach przeglądarki Chrome, Firefox i Edge.

Procesy robocze sieci Web

Ta biblioteka wymaga, aby niektóre obiekty DOM były globalnie dostępne w przypadku użycia w przeglądarce, które procesy robocze sieci Web nie są domyślnie dostępne. Aby ta biblioteka działała w procesach roboczych sieci Web, należy je polifill.

Aby uzyskać więcej informacji, zapoznaj się z naszą dokumentacją dotyczącą korzystania z zestawu Azure SDK for JS w Web Workers

Ta biblioteka zależy od następujących interfejsów API DOM, które wymagają zewnętrznych polifilli załadowanych podczas korzystania z procesów roboczych sieci Web:

• document
• DOMParser
• Node
• XMLSerializer

Różnice między Node.js a przeglądarkami

Istnieją różnice między środowiskiem uruchomieniowym Node.js a przeglądarkami. Podczas rozpoczynania pracy z tą biblioteką należy zwrócić uwagę na interfejsy API lub klasy oznaczone "TYLKO DOSTĘPNE W środowisku uruchomieniowym NODE.JS" lub "TYLKO DOSTĘPNE W PRZEGLĄDARKACH".

Następujące funkcje, interfejsy, klasy lub funkcje są dostępne tylko w Node.js

• Autoryzacja klucza współużytkowanego na podstawie nazwy konta i klucza konta
  • StorageSharedKeyCredential
• Generowanie sygnatury dostępu współdzielonego (SAS)
  • generateAccountSASQueryParameters()
  • generateQueueSASQueryParameters()

Pakiet JavaScript

Aby użyć tej biblioteki klienta w przeglądarce, najpierw należy użyć pakietu. Aby uzyskać szczegółowe informacje o tym, jak to zrobić, zapoznaj się z naszą dokumentacją dotyczącą tworzenia pakietów .

MECHANIZM CORS

Musisz skonfigurować współużytkowanie zasobów między źródłami (CORS) regułami dla konta magazynu, jeśli chcesz utworzyć aplikacje dla przeglądarek. Przejdź do witryny Azure Portal i Eksploratora usługi Azure Storage, znajdź konto magazynu, utwórz nowe reguły CORS dla usług blob/queue/file/table.

Można na przykład utworzyć następujące ustawienia mechanizmu CORS na potrzeby debugowania. Należy jednak dokładnie dostosować ustawienia zgodnie z wymaganiami w środowisku produkcyjnym.

• Dozwolone źródła: *
• Dozwolone czasowniki: DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
• Dozwolone nagłówki: *
• Uwidocznione nagłówki: *
• Maksymalny wiek (w sekundach): 86400

Kluczowe pojęcia

Kolejka to magazyn danych na koncie usługi Kolejka usługi Azure Storage służący do wysyłania/odbierania komunikatów między połączonymi klientami.

Kluczowe typy danych w naszej bibliotece związane z tymi usługami to:

• QueueServiceClient reprezentuje połączenie (za pośrednictwem adresu URL) z danym kontem magazynu w usłudze Azure Storage Queue i udostępnia interfejsy API do manipulowania kolejkami. Jest on uwierzytelniany w usłudze i może służyć do tworzenia obiektów QueueClient, a także tworzenia, usuwania, wyświetlania listy kolejek z usługi.
• QueueClient reprezentuje pojedynczą kolejkę na koncie magazynu. Może służyć do manipulowania komunikatami kolejki, na przykład do wysyłania, odbierania i podglądu komunikatów w kolejce.

Przykłady

Importowanie pakietu

Aby użyć klientów, zaimportuj pakiet do pliku:

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

Alternatywnie selektywnie zaimportuj tylko potrzebne typy:

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

Tworzenie klienta usługi kolejki

QueueServiceClient wymaga adresu URL usługi kolejki i poświadczenia dostępu. Opcjonalnie akceptuje również niektóre ustawienia w parametrze options.

z DefaultAzureCredential z pakietu @azure/identity

Zalecany sposób tworzenia wystąpienia QueueServiceClient

Konfiguracja: Odwołanie — autoryzowanie dostępu do obiektów blob i kolejek za pomocą usługi Azure Active Directory z poziomu aplikacji klienckiej — /azure/storage/common/storage-auth-aad-app

• Rejestrowanie nowej aplikacji usługi AAD i przyznawanie uprawnień dostępu do usługi Azure Storage w imieniu zalogowanego użytkownika

  • Rejestrowanie nowej aplikacji w usłudze Azure Active Directory (w witrynie Azure-Portal) — /azure/active-directory/develop/quickstart-register-app
  • W sekcji API permissions wybierz pozycję Add a permission i wybierz pozycję Microsoft APIs.
  • Wybierz Azure Storage i zaznacz pole wyboru obok user_impersonation, a następnie kliknij przycisk Add permissions. Umożliwiłoby to aplikacji dostęp do usługi Azure Storage w imieniu zalogowanego użytkownika.

• Udzielanie dostępu do danych kolejki usługi Azure Storage za pomocą kontroli dostępu opartej na rolach w witrynie Azure Portal

  • Role RBAC dla obiektów blob i kolejek — /azure/storage/common/storage-auth-aad-rbac-portal.
  • W witrynie Azure Portal przejdź do konta magazynu i przypisz rolę Współautor danych kolejki usługi Storage do zarejestrowanej aplikacji usługi AAD z karty Access control (IAM) (na pasku nawigacyjnym po lewej stronie konta magazynu w witrynie Azure-Portal).

• Konfiguracja środowiska dla przykładu

  • Na stronie przeglądu aplikacji usługi AAD zanotuj CLIENT ID i TENANT ID. Na karcie "Certyfikaty & Wpisy tajne" utwórz wpis tajny i zanotuj je.
  • Upewnij się, że masz AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET jako zmienne środowiskowe, aby pomyślnie wykonać przykład (może korzystać z pliku 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
);

[Uwaga — powyższe kroki dotyczą tylko Node.js]

używanie parametrów połączenia

Alternatywnie można utworzyć wystąpienie QueueServiceClient przy użyciu metody statycznej fromConnectionString() z pełnymi parametrami połączenia jako argumentem. (Parametry połączenia można uzyskać w witrynie Azure Portal). [DOSTĘPNE TYLKO W ŚRODOWISKU URUCHOMIENIOWYM NODE.JS]

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

const connStr = "<connection string>";

const queueServiceClient = QueueServiceClient.fromConnectionString(connStr);

z StorageSharedKeyCredential

Alternatywnie utworzysz wystąpienie QueueServiceClient przy użyciu StorageSharedKeyCredential, przekazując argumenty account-name i account-key. (Nazwę konta i klucz konta można uzyskać w witrynie Azure Portal). [DOSTĘPNE TYLKO W ŚRODOWISKU URUCHOMIENIOWYM 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
  }
);

z tokenem SAS

Ponadto można utworzyć wystąpienie QueueServiceClient przy użyciu sygnatur dostępu współdzielonego (SAS). Token SAS można uzyskać z witryny Azure Portal lub wygenerować go przy użyciu 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}`
);

Wyświetlanie listy kolejek na tym koncie

Użyj funkcji QueueServiceClient.listQueues(), aby iterować kolejki przy użyciu nowej składni 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 iter1 = queueServiceClient.listQueues();
  let i = 1;
  for await (const item of iter1) {
    console.log(`Queue${i}: ${item.name}`);
    i++;
  }
}

main();

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

Aby uzyskać kompletny przykład dotyczący iterowania kolejek, zobacz samples/v12/typescript/listQueues.ts.

Tworzenie nowej kolejki

Użyj funkcji QueueServiceClient.getQueueClient(), aby utworzyć nową kolejkę.

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

Wysyłanie komunikatu do kolejki

Użyj sendMessage(), aby dodać komunikat do kolejki:

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

Podgląd wiadomości

QueueClient.peekMessages() umożliwia przeglądanie co najmniej jednego komunikatu przed kolejką. To wywołanie nie uniemożliwia innego kodu uzyskiwania dostępu do zajrzeć do komunikatów.

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

Przetwarzanie komunikatu

Komunikaty są przetwarzane w dwóch krokach.

• Najpierw wywołaj queueClient.receiveMessages(). Dzięki temu komunikaty są niewidoczne dla innych komunikatów odczytu z tej kolejki przez domyślny okres 30 sekund.
• Po zakończeniu przetwarzania komunikatu wywołaj queueClient.deleteMessage() za pomocą popReceiptkomunikatu .

Jeśli kod nie może przetworzyć komunikatu z powodu awarii sprzętu lub oprogramowania, ten dwuetapowy proces gwarantuje, że inne wystąpienie kodu może uzyskać ten sam komunikat i spróbować ponownie.

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

Usuwanie kolejki

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

Kompletny przykład prostych scenariuszy QueueServiceClient znajduje się w samples/v12/typescript/src/queueClient.ts.

Rozwiązywanie problemów

Włączenie rejestrowania może pomóc odkryć przydatne informacje o błędach. Aby wyświetlić dziennik żądań i odpowiedzi HTTP, ustaw zmienną środowiskową AZURE_LOG_LEVEL na info. Alternatywnie rejestrowanie można włączyć w czasie wykonywania, wywołując setLogLevel w @azure/logger:

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

setLogLevel("info");

Następne kroki

Więcej przykładów kodu

• przykłady usługi Queue Storage
• Queue Storage Test Cases

Przyczyniając się

Jeśli chcesz współtworzyć tę bibliotekę, przeczytaj przewodnik dotyczący współtworzenia , aby dowiedzieć się więcej na temat tworzenia i testowania kodu.

Zapoznaj się również z przewodnikiem Storage, aby uzyskać dodatkowe informacje na temat konfigurowania środowiska testowego dla bibliotek magazynu.