Szybki start: biblioteka klienta usługi Azure Queue Storage dla języka JavaScript

  • Artykuł

Wprowadzenie do biblioteki klienta usługi Azure Queue Storage dla języka JavaScript. Azure Queue Storage to usługa do przechowywania dużej liczby komunikatów na potrzeby późniejszego pobierania i przetwarzania. Wykonaj następujące kroki, aby zainstalować pakiet i wypróbować przykładowy kod dla podstawowych zadań.

Dokumentacja interfejsu API — dokumentacja | pakietu kodu | źródłowego biblioteki (npm)Przykłady |

Użyj biblioteki klienta usługi Azure Queue Storage dla języka JavaScript, aby:

  • Utwórz kolejkę
  • Dodawanie komunikatów do kolejki
  • Podgląd komunikatów w kolejce
  • Aktualizowanie komunikatu w kolejce
  • Pobieranie długości kolejki
  • Odbieranie komunikatów z kolejki
  • Usuwanie komunikatów z kolejki
  • Usuwanie kolejki

Wymagania wstępne

Konfigurowanie

Ta sekcja przeprowadzi Cię przez proces przygotowywania projektu do pracy z biblioteką klienta usługi Azure Queue Storage dla języka JavaScript.

Tworzenie projektu

Utwórz aplikację Node.js o nazwie queues-quickstart.

  1. W oknie konsoli (takim jak cmd, PowerShell lub Bash) utwórz nowy katalog dla projektu:

    mkdir queues-quickstart

  2. Przejdź do nowo utworzonego queues-quickstart katalogu:

    cd queues-quickstart

  3. Utwórz plik package.json:

    npm init -y

  4. Otwórz projekt w programie Visual Studio Code:

    code .

Instalowanie pakietów

Z katalogu projektu zainstaluj następujące pakiety przy użyciu npm install polecenia .

  1. Zainstaluj pakiet npm usługi Azure Queue Storage:

    npm install @azure/storage-queue

  2. Zainstaluj pakiet npm tożsamości platformy Azure, aby obsługiwać połączenia bez hasła:

    npm install @azure/identity

  3. Zainstaluj inne zależności używane w tym przewodniku Szybki start:

    npm install uuid dotenv

Konfigurowanie struktury aplikacji

Z katalogu projektu:

  1. Otwieranie nowego pliku tekstowego w edytorze kodu

  2. Dodawanie require wywołań w celu załadowania modułów Azure i Node.js

  3. Tworzenie struktury programu, w tym podstawowej obsługi wyjątków

    Oto kod:

    const { QueueClient } = require("@azure/storage-queue");
const { DefaultAzureCredential } = require('@azure/identity');
const { v1: uuidv1 } = require("uuid");

async function main() {
    console.log("Azure Queue Storage client library - JavaScript quickstart sample");

    // Quickstart code goes here
}

main().then(() => console.log("\nDone")).catch((ex) => console.log(ex.message));

  4. Zapisz nowy plik w formacie index.jsqueues-quickstart w katalogu .

Uwierzytelnianie na platformie Azure

Żądania aplikacji do większości usług platformy Azure muszą być autoryzowane. DefaultAzureCredential Użycie klasy udostępnionej przez bibliotekę klienta tożsamości platformy Azure jest zalecanym podejściem do implementowania połączeń bez hasła z usługami platformy Azure w kodzie.

Możesz również autoryzować żądania do usług platformy Azure przy użyciu haseł, parametry połączenia lub innych poświadczeń bezpośrednio. Należy jednak zachować ostrożność przy użyciu tego podejścia. Deweloperzy muszą być sumienni, aby nigdy nie ujawniać tych wpisów tajnych w niezabezpieczonej lokalizacji. Każdy, kto uzyskuje dostęp do hasła lub klucza tajnego, może się uwierzytelnić. DefaultAzureCredential oferuje ulepszone korzyści związane z zarządzaniem i zabezpieczeniami za pośrednictwem klucza konta, aby umożliwić uwierzytelnianie bez hasła. Obie opcje przedstawiono w poniższym przykładzie.

DefaultAzureCredential jest klasą dostarczaną przez bibliotekę klienta tożsamości platformy Azure dla języka JavaScript. Aby dowiedzieć się więcej na temat DefaultAzureCredentialusługi , zobacz Omówienie domyślneAzureCredential. DefaultAzureCredential obsługuje wiele metod uwierzytelniania i określa, która metoda powinna być używana w czasie wykonywania. Takie podejście umożliwia aplikacji używanie różnych metod uwierzytelniania w różnych środowiskach (lokalnych i produkcyjnych) bez implementowania kodu specyficznego dla środowiska.

Na przykład aplikacja może uwierzytelniać się przy użyciu poświadczeń logowania interfejsu wiersza polecenia platformy Azure podczas tworzenia aplikacji lokalnie, a następnie używać tożsamości zarządzanej po jej wdrożeniu na platformie Azure. Do tego przejścia nie są wymagane żadne zmiany kodu.

Podczas tworzenia aplikacji lokalnie upewnij się, że konto użytkownika, które uzyskuje dostęp do danych kolejki, ma odpowiednie uprawnienia. Będziesz potrzebować współautora danych kolejki usługi Storage, aby odczytywać i zapisywać dane kolejki. Aby przypisać sobie tę rolę, musisz przypisać rolę Administracja istratora dostępu użytkowników lub inną rolę obejmującą akcję Microsoft.Authorization/roleAssignments/write. Role RBAC platformy Azure można przypisać użytkownikowi przy użyciu witryny Azure Portal, interfejsu wiersza polecenia platformy Azure lub programu Azure PowerShell. Więcej informacji na temat dostępnych zakresów przypisań ról można znaleźć na stronie przeglądu zakresu.

W tym scenariuszu przypiszesz uprawnienia do konta użytkownika w zakresie konta magazynu, aby postępować zgodnie z zasadą najniższych uprawnień. Ta praktyka zapewnia użytkownikom tylko minimalne wymagane uprawnienia i tworzy bezpieczniejsze środowiska produkcyjne.

W poniższym przykładzie do konta użytkownika zostanie przypisana rola Współautor danych kolejki magazynu, która zapewnia zarówno dostęp do odczytu, jak i zapisu do danych kolejki na koncie magazynu.

Ważne

W większości przypadków propagacja przypisania roli na platformie Azure potrwa minutę lub dwie, ale w rzadkich przypadkach może upłynąć do ośmiu minut. Jeśli podczas pierwszego uruchomienia kodu wystąpią błędy uwierzytelniania, zaczekaj chwilę i spróbuj ponownie.

  1. W witrynie Azure Portal znajdź konto magazynu przy użyciu głównego paska wyszukiwania lub nawigacji po lewej stronie.

  2. Na stronie przeglądu konta magazynu wybierz pozycję Kontrola dostępu (Zarządzanie dostępem i tożsamościami) z menu po lewej stronie.

  3. Na stronie Kontrola dostępu (Zarządzanie dostępem i tożsamościami) wybierz kartę Przypisania ról.

  4. Wybierz pozycję + Dodaj z górnego menu, a następnie pozycję Dodaj przypisanie roli z wyświetlonego menu rozwijanego.

A screenshot showing how to assign a role.

  1. Użyj pola wyszukiwania, aby filtrować wyniki do żądanej roli. W tym przykładzie wyszukaj pozycję Współautor danych kolejki usługi Storage i wybierz pasujący wynik, a następnie wybierz pozycję Dalej.

  2. W obszarze Przypisz dostęp do wybierz pozycję Użytkownik, grupa lub jednostka usługi, a następnie wybierz pozycję + Wybierz członków.

  3. W oknie dialogowym wyszukaj nazwę użytkownika firmy Microsoft Entra (zazwyczaj adres e-mail user@domain ), a następnie wybierz pozycję Wybierz w dolnej części okna dialogowego.

  4. Wybierz pozycję Przejrzyj i przypisz , aby przejść do ostatniej strony, a następnie ponownie przejrzyj i przypisz, aby ukończyć proces.

Model obiektów

