Bibliothèque cliente file d’attente stockage Azure pour Java - version 12.19.1
Les files d’attente de stockage Azure sont un service permettant de stocker un grand nombre de messages accessibles depuis n’importe où dans le monde via des appels authentifiés avec HTTP ou HTTPS. Un simple message de file d’attente peut avoir une taille de 64 Ko et une file d’attente peut contenir des millions de messages, jusqu’à la limite de capacité totale d’un compte de stockage.
Code source | Documentation de référence de l’API | Documentation du produit | Exemples
Prise en main
Prérequis
- Kit de développement Java (JDK) avec la version 8 ou ultérieure
- Abonnement Azure
- Créer un compte de stockage
Inclure le package
Inclure le fichier de nomenclature
Incluez azure-sdk-bom dans votre projet pour dépendre de la version ga de la bibliothèque. Dans l’extrait de code suivant, remplacez l’espace réservé {bom_version_to_target} par le numéro de version. Pour en savoir plus sur la nomenclature, consultez le README BOM du KIT DE DÉVELOPPEMENT LOGICIEL AZURE.
<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>
Incluez ensuite la dépendance directe dans la section des dépendances sans la balise de version.
<dependencies>
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-storage-queue</artifactId>
</dependency>
</dependencies>
Inclure une dépendance directe
Si vous souhaitez dépendre d’une version particulière de la bibliothèque qui n’est pas présente dans la nomenclature, ajoutez la dépendance directe à votre projet comme suit.
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-storage-queue</artifactId>
<version>12.19.1</version>
</dependency>
Créer un compte de stockage
Pour créer un compte de stockage, vous pouvez utiliser le portail Azure ou Azure CLI.
az storage account create \
--resource-group <resource-group-name> \
--name <storage-account-name> \
--location <location>
Authentifier le client
Pour interagir avec le service de stockage (Blob, File d’attente, Message, MessageId, Fichier), vous devez créer un instance de la classe Service Client. Pour ce faire, vous aurez besoin de la chaîne SAS de compte (signature d’accès partagé) du compte de stockage. Pour en savoir plus, consultez Jeton SAS
Obtenir des informations d’identification
- Jeton SAS
a. Utilisez l’extrait de code Azure CLI ci-dessous pour obtenir le jeton SAS à partir du compte de stockage.
az storage queue generate-sas
--name {queue name}
--expiry {date/time to expire SAS token}
--permission {permission to grant}
--connection-string {connection string of the storage account}
CONNECTION_STRING=<connection-string>
az storage queue generate-sas
--name javasdksas
--expiry 2019-06-05
--permission rpau
--connection-string $CONNECTION_STRING
b. Vous pouvez également obtenir le jeton SAP du compte à partir du portail Azure.
Go to your storage account -> Shared access signature -> Click on Generate SAS and connection string (after setup)
- Informations d’identification de clé partagée
a. Utilisez le nom du compte et la clé de compte. Nom du compte est le nom de votre compte de stockage.
// Here is where we get the key
Go to your storage account -> Access keys -> Key 1/ Key 2 -> Key
b. Utiliser le chaîne de connexion
// Here is where we get the key
Go to your storage account -> Access Keys -> Keys 1/ Key 2 -> Connection string
Concepts clés
Format d’URL
Les files d’attente sont adressables au format d’URL suivant : L’URL suivante traite une file d’attente dans le diagramme : https://myaccount.queue.core.windows.net/images-to-download
Syntaxe d'URI de ressource
Pour le compte de stockage, l'URI de base pour les opérations de file d'attente comprend uniquement le nom du compte :
https://myaccount.queue.core.windows.net
Pour une file d'attente, l'URI de base comprend le nom du compte et le nom de la file d'attente :
https://myaccount.queue.core.windows.net/myqueue
Gestion des exceptions
Utilise le généré à partir de la queueServiceClient section Client du service de file d’attente ci-dessous.
String queueServiceURL = String.format("https://%s.queue.core.windows.net", ACCOUNT_NAME);
QueueServiceClient queueServiceClient = new QueueServiceClientBuilder().endpoint(queueServiceURL)
.sasToken(SAS_TOKEN).buildClient();
try {
queueServiceClient.createQueue("myQueue");
} catch (QueueStorageException e) {
logger.error("Failed to create a queue with error code: " + e.getErrorCode());
}
Noms de file d'attente
Chaque file d'attente dans un compte doit avoir un nom unique. Le nom de file d'attente doit être un nom DNS valide et ne peut pas être modifié une fois créé. Les noms de file d'attente doivent respecter les règles suivantes :
- un nom de file d'attente doit commencer par une lettre ou un chiffre et ne peut contenir que des lettres, des chiffres et le tiret (-) ;
- la première et la dernière lettre du nom de file d'attente doivent être alphanumériques ; le tiret (-) ne peut pas être en première ou en dernière position ; les tirets consécutifs ne sont pas autorisés dans les noms de file d'attente ;
- toutes les lettres d'un nom de file d'attente doivent être en minuscules ;
- un nom de file d'attente doit comprendre entre 3 et 63 caractères.
Queue Services (Services File d’attente)
Le service de file d’attente effectue des opérations sur les files d’attente dans le compte de stockage et gère les propriétés de la file d’attente.
Client du service de file d’attente
Le client effectue les interactions avec le service file d’attente, crée ou supprime une file d’attente, obtient et configure les propriétés de file d’attente, répertorie les files d’attente dans le compte et obtient des statistiques de file d’attente. Un client asynchrone, QueueServiceAsyncClientet synchrone, QueueClient, existe dans le KIT de développement logiciel (SDK) permettant la sélection d’un client en fonction du cas d’usage d’une application.
Une fois que vous avez la valeur de SASToken, vous pouvez créer le client de service de file d’attente avec ${accountName}, ${SASToken}.
String queueServiceURL = String.format("https://%s.queue.core.windows.net", ACCOUNT_NAME);
QueueServiceClient queueServiceClient = new QueueServiceClientBuilder().endpoint(queueServiceURL)
.sasToken(SAS_TOKEN).buildClient();
QueueClient newQueueClient = queueServiceClient.createQueue("myQueue");
ou
String queueServiceAsyncURL = String.format("https://%s.queue.core.windows.net/", ACCOUNT_NAME);
QueueServiceAsyncClient queueServiceAsyncClient = new QueueServiceClientBuilder().endpoint(queueServiceAsyncURL)
.sasToken(SAS_TOKEN).buildAsyncClient();
queueServiceAsyncClient.createQueue("newAsyncQueue").subscribe(result -> {
// do something when new queue created
}, error -> {
// do something if something wrong happened
}, () -> {
// completed, do something
});
File d'attente
Les files d’attente de stockage Azure sont un service permettant de stocker un grand nombre de messages accessibles depuis n’importe où dans le monde via des appels authentifiés avec HTTP ou HTTPS. Un simple message de file d’attente peut avoir une taille de 64 Ko et une file d’attente peut contenir des millions de messages, jusqu’à la limite de capacité totale d’un compte de stockage.
QueueClient
Une fois que vous avez la valeur de SASToken, vous pouvez créer le client de service de file d’attente avec ${accountName}, ${queueName}, ${SASToken}.
String queueURL = String.format("https://%s.queue.core.windows.net/%s", ACCOUNT_NAME, queueName);
QueueClient queueClient = new QueueClientBuilder().endpoint(queueURL).sasToken(SAS_TOKEN).buildClient();
// metadata is map of key-value pair
queueClient.createWithResponse(metadata, Duration.ofSeconds(30), Context.NONE);
ou
// Only one "?" is needed here. If the sastoken starts with "?", please removing one "?".
String queueAsyncURL = String.format("https://%s.queue.core.windows.net/%s?%s", ACCOUNT_NAME, queueAsyncName,
SAS_TOKEN);
QueueAsyncClient queueAsyncClient = new QueueClientBuilder().endpoint(queueAsyncURL).buildAsyncClient();
queueAsyncClient.createWithResponse(metadata).subscribe(result -> {
// do something when new queue created
}, error -> {
// do something if something wrong happened
}, () -> {
// completed, do something
});
Exemples
Les sections suivantes fournissent plusieurs extraits de code couvrant certaines des tâches de service de configuration les plus courantes, notamment :
- Créer un client
- Créer une file d’attente
- Supprimer une file d’attente
- Répertorier les files d’attente dans le compte
- Obtenir les propriétés dans le compte de file d’attente
- Définir les propriétés dans le compte de file d’attente
- Obtenir des statistiques de file d’attente
- Mettre un message de file d’attente dans une file d’attente
- Mettre à jour un message dans une file d’attente
- Afficher un aperçu des messages d’une file d’attente
- Recevoir les messages d’une file d’attente
- Supprimer un message d’une file d’attente
- Obtenir les propriétés d’une file d’attente
- Définir/mettre à jour les métadonnées d’une file d’attente
Créer un client
Nous avons deux façons de générer QueueService ou Queue Client. Voici un exemple de file d’attenteServiceClient. Les mêmes choses s’appliquent à queueClient.
Tout d’abord, générez le client à partir de l’URL/du point de terminaison complet (par exemple, avec queueName, avec SASToken, etc.)
// Only one "?" is needed here. If the sastoken starts with "?", please removing one "?".
String queueServiceURL = String.format("https://%s.queue.core.windows.net/?%s", ACCOUNT_NAME, SAS_TOKEN);
QueueServiceClient queueServiceClient = new QueueServiceClientBuilder().endpoint(queueServiceURL).buildClient();
ou
Nous pouvons générer le service queueServiceClient à partir du générateur en utilisant ${SASToken} comme informations d’identification.
String queueServiceURL = String.format("https://%s.queue.core.windows.net", ACCOUNT_NAME);
QueueServiceClient queueServiceClient = new QueueServiceClientBuilder().endpoint(queueServiceURL)
.sasToken(SAS_TOKEN).buildClient();
Créer une file d’attente
Créez une file d’attente dans le compte de stockage en utilisant ${SASToken} comme informations d’identification.
Lève StorageException Si la file d’attente ne parvient pas à être créée.
String queueServiceURL = String.format("https://%s.queue.core.windows.net", ACCOUNT_NAME);
QueueServiceClient queueServiceClient = new QueueServiceClientBuilder().endpoint(queueServiceURL)
.sasToken(SAS_TOKEN).buildClient();
QueueClient newQueueClient = queueServiceClient.createQueue("myQueue");
Suppression d'une file d'attente
Supprimez une file d’attente dans le compte de stockage en utilisant ${SASToken} comme informations d’identification.
Lève StorageException si la file d’attente ne parvient pas à être supprimée.
String queueServiceURL = String.format("https://%s.queue.core.windows.net", ACCOUNT_NAME);
QueueServiceClient queueServiceClient = new QueueServiceClientBuilder().endpoint(queueServiceURL)
.sasToken(SAS_TOKEN).buildClient();
queueServiceClient.deleteQueue("myqueue");
Répertorier les files d’attente dans le compte
Répertoriez toutes les files d’attente du compte en utilisant ${SASToken} comme informations d’identification.
String queueServiceURL = String.format("https://%s.queue.core.windows.net", ACCOUNT_NAME);
QueueServiceClient queueServiceClient = new QueueServiceClientBuilder().endpoint(queueServiceURL)
.sasToken(SAS_TOKEN).buildClient();
// @param marker: Starting point to list the queues
// @param options: Filter for queue selection
// @param timeout: An optional timeout applied to the operation.
// @param context: Additional context that is passed through the Http pipeline during the service call.
queueServiceClient.listQueues(options, timeout, context).stream().forEach(queueItem ->
System.out.printf("Queue %s exists in the account.", queueItem.getName()));
Obtenir les propriétés du compte de file d’attente
Obtenez les propriétés de file d’attente dans le compte, y compris les propriétés pour les règles Storage Analytics et CORS (Cross-Origin Resource Sharing).
Utilisez ${SASToken} comme informations d’identification.
String queueServiceURL = String.format("https://%s.queue.core.windows.net", ACCOUNT_NAME);
QueueServiceClient queueServiceClient = new QueueServiceClientBuilder().endpoint(queueServiceURL)
.sasToken(SAS_TOKEN).buildClient();
QueueServiceProperties properties = queueServiceClient.getProperties();
Définir des propriétés dans le compte de file d’attente
Définissez les propriétés de file d’attente dans le compte, y compris les propriétés pour les règles Storage Analytics et CORS (Cross-Origin Resource Sharing).
Utilisez ${SASToken} comme informations d’identification.
String queueServiceURL = String.format("https://%s.queue.core.windows.net", ACCOUNT_NAME);
QueueServiceClient queueServiceClient = new QueueServiceClientBuilder().endpoint(queueServiceURL)
.sasToken(SAS_TOKEN).buildClient();
QueueServiceProperties properties = queueServiceClient.getProperties();
properties.setCors(Collections.emptyList());
queueServiceClient.setProperties(properties);
Obtenir les statistiques du service de file d’attente
L'opération Get Queue Service Stats récupère des statistiques relatives à la réplication pour le service de File d'attente.
Utilisez ${SASToken} comme informations d’identification.
Elle est uniquement disponible sur le point de terminaison d'emplacement secondaire lorsque la réplication géographique redondante avec accès en lecture est activée pour le compte de stockage.
String queueServiceURL = String.format("https://%s.queue.core.windows.net", ACCOUNT_NAME);
QueueServiceClient queueServiceClient = new QueueServiceClientBuilder().endpoint(queueServiceURL)
.sasToken(SAS_TOKEN).buildClient();
QueueServiceStatistics queueStats = queueServiceClient.getStatistics();
Mettre en file d’attente un message dans une file d’attente
L’opération ajoute un nouveau message à l’arrière de la file d’attente de messages. Un délai de visibilité peut également être spécifié afin que le message soit invisible tant que ce délai n'a pas été expiré.
Utilisez ${SASToken} comme informations d’identification.
Un message doit être dans un format qui peut être inclus dans une demande XML en UTF-8. La taille du message encodé ne peut pas dépasser 64 Ko pour les versions postérieures au 18/08/2011 et 8 Ko pour les versions antérieures.
String queueURL = String.format("https://%s.queue.core.windows.net", ACCOUNT_NAME);
QueueClient queueClient = new QueueClientBuilder().endpoint(queueURL).sasToken(SAS_TOKEN).queueName("myqueue")
.buildClient();
queueClient.sendMessage("myMessage");
Mettre à jour un message dans une file d’attente
L’opération met à jour un message dans la file d’attente des messages. Utilisez ${SASToken} comme informations d’identification.
String queueURL = String.format("https://%s.queue.core.windows.net", ACCOUNT_NAME);
QueueClient queueClient = new QueueClientBuilder().endpoint(queueURL).sasToken(SAS_TOKEN).queueName("myqueue")
.buildClient();
// @param messageId: Id of the message
// @param popReceipt: Unique identifier that must match the message for it to be updated
// @param visibilityTimeout: How long the message will be invisible in the queue in seconds
queueClient.updateMessage(messageId, popReceipt, "new message", visibilityTimeout);
Afficher un aperçu des messages d’une file d’attente
L’opération effectue un aperçu d’un ou plusieurs messages à partir de l’avant de la file d’attente. Utilisez ${SASToken} comme informations d’identification.
String queueURL = String.format("https://%s.queue.core.windows.net", ACCOUNT_NAME);
QueueClient queueClient = new QueueClientBuilder().endpoint(queueURL).sasToken(SAS_TOKEN).queueName("myqueue")
.buildClient();
// @param key: The key with which the specified value should be associated.
// @param value: The value to be associated with the specified key.
queueClient.peekMessages(5, Duration.ofSeconds(1), new Context(key, value)).forEach(message ->
System.out.println(message.getBody().toString()));
Réception des messages d'une file d'attente
L’opération récupère un ou plusieurs messages à l’avant de la file d’attente. Utilisez ${SASToken} comme informations d’identification.
String queueURL = String.format("https://%s.queue.core.windows.net", ACCOUNT_NAME);
QueueClient queueClient = new QueueClientBuilder().endpoint(queueURL).sasToken(SAS_TOKEN).queueName("myqueue")
.buildClient();
// Try to receive 10 messages: Maximum number of messages to get
queueClient.receiveMessages(10).forEach(message ->
System.out.println(message.getBody().toString()));
Supprimer un message d’une file d’attente
L’opération supprime un message de la file d’attente. Utilisez ${SASToken} comme informations d’identification.
String queueURL = String.format("https://%s.queue.core.windows.net", ACCOUNT_NAME);
QueueClient queueClient = new QueueClientBuilder().endpoint(queueURL).sasToken(SAS_TOKEN).queueName("myqueue")
.buildClient();
queueClient.deleteMessage(messageId, popReceipt);
Obtenir les propriétés d’une file d’attente
L’opération récupère les métadonnées définies par l’utilisateur et les propriétés de file d’attente sur la file d’attente spécifiée. Les métadonnées sont associées à la file d'attente en tant que paires nom-valeur.
Utilisez ${SASToken} comme informations d’identification.
String queueURL = String.format("https://%s.queue.core.windows.net", ACCOUNT_NAME);
QueueClient queueClient = new QueueClientBuilder().endpoint(queueURL).sasToken(SAS_TOKEN).queueName("myqueue")
.buildClient();
QueueProperties properties = queueClient.getProperties();
Définir les métadonnées d’une file d’attente
L’opération définit les métadonnées définies par l’utilisateur sur la file d’attente spécifiée. Les métadonnées sont associées à la file d'attente en tant que paires nom-valeur.
Utilisez ${SASToken} comme informations d’identification.
String queueURL = String.format("https://%s.queue.core.windows.net", ACCOUNT_NAME);
QueueClient queueClient = new QueueClientBuilder().endpoint(queueURL).sasToken(SAS_TOKEN).queueName("myqueue")
.buildClient();
Map<String, String> metadata = new HashMap<>();
metadata.put("key1", "val1");
metadata.put("key2", "val2");
queueClient.setMetadata(metadata);
Dépannage
Général
Lorsque vous interagissez avec la file d’attente à l’aide de cette bibliothèque cliente Java, les erreurs retournées par le service correspondent aux mêmes codes status HTTP retournés pour les demandes d’API REST. Par exemple, si vous essayez de récupérer une file d’attente qui n’existe pas dans votre compte de stockage, une 404 erreur est retournée, indiquant Not Found.
Client HTTP par défaut
Toutes les bibliothèques de client utilisent par défaut le client HTTP Netty. L’ajout de la dépendance ci-dessus configure automatiquement la bibliothèque de client pour utiliser le client HTTP Netty. La configuration ou la modification du client HTTP sont détaillées dans le wiki pour clients HTTP.
Bibliothèque SSL par défaut
Toutes les bibliothèques de client utilisent par défaut la bibliothèque BoringSSL Tomcat native pour permettre des performances de niveau natif pour les opérations SSL. La bibliothèque BoringSSL est un fichier uber jar contenant des bibliothèques natives pour Linux/macOS/Windows. Elle offre de meilleures performances que l’implémentation SSL par défaut au sein du JDK. Pour plus d’informations, notamment sur la réduction de la taille des dépendances, consultez la section du wiki consacrée à l’optimisation des performances.
Étapes suivantes
Plusieurs exemples de sdk Java file d’attente de stockage sont disponibles dans le dépôt GitHub du SDK. Ces exemples fournissent un exemple de code pour d’autres scénarios couramment rencontrés lors de l’utilisation de Key Vault :
Étapes suivantes - Exemples
Les exemples sont expliqués en détail ici.
Contribution
Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, visitez https://cla.microsoft.com.
Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat CLA.
Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.
Pour plus d’informations sur la contribution à ce dépôt, consultez le guide de contribution.
- Fork it
- Créer votre branche de fonctionnalité (
git checkout -b my-new-feature) - Valider vos modifications (
git commit -am 'Add some feature') - Push vers la branche (
git push origin my-new-feature) - Créer une demande de tirage
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour