Jak używać usługi Queue Storage z poziomu języka Java

Przegląd

W tym przewodniku pokazano, jak kodować typowe scenariusze przy użyciu usługi Azure Queue Storage. Przykłady są napisane w języku Java i używają zestawu AZURE Storage SDK dla języka Java. Scenariusze obejmują wstawianie, wyświetlanie, pobieranie i usuwanie komunikatów w kolejce. Omówiono również kod tworzenia iusuwania kolejek. Aby uzyskać więcej informacji na temat kolejek, zobacz sekcję Następne kroki .

Co to jest usługa Queue Storage?

Azure Queue Storage to usługa do przechowywania dużej liczby komunikatów, do których można uzyskiwać dostęp z dowolnego miejsca na świecie za pośrednictwem uwierzytelnionych wywołań przy użyciu protokołu HTTP lub HTTPS. Pojedynczy komunikat w kolejce może mieć rozmiar do 64 KB, a kolejka może zawierać miliony komunikatów, aż do osiągnięcia całkowitej pojemności konta magazynu. Usługa Queue Storage jest często używana do tworzenia listy prac w celu asynchronicznego przetwarzania.

Pojęcia dotyczące usługi kolejkowania

Usługa Azure Queue Service zawiera następujące składniki:

• #B0 Konto magazynowe: #C1 Wszelki dostęp do usługi Azure Storage odbywa się za pośrednictwem konta magazynowego. 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 sekcji Naming Queues and Metadata.

• Komunikat: komunikat w dowolnym formacie, o maksymalnym rozmiarze 64 KB. Maksymalny czas pozostawania komunikatu w kolejce wynosi 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.

• Format adresu URL: kolejki są adresowalne przy użyciu następującego formatu adresu URL: http://.queue.core.windows.net/<storage account>

  Następujący adres URL adresuje kolejkę na diagramie:

  http://myaccount.queue.core.windows.net/incoming-orders

Tworzenie konta usługi Azure Storage

Najprostszym sposobem utworzenia pierwszego konta usługi Azure Storage jest użycie witryny Azure Portal. Więcej informacji można znaleźć w temacie Tworzenie konta usług magazynowych.

Konto usługi Azure Storage można również utworzyć przy użyciu programu Azure PowerShell, interfejsu wiersza polecenia platformy Azurelub dostawcy zasobów usługi Azure Storage dla platformy .NET.

Jeśli w tej chwili nie chcesz tworzyć konta magazynu na platformie Azure, możesz również użyć emulatora magazynu Azurite do uruchomienia i przetestowania kodu w środowisku lokalnym. Aby uzyskać więcej informacji, zobacz Use the Azurite emulator for local Azure Storage development (Używanie emulatora Azurite do lokalnego programowania w usłudze Azure Storage).

Tworzenie aplikacji Java

Najpierw sprawdź, czy system deweloperów spełnia wymagania wstępne wymienione w bibliotece klienta usługi Azure Queue Storage w wersji 12 dla języka Java.

Aby utworzyć aplikację Java o nazwie queues-how-to-v12:

1. W oknie konsoli (takim jak cmd, PowerShell lub Bash) użyj narzędzia Maven, aby utworzyć nową aplikację konsolową o nazwie queues-how-to-v12. Wpisz następujące mvn polecenie, aby utworzyć projekt Java "hello world".

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

   mvn archetype:generate `
       --define interactiveMode=n `
       --define groupId=com.queues.howto `
       --define artifactId=queues-howto-v12 `
       --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.howto
   [INFO] Parameter: artifactId, Value: queues-howto-v12
   [INFO] Parameter: version, Value: 1.0-SNAPSHOT
   [INFO] Parameter: package, Value: com.queues.howto
   [INFO] Parameter: packageInPathFormat, Value: com/queues/howto
   [INFO] Parameter: version, Value: 1.0-SNAPSHOT
   [INFO] Parameter: package, Value: com.queues.howto
   [INFO] Parameter: groupId, Value: com.queues.howto
   [INFO] Parameter: artifactId, Value: queues-howto-v12
   [INFO] Project created from Archetype in dir: C:\queues\queues-howto-v12
   [INFO] ------------------------------------------------------------------------
   [INFO] BUILD SUCCESS
   [INFO] ------------------------------------------------------------------------
   [INFO] Total time:  6.775 s
   [INFO] Finished at: 2020-08-17T15:27:31-07:00
   [INFO] ------------------------------------------------------------------------
   

3. Przejdź do nowo utworzonego queues-howto-v12 katalogu.

   cd queues-howto-v12
   

Instalowanie pakietu