Azure Queue Storage to usługa służąca do przechowywania dużej liczby komunikatów. Komunikat kolejki może mieć rozmiar do 64 KB. Kolejka może zawierać miliony komunikatów do całkowitego limitu pojemności konta magazynu. Kolejki są często używane do tworzenia listy prac w celu asynchronicznego przetwarzania. Usługa Queue Storage oferuje trzy typy zasobów:

  • Konto magazynu: cały dostęp do usługi Azure Storage odbywa się za pośrednictwem konta magazynu. Aby uzyskać więcej informacji na temat kont magazynu, zobacz Omówienie konta magazynu
  • Kolejka: kolejka zawiera zestaw komunikatów. Wszystkie komunikaty muszą być w kolejce. Pamiętaj, że nazwa kolejki może zawierać tylko małe litery. Informacje dotyczące nazewnictwa kolejek można znaleźć w temacie Naming Queues and Metadata (Nazewnictwo kolejek i metadanych).
  • Komunikat: komunikat w dowolnym formacie, o maksymalnym rozmiarze 64 KB. Komunikat może pozostać w kolejce przez maksymalnie 7 dni. W przypadku wersji 2017-07-29 lub nowszej maksymalny czas wygaśnięcia może być dowolną liczbą dodatnią lub -1 wskazującą, że komunikat nie wygasa. Jeśli ten parametr zostanie pominięty, domyślny czas wygaśnięcia wynosi siedem dni.

Na poniższym diagramie przedstawiono relacje między tymi zasobami.

Diagram of Queue storage architecture

Użyj następujących klas języka JavaScript, aby wchodzić w interakcje z tymi zasobami:

  • QueueServiceClientQueueServiceClient: Wystąpienie reprezentuje połączenie z danym kontem magazynu w usłudze Azure Storage Queue. Ten klient umożliwia zarządzanie wszystkimi kolejkami na koncie magazynu.
  • QueueClientQueueClient: Wystąpienie reprezentuje pojedynczą kolejkę na koncie magazynu. Ten klient umożliwia zarządzanie pojedynczą kolejką i jej komunikatami oraz manipulowanie nimi.

Przykłady kodu

Te przykładowe fragmenty kodu pokazują, jak wykonać następujące czynności za pomocą biblioteki klienta usługi Azure Queue Storage dla języka JavaScript:

Autoryzowanie dostępu i tworzenie obiektu klienta

Upewnij się, że uwierzytelniasz się przy użyciu tego samego konta Microsoft Entra, do którego przypisano rolę. Uwierzytelnianie można przeprowadzić za pomocą interfejsu wiersza polecenia platformy Azure, programu Visual Studio Code lub programu Azure PowerShell.

Zaloguj się do platformy Azure za pomocą interfejsu wiersza polecenia platformy Azure przy użyciu następującego polecenia:

az login

Po uwierzytelnieniu można utworzyć i autoryzować QueueClient obiekt przy użyciu funkcji DefaultAzureCredential uzyskiwania dostępu do danych kolejki na koncie magazynu. DefaultAzureCredential program automatycznie odnajduje i używa konta, które zostało zalogowane w poprzednim kroku.

Aby autoryzować przy użyciu programu DefaultAzureCredential, upewnij się, że dodano pakiet @azure/tożsamość zgodnie z opisem w temacie Instalowanie pakietów. Pamiętaj również, aby załadować moduł @azure/identity w pliku index.js :

const { DefaultAzureCredential } = require('@azure/identity');

Zdecyduj o nazwie kolejki i utwórz wystąpienie QueueClient klasy przy użyciu DefaultAzureCredential autoryzacji. Ten obiekt klienta jest używany do tworzenia zasobu kolejki i interakcji z nim na koncie magazynu.

Ważne

Nazwy kolejek mogą zawierać tylko małe litery, cyfry i łączniki oraz muszą zaczynać się literą lub cyfrą. Przed i za każdym łącznikiem musi znajdować się znak inny niż łącznik. Nazwa musi również mieć długość od 3 do 63 znaków. Aby uzyskać więcej informacji na temat nazewnictwa kolejek, zobacz Nazewnictwo kolejek i metadanych.

Dodaj następujący kod wewnątrz main metody i pamiętaj, aby zastąpić wartość symbolu zastępczego <storage-account-name> :

// Create a unique name for the queue
const queueName = "quickstart" + uuidv1();

// Instantiate a QueueClient which will be used to create and interact with a queue
// TODO: replace <storage-account-name> with the actual name
const queueClient = new QueueClient(`https://<storage-account-name>.queue.core.windows.net/${queueName}`, new DefaultAzureCredential());

Uwaga

