Udostępnij przez

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

Wprowadzenie do biblioteki klienta usługi Azure Queue Storage dla języka Java. 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 referencyjna API | Kod źródłowy biblioteki | Pakiet (Maven) | Przykłady

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

  • Utwórz kolejkę
  • Dodawanie komunikatów do kolejki
  • Podgląd komunikatów w kolejce
  • Zaktualizuj komunikat w kolejce
  • Pobierz długość kolejki
  • Odbieranie komunikatów z kolejki
  • Usuwanie komunikatów z kolejki
  • Usuń kolejkę

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 Java.

Tworzenie projektu

Utwórz aplikację Java o nazwie queues-quickstart.

  1. W oknie konsoli (takim jak cmd, PowerShell lub Bash) użyj narzędzia Maven, aby utworzyć nową aplikację konsolową z nazwą queues-quickstart. Wpisz następujące polecenie mvn, aby utworzyć projekt Java "Hello, world!".

    mvn archetype:generate `
    --define interactiveMode=n `
    --define groupId=com.queues.quickstart `
    --define artifactId=queues-quickstart `
    --define archetypeArtifactId=maven-archetype-quickstart `
    --define archetypeVersion=1.4

  2. Dane wyjściowe generowania projektu powinny wyglądać mniej więcej tak:

    [INFO] Scanning for projects...
[INFO]
[INFO] ------------------< org.apache.maven:standalone-pom >-------------------
[INFO] Building Maven Stub Project (No POM) 1
[INFO] --------------------------------[ pom ]---------------------------------
[INFO]
[INFO] >>> maven-archetype-plugin:3.1.2:generate (default-cli) > generate-sources @ standalone-pom >>>
[INFO]
[INFO] <<< maven-archetype-plugin:3.1.2:generate (default-cli) < generate-sources @ standalone-pom <<<
[INFO]
[INFO]
[INFO] --- maven-archetype-plugin:3.1.2:generate (default-cli) @ standalone-pom ---
[INFO] Generating project in Batch mode
[INFO] ----------------------------------------------------------------------------
[INFO] Using following parameters for creating project from Archetype: maven-archetype-quickstart:1.4
[INFO] ----------------------------------------------------------------------------
[INFO] Parameter: groupId, Value: com.queues.quickstart
[INFO] Parameter: artifactId, Value: queues-quickstart
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] Parameter: package, Value: com.queues.quickstart
[INFO] Parameter: packageInPathFormat, Value: com/queues/quickstart
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] Parameter: package, Value: com.queues.quickstart
[INFO] Parameter: groupId, Value: com.queues.quickstart
[INFO] Parameter: artifactId, Value: queues-quickstart
[INFO] Project created from Archetype in dir: C:\quickstarts\queues\queues-quickstart
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  6.394 s
[INFO] Finished at: 2019-12-03T09:58:35-08:00
[INFO] ------------------------------------------------------------------------

  3. Przejdź do nowo utworzonego katalogu queues-quickstart .

    cd queues-quickstart

Instalowanie pakietów

pom.xml Otwórz plik w edytorze tekstów.

Dodaj azure-sdk-bom, aby wziąć zależność od najnowszej wersji biblioteki. W poniższym fragmencie kodu zastąp {bom_version_to_target} symbol zastępczy numerem wersji. Korzystanie z azure-sdk-bom zwalnia z konieczności określania wersji każdej indywidualnej zależności. Aby dowiedzieć się więcej na temat BOM, zobacz README Azure SDK BOM.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Następnie dodaj następujące elementy zależności do grupy zależności. Zależność azure-identity jest wymagana w przypadku połączeń bez hasła z usługami platformy Azure.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-queue</artifactId>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
</dependency>

Konfigurowanie struktury aplikacji

Z katalogu projektu:

  1. Przejdź do katalogu /src/main/java/com/queues/quickstart
  2. Otwórz plik App.java w edytorze
  3. Usuń instrukcję System.out.println("Hello, world");
  4. Dodaj import dyrektywy

Oto kod:

package com.queues.quickstart;

/**
 * Azure Queue Storage client library quickstart
 */
import com.azure.identity.*;
import com.azure.storage.queue.*;
import com.azure.storage.queue.models.*;
import java.io.*;

public class App
{
    public static void main(String[] args) throws IOException
    {
        // Quickstart code goes here
    }
}

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ł, parametrów 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 tajemnic w niezabezpieczonym miejscu. 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 Java. Aby dowiedzieć się więcej na temat DefaultAzureCredential, zobacz Omówienie DefaultAzureCredential. 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ć Storage Queue Data Contributor, aby móc odczytywać i zapisywać dane w kolejce. Aby przypisać sobie tę rolę, musisz mieć przypisaną rolę Administratora 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 Twojego konta użytkownika w zakresie konta magazynowego, 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 Twojego konta użytkownika zostanie przypisana rola Kontrybutor danych kolejki magazynowej, która zapewnia zarówno dostęp do odczytu, jak i zapisu danych kolejki w Twoim koncie magazynowym.

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 portalu Azure znajdź swoje konto magazynowe, używając głównego paska wyszukiwania lub nawigacji z lewej strony.

  2. Na stronie przeglądu konta magazynu wybierz pozycję Kontrola dostępu (IAM) z menu po lewej stronie.

  3. Na stronie Kontrola dostępu (IAM) wybierz kartę Przypisania ról.

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

Zrzut ekranu przedstawiający sposób przypisywania roli.

  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 Użytkownik, grupa lub główna nazwa usługi, a następnie wybierz + 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 do przechowywania dużej liczby komunikatów. Komunikat kolejki może mieć rozmiar do 64 KB. Kolejka może zawierać miliony komunikatów, aż do osiągnięcia całkowitego limitu pojemności konta magazynowego. Kolejki są często używane do tworzenia zapasu zaległych zadań w celu asynchronicznego przetwarzania zadań. Usługa Queue Storage oferuje trzy typy zasobów:

  • Konto magazynu: Wszystkie działania związane z dostępem do Azure Storage odbywają 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 wiadomości 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 architektury przechowywania kolejek

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

  • QueueClientBuilder: Klasa QueueClientBuilder konfiguruje i tworzy instancję obiektu QueueClient.
  • QueueServiceClient: QueueServiceClient to umożliwia zarządzanie wszystkimi kolejkami w koncie magazynowym.
  • QueueClient: Klasa QueueClient umożliwia zarządzanie pojedynczą kolejką i jej komunikatami oraz manipulowanie nimi.
  • QueueMessageItem: Klasa QueueMessageItem reprezentuje poszczególne obiekty, które są zwracane podczas wywoływania ReceiveMessages na kolejce.

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 Java:

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 za pomocą DefaultAzureCredential do uzyskania dostępu do danych kolejki na koncie przechowywania. DefaultAzureCredential program automatycznie odnajduje i używa konta, które zostało zalogowane w poprzednim kroku.

Aby autoryzować przy użyciu DefaultAzureCredential, upewnij się, że dodałeś zależność azure-identity w pom.xml, zgodnie z opisem w temacie Instalowanie pakietów. Pamiętaj również, aby dodać dyrektywę import dla com.azure.identity w pliku App.java.

import com.azure.identity.*;

Zdecyduj o nazwie kolejki i utwórz wystąpienie klasy QueueClient, używając DefaultAzureCredential do autoryzacji. Używamy tego obiektu klienta do tworzenia i interakcji z zasobem kolejki na koncie magazynowym.

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 ten kod wewnątrz metody main i pamiętaj, aby zastąpić wartość symbolu zastępczego <storage-account-name>:

System.out.println("Azure Queue Storage client library - Java quickstart sample\n");

// Create a unique name for the queue
String queueName = "quickstartqueues-" + java.util.UUID.randomUUID();

// Instantiate a QueueClient
// We'll use this client object to create and interact with the queue
// TODO: replace <storage-account-name> with the actual name
QueueClient queueClient = new QueueClientBuilder()
        .endpoint("https://<storage-account-name>.queue.core.windows.net/")
        .queueName(queueName)
        .credential(new DefaultAzureCredentialBuilder().build())
        .buildClient();

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. Opcjonalnie można ustawić opcję QueueMessageEncoding do obsługi BASE64 niezgodnych komunikatów.

Utwórz kolejkę

Używając obiektu QueueClient, wywołaj metodę create, aby utworzyć kolejkę na koncie magazynowym.

Dodaj ten kod na końcu main metody:

System.out.println("Creating queue: " + queueName);

// Create the queue
queueClient.create();

Dodawanie komunikatów do kolejki

Poniższy fragment kodu dodaje komunikaty do kolejki, wywołując metodę sendMessage . Zapisuje również zwrócony element SendMessageResult z wywołania sendMessage . Wynik jest używany do aktualizacji komunikatu w dalszej części programu.

Dodaj ten kod na końcu main metody:

System.out.println("\nAdding messages to the queue...");

// Send several messages to the queue
queueClient.sendMessage("First message");
queueClient.sendMessage("Second message");

// Save the result so we can update this message later
SendMessageResult result = queueClient.sendMessage("Third message");

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.

Dodaj ten kod na końcu main metody:

System.out.println("\nPeek at the messages in the queue...");

// Peek at messages in the queue
queueClient.peekMessages(10, null, null).forEach(
    peekedMessage -> System.out.println("Message: " + peekedMessage.getMessageText()));

Zaktualizuj komunikat 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ą wiadomości przekaż identyfikator wiadomości i potwierdzenie odbioru, używając SendMessageResult, które zostało zapisane wcześniej w kodzie. Identyfikator wiadomości i pokwitowanie odbioru identyfikują, który wiadomość zaktualizować.

System.out.println("\nUpdating the third message in the queue...");

// Update a message using the result that
// was saved when sending the message
queueClient.updateMessage(result.getMessageId(),
                          result.getPopReceipt(),
                          "Third message has been updated",
                          Duration.ofSeconds(1));

Pobierz długość kolejki

Możesz uzyskać szacunkową liczbę wiadomości w kolejce.

Metoda getProperties zwraca kilka wartości, w tym liczbę komunikatów aktualnie w kolejce. Liczba jest przybliżona tylko dlatego, że komunikaty można dodawać lub usuwać po żądaniu. Metoda getApproximateMessageCount zwraca ostatnią wartość pobraną przez wywołanie metody do getProperties, bez wywoływania usługi Queue Storage.

QueueProperties properties = queueClient.getProperties();
long messageCount = properties.getApproximateMessagesCount();

System.out.println(String.format("Queue length: %d", messageCount));

Odbieranie i usuwanie komunikatów z kolejki

Pobierz wcześniej dodane komunikaty, wywołując metodę receiveMessages . Przykładowy kod usuwa również komunikaty z kolejki po ich odebraniu i przetworzeniu. W takim przypadku przetwarzanie po prostu wyświetla komunikat na konsoli.

Aplikacja zatrzymuje się na dane wejściowe użytkownika, wywołując System.console().readLine(); przed odebraniem i usunięciem komunikatów. Sprawdź w witrynie Azure Portal , czy zasoby zostały utworzone poprawnie, zanim zostaną usunięte. 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 metody:

System.out.println("\nPress Enter key to receive messages and delete them from the queue...");
System.console().readLine();

// Get messages from the queue
queueClient.receiveMessages(10).forEach(
    // "Process" the message
    receivedMessage -> {
        System.out.println("Message: " + receivedMessage.getMessageText());

        // Let the service know we're finished with
        // the message and it can be safely deleted.
        queueClient.deleteMessage(receivedMessage.getMessageId(), receivedMessage.getPopReceipt());
    }
);

Podczas wywoływania receiveMessages metody można opcjonalnie określić wartość maxMessagesparametru , 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.

Usuń kolejkę

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 metody:

System.out.println("\nPress Enter key to delete the queue...");
System.console().readLine();

// Clean up
System.out.println("Deleting queue: " + queueClient.getQueueName());
queueClient.delete();

System.out.println("Done");

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 aplikacji, a następnie skompiluj i uruchom aplikację.

mvn compile

Następnie skompiluj pakiet.

mvn package

Użyj następującego mvn polecenia, aby uruchomić aplikację.

mvn exec:java -Dexec.mainClass="com.queues.quickstart.App" -Dexec.cleanupDaemonThreads=false

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

Azure Queue Storage client library - Java quickstart sample

Adding messages to the queue...

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

Updating the third message in the queue...

Press Enter key to receive messages and delete them from the queue...

Message: First message
Message: Second message
Message: Third message has been updated

Press Enter key to delete the queue...

Deleting queue: quickstartqueues-fbf58f33-4d5a-41ac-ac0e-1a05d01c7003
Done

Gdy aplikacja wstrzymuje się przed odebraniem komunikatów, sprawdź konto magazynu w witrynie Azure Portal. Sprawdź, czy komunikaty znajdują się w kolejce.

Naciśnij , Enter aby odbierać i usuwać komunikaty. Po wyświetleniu monitu naciśnij ponownie klawisz Enter, aby usunąć kolejkę i zakończyć demonstrację.

Następne kroki

W tym szybkim przewodniku nauczyłeś się, jak utworzyć kolejkę i dodać do niej komunikaty przy użyciu kodu Java. Następnie nauczyłeś się podglądać, pobierać i usuwać wiadomości. Na koniec nauczyłeś się, jak usunąć kolejkę komunikatów.

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

azure dla deweloperów rozwiązań w chmurze Java

  • Last updated on