pom.xml Otwórz plik w edytorze tekstów. Dodaj następujący element zależności do grupy zależności.

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

Konfigurowanie aplikacji w celu uzyskania dostępu do usługi Queue Storage

Dodaj następujące instrukcje importowania na początku pliku Java, w którym chcesz używać interfejsów API usługi Azure Storage do uzyskiwania dostępu do kolejek:

// Include the following imports to use queue APIs
import com.azure.core.util.*;
import com.azure.storage.queue.*;
import com.azure.storage.queue.models.*;

Konfigurowanie stringu połączenia usługi Azure Storage

Klient usługi Azure Storage używa parametrów połączenia magazynu do uzyskiwania dostępu do usług zarządzania danymi. Pobierz nazwę i podstawowy klucz dostępu dla konta magazynu wymienionego w Azure Portal. Użyj ich jako AccountName wartości i AccountKey w parametrach połączenia. W tym przykładzie pokazano, jak można zadeklarować pole statyczne w celu przechowywania parametrów połączenia:

// Define the connection-string with your values
final String connectStr = 
    "DefaultEndpointsProtocol=https;" +
    "AccountName=your_storage_account;" +
    "AccountKey=your_storage_account_key";

W poniższych przykładach przyjęto założenie, że masz String obiekt zawierający parametry połączenia magazynu.

Instrukcje: tworzenie kolejki

Obiekt QueueClient zawiera operacje interakcji z kolejką. Poniższy kod tworzy QueueClient obiekt. Użyj obiektu , QueueClient aby utworzyć kolejkę, której chcesz użyć.

public static String createQueue(String connectStr)
{
    try
    {
        // Create a unique name for the queue
        String queueName = "queue-" + java.util.UUID.randomUUID();

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

        // Instantiate a QueueClient which will be
        // used to create and manipulate the queue
        QueueClient queue = new QueueClientBuilder()
                                .connectionString(connectStr)
                                .queueName(queueName)
                                .buildClient();

        // Create the queue
        queue.create();
        return queue.getQueueName();
    }
    catch (QueueStorageException e)
    {
        // Output the exception message and stack trace
        System.out.println("Error code: " + e.getErrorCode() + "Message: " + e.getMessage());
        return null;
    }
}

Jak dodać komunikat do kolejki

Aby wstawić komunikat do istniejącej kolejki, wywołaj metodę sendMessage. Komunikat może być ciągiem (w formacie UTF-8) lub tablicą bajtów. Oto kod, który wysyła komunikat tekstowy do kolejki.

public static void addQueueMessage
    (String connectStr, String queueName, String messageText)
{
    try
    {
        // Instantiate a QueueClient which will be
        // used to create and manipulate the queue
        QueueClient queueClient = new QueueClientBuilder()
                                    .connectionString(connectStr)
                                    .queueName(queueName)
                                    .buildClient();

        System.out.println("Adding message to the queue: " + messageText);

        // Add a message to the queue
        queueClient.sendMessage(messageText);
    }
    catch (QueueStorageException e)
    {
        // Output the exception message and stack trace
        System.out.println(e.getMessage());
        e.printStackTrace();
    }
}

Instrukcje: Zobacz następną wiadomość

Możesz spojrzeć na komunikat znajdujący się na początku kolejki bez usuwania go z kolejki, wywołując metodę peekMessage.

public static void peekQueueMessage
    (String connectStr, String queueName)
{
    try
    {
        // Instantiate a QueueClient which will be
        // used to create and manipulate the queue
        QueueClient queueClient = new QueueClientBuilder()
                                    .connectionString(connectStr)
                                    .queueName(queueName)
                                    .buildClient();

        // Peek at the first message
        PeekedMessageItem peekedMessageItem = queueClient.peekMessage();
        System.out.println("Peeked message: " + peekedMessageItem.getMessageText());
    }
    catch (QueueStorageException e)
    {
        // Output the exception message and stack trace
        System.out.println(e.getMessage());
        e.printStackTrace();
    }
}

Instrukcje: zmienianie zawartości komunikatu w kolejce

Zawartość komunikatu można zmienić w kolejce. Jeśli komunikat reprezentuje zadanie robocze, możesz użyć tej funkcji do zaktualizowania stanu. Poniższy kod aktualizuje komunikat kolejki o nowej zawartości i ustawia limit czasu widoczności, aby przedłużyć kolejne 30 sekund. Wydłużenie limitu czasu widoczności daje klientowi kolejne 30 sekund, aby kontynuować pracę nad komunikatem. Można również zachować liczbę ponownych prób. Jeśli komunikat jest ponawiany więcej niż n razy, należy go usunąć. Ten scenariusz chroni przed komunikatem, który wyzwala błąd aplikacji za każdym razem, gdy jest przetwarzany.