Komunikaty wysyłane przy użyciu QueueClient klasy muszą być w formacie, który można uwzględnić w żądaniu XML z kodowaniem UTF-8. Aby dołączyć znaczniki do wiadomości, zawartość wiadomości musi być zakodowana w formacie XML lub zakodowana w formacie Base64.

Komunikaty kolejek są przechowywane jako ciągi. Jeśli chcesz wysłać inny typ danych, musisz serializować ten typ danych w ciągu podczas wysyłania komunikatu i deserializacji formatu ciągu podczas odczytywania komunikatu.

Aby przekonwertować format JSON na format ciągu i z powrotem w pliku Node.js, użyj następujących funkcji pomocnika:

function jsonToBase64(jsonObj) {
    const jsonString = JSON.stringify(jsonObj)
    return  Buffer.from(jsonString).toString('base64')
}
function encodeBase64ToJson(base64String) {
    const jsonString = Buffer.from(base64String,'base64').toString()
    return JSON.parse(jsonString)
}

Utwórz kolejkę

Za pomocą obiektu wywołaj QueueClient metodę create , aby utworzyć kolejkę na koncie magazynu.

Dodaj ten kod na końcu main metody:

console.log("\nCreating queue...");
console.log("\t", queueName);

// Create the queue
const createQueueResponse = await queueClient.create();
console.log("Queue created, requestId:", createQueueResponse.requestId);

Dodawanie komunikatów do kolejki

Poniższy fragment kodu dodaje komunikaty do kolejki, wywołując metodę sendMessage . Zapisuje również zwrócone QueueSendMessageResponse z trzeciego sendMessage wywołania. Zwrócony sendMessageResponse element służy do aktualizowania zawartości komunikatu w dalszej części programu.

Dodaj ten kod na końcu main funkcji:

console.log("\nAdding messages to the queue...");

// Send several messages to the queue
await queueClient.sendMessage("First message");
await queueClient.sendMessage("Second message");
const sendMessageResponse = await queueClient.sendMessage("Third message");

console.log("Messages added, requestId:", sendMessageResponse.requestId);

Podgląd komunikatów w kolejce

Przyjrzyj się komunikatom w kolejce, wywołując metodę peekMessages . Ta metoda pobiera jeden lub więcej komunikatów z przodu kolejki, ale nie zmienia widoczności komunikatu. Domyślnie peekMessages zagląda do pojedynczego komunikatu.

Dodaj ten kod na końcu main funkcji:

console.log("\nPeek at the messages in the queue...");

// Peek at messages in the queue
const peekedMessages = await queueClient.peekMessages({ numberOfMessages : 5 });

for (i = 0; i < peekedMessages.peekedMessageItems.length; i++) {
    // Display the peeked message
    console.log("\t", peekedMessages.peekedMessageItems[i].messageText);
}

Aktualizowanie komunikatu w kolejce

Zaktualizuj zawartość komunikatu, wywołując metodę updateMessage . Ta metoda może zmienić limit czasu widoczności i zawartości komunikatu. Zawartość komunikatu musi być ciągiem zakodowanym w formacie UTF-8 o rozmiarze do 64 KB. Wraz z nową zawartością przekaż messageId i popReceipt z odpowiedzi, która została zapisana wcześniej w kodzie. Właściwości sendMessageResponse identyfikują komunikat do zaktualizowania.

console.log("\nUpdating the third message in the queue...");

// Update a message using the response saved when calling sendMessage earlier
updateMessageResponse = await queueClient.updateMessage(
    sendMessageResponse.messageId,
    sendMessageResponse.popReceipt,
    "Third message has been updated"
);

console.log("Message updated, requestId:", updateMessageResponse.requestId);

Pobieranie długości kolejki

Metoda getProperties zwraca metadane dotyczące kolejki, w tym przybliżoną liczbę komunikatów oczekujących w kolejce.

const properties = await queueClient.getProperties();
console.log("Approximate queue length: ", properties.approximateMessagesCount);

Odbieranie komunikatów z kolejki

Pobierz wcześniej dodane komunikaty, wywołując metodę receiveMessages . numberOfMessages W polu przekaż maksymalną liczbę komunikatów, które będą odbierane dla tego wywołania.

Dodaj ten kod na końcu main funkcji:

console.log("\nReceiving messages from the queue...");

// Get messages from the queue
const receivedMessagesResponse = await queueClient.receiveMessages({ numberOfMessages : 5 });

