Jak używać usługi Queue Storage z poziomu języka Java
Omówienie
W tym przewodniku pokazano, jak kodować typowe scenariusze przy użyciu usługi Azure Queue Storage. Przykłady zostały napisane w języku Java i wymagają użycia zestawu SDK usługi Azure Storage dla języka Java. Scenariusze obejmują wstawianie, podgląd, pobieranie i usuwanie komunikatów w kolejce. Omówiony jest 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órej można uzyskać dostęp z dowolnego miejsca na świecie za pośrednictwem uwierzytelnionego połączenia za pomocą protokołu HTTP lub HTTPS. Pojedynczy komunikat z kolejki nie może przekraczać 64 KB, a kolejka może zawierać miliony komunikatów — maksymalnie liczbę nieprzekraczającą całkowitego limitu pojemności konta magazynu. Usługa Queue Storage jest często używana do tworzenia listy prac w celu przetwarzania asynchronicznego.
Pojęcia dotyczące usługi kolejki
Usługa Azure Queue service zawiera następujące składniki:
Konto magazynu: cały dostęp do usługi Azure Storage odbywa się przez konto 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. 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 wygaśnie. 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://
<storage account>.queue.core.windows.net/<queue>Następujący adres URL dotyczy kolejki w schemacie:
http://myaccount.queue.core.windows.net/incoming-orders
Tworzenie konta usługi Azure Storage
Najprościej jest utworzyć pierwsze konto usługi Azure Storage przy użyciu witryny Azure Portal. Więcej informacji można znaleźć w temacie Tworzenie konta magazynu.
Można również utworzyć konto usługi Azure Storage przy użyciu programu Azure PowerShell, interfejsu wiersza polecenia Azure lub 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, aby uruchomić i przetestować kod 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:
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ącemvnpolecenie, 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.4mvn archetype:generate ` --define interactiveMode=n ` --define groupId=com.queues.howto ` --define artifactId=queues-howto-v12 ` --define archetypeArtifactId=maven-archetype-quickstart ` --define archetypeVersion=1.4Dane 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] ------------------------------------------------------------------------Przejdź do nowo utworzonego
queues-howto-v12katalogu.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 do góry 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 parametrów 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 założono, że masz String obiekt zawierający parametry połączenia magazynu.
Instrukcje: tworzenie kolejki
QueueClient Obiekt 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;
}
}
Instrukcje: dodawanie komunikatu 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 ciągu 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: Przeglądanie następnego komunikatu
Komunikat można wyświetlić przed kolejką bez usuwania jej z kolejki, wywołując polecenie 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
Możesz zmienić zawartość komunikatu w kolejce. Jeśli komunikat reprezentuje zadanie pracy, 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 kolejkę 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 uzyskać szacunkową liczbę komunikatów 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 dodać lub usunąć po żądaniu. Metoda getApproximateMessageCount zwraca ostatnią wartość pobraną przez wywołanie metody , getPropertiesbez 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();
}
}
Instrukcje: dequeue następnej wiadomości
Kod dequeuuje komunikat z kolejki w dwóch krokach. Po wywołaniu metody receiveMessagezostanie wyświetlony następny komunikat w kolejce. Komunikat zwrócony z receiveMessage staje się niewidoczny dla każdego innego kodu odczytujących komunikaty 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 będzie można uzyskać ten sam komunikat i spróbować ponownie. Kod wywołuje się deleteMessage bezpośrednio po przetworzeniu komunikatu.
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 usuwania komunikatów w kolejce
Istnieją dwa sposoby dostosowywania pobierania komunikatów z kolejki. Najpierw pobierz partię komunikatów (do 32). Po drugie ustaw dłuższy lub krótszy limit czasu widoczności, dzięki czemu kod może w pełni przetworzyć każdy komunikat.
Poniższy przykład kodu używa receiveMessages metody , aby uzyskać 20 komunikatów 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. Limit czasu jest uruchamiany dla wszystkich komunikatów w tym samym czasie. 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();
}
}
Instrukcje: usuwanie kolejki
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();
}
}
Porada
Zapoznaj się z repozytorium przykładów kodu usługi Azure Storage
Nasza lista przykładów usługi Azure Storage zawiera łatwe w użyciu kompleksowe przykłady kodu usługi Azure Storage, które można pobierać i uruchamiać.
Następne kroki
Teraz, gdy znasz już podstawy usługi Queue Storage, skorzystaj z tych linków, aby dowiedzieć się więcej o bardziej złożonych zadaniach magazynu.
- 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 zapoznać się z powiązanymi przykładami kodu korzystającymi z przestarzałych zestawów SDK języka Java w wersji 8, zobacz Przykłady kodu przy użyciu języka Java w wersji 8.