Poniższy przykładowy kod wyszukuje w kolejce komunikatów, lokalizuje pierwszą zawartość komunikatu zgodną z ciągiem wyszukiwania, modyfikuje zawartość komunikatu i kończy działanie.

public static void updateQueueMessage
    (String connectStr, String queueName,
    String searchString, String updatedContents)
{
    try
    {
        // Instantiate a QueueClient which will be
        // used to create and manipulate the queue
        QueueClient queueClient = new QueueClientBuilder()
                                    .connectionString(connectStr)
                                    .queueName(queueName)
                                    .buildClient();

        // The maximum number of messages to retrieve is 32
        final int MAX_MESSAGES = 32;

        // Iterate through the queue messages
        for (QueueMessageItem message : queueClient.receiveMessages(MAX_MESSAGES))
        {
            // Check for a specific string
            if (message.getMessageText().equals(searchString))
            {
                // Update the message to be visible in 30 seconds
                queueClient.updateMessage(message.getMessageId(),
                                          message.getPopReceipt(),
                                          updatedContents,
                                          Duration.ofSeconds(30));
                System.out.println(
                    String.format("Found message: \'%s\' and updated it to \'%s\'",
                                    searchString,
                                    updatedContents)
                                  );
                break;
            }
        }
    }
    catch (QueueStorageException e)
    {
        // Output the exception message and stack trace
        System.out.println(e.getMessage());
        e.printStackTrace();
    }
}

Poniższy przykładowy kod aktualizuje tylko pierwszy widoczny komunikat w kolejce.

public static void updateFirstQueueMessage
    (String connectStr, String queueName, String updatedContents)
{
    try
    {
        // Instantiate a QueueClient which will be
        // used to create and manipulate the queue
        QueueClient queueClient = new QueueClientBuilder()
                                    .connectionString(connectStr)
                                    .queueName(queueName)
                                    .buildClient();

        // Get the first queue message
        QueueMessageItem message = queueClient.receiveMessage();

        // Check for a specific string
        if (null != message)
        {
            // Update the message to be visible in 30 seconds
            UpdateMessageResult result = queueClient.updateMessage(message.getMessageId(),
                                                                   message.getPopReceipt(),
                                                                   updatedContents,
                                                                   Duration.ofSeconds(30));
            System.out.println("Updated the first message with the receipt: " +
                    result.getPopReceipt());
        }
    }
    catch (QueueStorageException e)
    {
        // Output the exception message and stack trace
        System.out.println(e.getMessage());
        e.printStackTrace();
    }
}

Instrukcje: uzyskiwanie długości kolejki

Możesz oszacować ilość 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.

public static void getQueueLength(String connectStr, String queueName)
{
    try
    {
        // Instantiate a QueueClient which will be
        // used to create and manipulate the queue
        QueueClient queueClient = new QueueClientBuilder()
                                    .connectionString(connectStr)
                                    .queueName(queueName)
                                    .buildClient();

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

        System.out.println(String.format("Queue length: %d", messageCount));
    }
    catch (QueueStorageException e)
    {
        // Output the exception message and stack trace
        System.out.println(e.getMessage());
        e.printStackTrace();
    }
}

Jak: Wypisać/Usunąć z kolejki następną wiadomość

Twój kod usuwa komunikat z kolejki w dwóch krokach. Po wywołaniu receiveMessage, zostanie wyświetlony następny komunikat w kolejce. Komunikat zwrócony z receiveMessage staje się niewidoczny dla jakiegokolwiek innego kodu odczytującego wiadomości z tej kolejki. Domyślnie komunikat pozostanie niewidoczny przez 30 sekund. Aby zakończyć usuwanie komunikatu z kolejki, należy również wywołać metodę deleteMessage. Jeśli kod nie może przetworzyć komunikatu, ten dwuetapowy proces gwarantuje, że możesz uzyskać ten sam komunikat i spróbować ponownie. Twój kod wywołuje deleteMessage, bezpośrednio po przetworzeniu wiadomości.

public static void dequeueMessage(String connectStr, String queueName)
{
    try
    {
        // Instantiate a QueueClient which will be
        // used to create and manipulate the queue
        QueueClient queueClient = new QueueClientBuilder()
                                    .connectionString(connectStr)
                                    .queueName(queueName)
                                    .buildClient();

        // Get the first queue message
        QueueMessageItem message = queueClient.receiveMessage();

        // Check for a specific string
        if (null != message)
        {
            System.out.println("Dequeing message: " + message.getMessageText());

            // Delete the message
            queueClient.deleteMessage(message.getMessageId(), message.getPopReceipt());
        }
        else
        {
            System.out.println("No visible messages in queue");
        }
    }
    catch (QueueStorageException e)
    {
        // Output the exception message and stack trace
        System.out.println(e.getMessage());
        e.printStackTrace();
    }
}