console.log("Messages received, requestId:", receivedMessagesResponse.requestId);

Podczas wywoływania receiveMessages metody można opcjonalnie określić wartości w funkcji QueueReceiveMessageOptions w celu dostosowania pobierania komunikatów . Można określić wartość parametru numberOfMessages, czyli liczbę komunikatów do pobrania z kolejki. Wartość domyślna to 1 komunikat, a maksymalna to 32 komunikaty. Można również określić wartość parametru visibilityTimeout, która ukrywa komunikaty przed innymi operacjami w okresie przekroczenia limitu czasu. Wartość domyślna to 30 sekund.

Usuwanie komunikatów z kolejki

Komunikaty z kolejki można usunąć po ich odebraniu i przetworzeniu. W takim przypadku przetwarzanie po prostu wyświetla komunikat w konsoli programu .

Usuń komunikaty, wywołując metodę deleteMessage . Wszystkie komunikaty, które nie zostały jawnie usunięte, staną się widoczne w kolejce ponownie, aby można było je przetworzyć.

Dodaj ten kod na końcu main funkcji:

// 'Process' and delete messages from the queue
for (i = 0; i < receivedMessagesResponse.receivedMessageItems.length; i++) {
    receivedMessage = receivedMessagesResponse.receivedMessageItems[i];

    // 'Process' the message
    console.log("\tProcessing:", receivedMessage.messageText);

    // Delete the message
    const deleteMessageResponse = await queueClient.deleteMessage(
        receivedMessage.messageId,
        receivedMessage.popReceipt
    );
    console.log("\tMessage deleted, requestId:", deleteMessageResponse.requestId);
}

Usuwanie kolejki

Poniższy kod czyści zasoby utworzone przez aplikację przez usunięcie kolejki przy użyciu delete metody .

Dodaj ten kod na końcu main funkcji i zapisz plik:

// Delete the queue
console.log("\nDeleting queue...");
const deleteQueueResponse = await queueClient.delete();
console.log("Queue deleted, requestId:", deleteQueueResponse.requestId);

Uruchamianie kodu

Ta aplikacja tworzy i dodaje trzy komunikaty do kolejki platformy Azure. Kod wyświetla listę komunikatów w kolejce, a następnie pobiera je i usuwa przed usunięciem kolejki.

W oknie konsoli przejdź do katalogu zawierającego index.js plik, a następnie użyj następującego node polecenia, aby uruchomić aplikację.

node index.js

Dane wyjściowe aplikacji są podobne do następującego przykładu:

Azure Queue Storage client library - JavaScript quickstart sample

Creating queue...
         quickstart<UUID>
Queue created, requestId: 5c0bc94c-6003-011b-7c11-b13d06000000

Adding messages to the queue...
Messages added, requestId: a0390321-8003-001e-0311-b18f2c000000

Peek at the messages in the queue...
         First message
         Second message
         Third message

Updating the third message in the queue...
Message updated, requestId: cb172c9a-5003-001c-2911-b18dd6000000

Receiving messages from the queue...
Messages received, requestId: a039036f-8003-001e-4811-b18f2c000000
        Processing: First message
        Message deleted, requestId: 4a65b82b-d003-00a7-5411-b16c22000000
        Processing: Second message
        Message deleted, requestId: 4f0b2958-c003-0030-2a11-b10feb000000
        Processing: Third message has been updated
        Message deleted, requestId: 6c978fcb-5003-00b6-2711-b15b39000000

Deleting queue...
Queue deleted, requestId: 5c0bca05-6003-011b-1e11-b13d06000000

Done

Wykonaj kroki kodu w debugerze i sprawdź witrynę Azure Portal w całym procesie. Sprawdź konto magazynu, aby sprawdzić, czy komunikaty w kolejce są tworzone i usuwane.

Następne kroki

W tym przewodniku Szybki start przedstawiono sposób tworzenia kolejki i dodawania do niej komunikatów przy użyciu kodu JavaScript. Następnie przedstawiono wgląd, pobieranie i usuwanie komunikatów. Na koniec przedstawiono sposób usuwania kolejki komunikatów.

Aby zapoznać się z samouczkami, przykładami, przewodnikami Szybki start i inną dokumentacją, odwiedź stronę:

Dokumentacja platformy Azure dla języka JavaScript