Dodatkowe opcje odkolejkowywania komunikatów

Istnieją dwa sposoby dostosowywania pobierania komunikatów z kolejki. Najpierw pobierz partię wiadomości (do 32). Po drugie, ustaw dłuższy lub krótszy limit czasu niewidoczności, co pozwala twojemu kodowi mieć więcej lub mniej czasu na pełne przetworzenie każdego komunikatu.

W poniższym przykładzie kodu użyto metody receiveMessages, aby pobrać 20 wiadomości w jednym wywołaniu. Następnie przetwarza każdy komunikat przy użyciu for pętli. Ustawia również limit czasu widoczności na pięć minut (300 sekund) dla każdego komunikatu. Czas oczekiwania rozpoczyna się dla wszystkich komunikatów jednocześnie. Po upływie pięciu minut od wywołania metody receiveMessages, wszystkie komunikaty, które nie zostały usunięte, staną się widoczne ponownie.

public static void dequeueMessages(String connectStr, String queueName)
{
    try
    {
        // Instantiate a QueueClient which will be
        // used to create and manipulate the queue
        QueueClient queueClient = new QueueClientBuilder()
                                    .connectionString(connectStr)
                                    .queueName(queueName)
                                    .buildClient();

        // The maximum number of messages to retrieve is 20
        final int MAX_MESSAGES = 20;

        // Retrieve 20 messages from the queue with a
        // visibility timeout of 300 seconds (5 minutes)
        for (QueueMessageItem message : queueClient.receiveMessages(MAX_MESSAGES,
                Duration.ofSeconds(300), Duration.ofSeconds(1), new Context("key1", "value1")))
        {
            // Do processing for all messages in less than 5 minutes,
            // deleting each message after processing.
            System.out.println("Dequeing message: " + message.getMessageText());
            queueClient.deleteMessage(message.getMessageId(), message.getPopReceipt());
        }
    }
    catch (QueueStorageException e)
    {
        // Output the exception message and stack trace
        System.out.println(e.getMessage());
        e.printStackTrace();
    }
}

Instrukcje: wyświetlanie listy kolejek

Aby uzyskać listę bieżących kolejek, wywołaj QueueServiceClient.listQueues() metodę , która zwróci kolekcję QueueItem obiektów.

public static void listQueues(String connectStr)
{
    try
    {
        // Instantiate a QueueServiceClient which will be
        // used to list the queues
        QueueServiceClient queueServiceClient = new QueueServiceClientBuilder()
                                    .connectionString(connectStr)
                                    .buildClient();

        // Loop through the collection of queues.
        for (QueueItem queue : queueServiceClient.listQueues())
        {
            // Output each queue name.
            System.out.println(queue.getName());
        }
    }
    catch (QueueStorageException e)
    {
        // Output the exception message and stack trace
        System.out.println(e.getMessage());
        e.printStackTrace();
    }
}

Jak usunąć kolejkę

Aby usunąć kolejkę i wszystkie zawarte w niej komunikaty, wywołaj metodę delete w QueueClient obiekcie .

public static void deleteMessageQueue(String connectStr, String queueName)
{
    try
    {
        // Instantiate a QueueClient which will be
        // used to create and manipulate the queue
        QueueClient queueClient = new QueueClientBuilder()
                                    .connectionString(connectStr)
                                    .queueName(queueName)
                                    .buildClient();

        System.out.println("Deleting queue: " + queueClient.getQueueName());

        // Delete the queue
        queueClient.delete();
    }
    catch (QueueStorageException e)
    {
        // Output the exception message and stack trace
        System.out.println(e.getMessage());
        e.printStackTrace();
    }
}

Dalsze kroki

Teraz, gdy znasz już podstawy usługi Queue Storage, skorzystaj z tych linków, aby dowiedzieć się więcej o bardziej skomplikowanych zadaniach związanych z magazynowaniem.

• zestaw SDK usługi Azure Storage dla języka Java
• Dokumentacja zestawu SDK klienta usługi Azure Storage
• Interfejs API REST usług Azure Storage
• Blog zespołu usługi Azure Storage

Aby uzyskać powiązane przykłady kodu korzystające z przestarzałych zestawów SDK języka Java w wersji 8, zobacz Przykłady kodu korzystające z języka Java w wersji 8.