Biblioteca cliente de cola de Azure Storage para Java: versión 12.19.1

  • Artículo

El almacenamiento en cola de Azure es un servicio para almacenar grandes cantidades de mensajes a los que puede obtenerse acceso desde cualquier lugar del mundo a través de llamadas autenticadas con HTTP o HTTPS. Un único mensaje en cola puede tener un tamaño de hasta 64 KB y una cola puede contener millones de mensajes, hasta el límite de capacidad total de una cuenta de almacenamiento.

Código fuente | Documentación de referencia de API | Documentación del producto | Ejemplos

Introducción

Requisitos previos

Inclusión del paquete

Inclusión del archivo BOM

Incluya azure-sdk-bom en el proyecto para que dependa de la versión de disponibilidad general de la biblioteca. En el fragmento de código siguiente, reemplace el marcador de posición {bom_version_to_target} por el número de versión. Para más información sobre la lista de materiales, consulte el archivo Léame bom del SDK de 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>

y, luego, incluya la dependencia directa en la sección de dependencias sin la etiqueta de versión.

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

Inclusión de dependencias directas

Si desea depender de una versión determinada de la biblioteca que no está presente en la lista de materiales, agregue la dependencia directa al proyecto como se indica a continuación.

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

Creación de una cuenta de almacenamiento

Para crear una cuenta de almacenamiento, puede usar Azure Portal o la CLI de Azure.

az storage account create \
    --resource-group <resource-group-name> \
    --name <storage-account-name> \
    --location <location>

Autenticar el cliente

Para interactuar con el servicio Storage (Blob, Queue, Message, MessageId, File), deberá crear una instancia de la clase Service Client. Para que esto sea posible, necesitará la cadena saS de cuenta (firma de acceso compartido) de la cuenta de almacenamiento. Más información en Token de SAS

Get Credentials

  • SAS Token

a. Use el siguiente fragmento de código de la CLI de Azure para obtener el token de SAS de la cuenta de storage.

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. Como alternativa, obtenga el token de SAS de cuenta de Azure Portal.

Go to your storage account -> Shared access signature -> Click on Generate SAS and connection string (after setup)
  • Credencial de clave compartida

a. Use el nombre de cuenta y la clave de cuenta. El nombre de la cuenta es el nombre de la cuenta de almacenamiento.

// Here is where we get the key
Go to your storage account -> Access keys -> Key 1/ Key 2 -> Key

b. Uso del cadena de conexión

// Here is where we get the key
Go to your storage account -> Access Keys -> Keys 1/ Key 2 -> Connection string

Conceptos clave

Formato de dirección URL

Las colas son direccionables con el siguiente formato de dirección URL: La siguiente dirección URL direcciona una cola en el diagrama: https://myaccount.queue.core.windows.net/images-to-download

Sintaxis del URI de recurso

En lo que respecta a la cuenta de almacenamiento, el URI base para las operaciones en la cola incluye solamente el nombre de la cuenta:

https://myaccount.queue.core.windows.net

Si se trata de una cola, el URI base incluye el nombre de la cuenta y el nombre de la cola:

https://myaccount.queue.core.windows.net/myqueue

Controlar las excepciones

Usa la queueServiceClient sección De cliente de Queue Service generada a continuación.

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());
}

Nombres de cola

Cada una de las colas en una cuenta debe tener un nombre único. El nombre de la cola debe ser un nombre de DNS válido y no se puede cambiar una vez se haya creado. Los nombres de cola deben seguir estas reglas:

  1. Un nombre de cola debe comenzar con una letra o un número y solo puede contener letras, números y guiones (-).
  2. La primera y última letra del nombre de la cola debe ser alfanumérica. El guion (-) no puede ser el primer ni el último carácter. No se permite utilizar guiones consecutivos en el nombre de la cola.
  3. Todas las letras de un nombre de cola deben ser minúsculas.
  4. El nombre de cola puede tener entre 3 y 63 caracteres.

Servicios de colas

El servicio queue realiza operaciones en las colas de la cuenta de almacenamiento y administra las propiedades de la cola.

Cliente de Queue Service

El cliente realiza las interacciones con Queue Service, crea o elimina una cola, obtiene y establece propiedades de cola, enumera las colas de la cuenta y obtiene estadísticas de cola. Existe un cliente asincrónico, QueueServiceAsyncClient, y sincrónico QueueClienten el SDK, lo que permite la selección de un cliente en función del caso de uso de una aplicación. Una vez que tenga el valor de SASToken, puede crear el cliente de queue service con ${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");

o

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
});

Cola

El almacenamiento en cola de Azure es un servicio para almacenar grandes cantidades de mensajes a los que puede obtenerse acceso desde cualquier lugar del mundo a través de llamadas autenticadas con HTTP o HTTPS. Un único mensaje en cola puede tener un tamaño de hasta 64 KB y una cola puede contener millones de mensajes, hasta el límite de capacidad total de una cuenta de almacenamiento.

QueueClient

Una vez que tenga el valor de SASToken, puede crear el cliente de queue service con ${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);

o

// 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
});

Ejemplos

En las secciones siguientes se proporcionan varios fragmentos de código que abarcan algunas de las tareas más comunes del servicio de configuración, entre las que se incluyen:

Creación de un cliente

Tenemos dos maneras de compilar QueueService o Queue Client. En este caso, queueServiceClient se usará como ejemplo. Las mismas cosas se aplican a queueClient.

En primer lugar, compile el cliente desde la dirección URL o el punto de conexión completo (por ejemplo, con queueName, con 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();

Or

Podemos compilar queueServiceClient desde el generador mediante ${SASToken} como credencial.

String queueServiceURL = String.format("https://%s.queue.core.windows.net", ACCOUNT_NAME);
QueueServiceClient queueServiceClient = new QueueServiceClientBuilder().endpoint(queueServiceURL)
        .sasToken(SAS_TOKEN).buildClient();

Creación de una cola

Cree una cola en la cuenta de almacenamiento con ${SASToken} como credencial. Inicia StorageException Si no se puede crear la cola.

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");

Eliminación de una cola

Elimine una cola en la cuenta de almacenamiento con ${SASToken} como credencial. Produce StorageException Si la cola no se puede eliminar.

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");

Enumerar colas en la cuenta

Enumere todas las colas de la cuenta con ${SASToken} como credencial.

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()));

Obtención de propiedades en la cuenta de cola

Obtenga las propiedades de la cola en la cuenta, incluidas las propiedades de las reglas de Storage Analytics y CORS (uso compartido de recursos entre orígenes).

Use ${SASToken} como credencial.

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();

Establecimiento de propiedades en la cuenta de cola

Establezca las propiedades de cola en la cuenta, incluidas las propiedades de las reglas de Storage Analytics y CORS (uso compartido de recursos entre orígenes).

Use ${SASToken} como credencial.

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);

Obtención de estadísticas de Queue Service

La operación Get Queue Service Stats recupera las estadísticas relacionadas con la replicación para el servicio Cola.

Use ${SASToken} como credencial. Solo está disponible en el extremo de ubicación secundario cuando está habilitada la replicación con redundancia geográfica con acceso de lectura para la cuenta de almacenamiento.

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();

Poner en cola un mensaje en cola

La operación agrega un nuevo mensaje a la parte posterior de la cola de mensajes. También se puede especificar un tiempo de espera de visibilidad para que el mensaje sea invisible hasta que caduque el tiempo de espera de visibilidad.

Use ${SASToken} como credencial. Un mensaje debe estar en un formato tal que se pueda incluir en una solicitud XML con codificación UTF-8. El mensaje codificado puede tener hasta 64 KB de tamaño para las versiones 2011-08-18 y posteriores, o 8 KB en tamaño para versiones anteriores.

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");

Eliminación de un mensaje de una cola

La operación actualiza un mensaje en la cola de mensajes. Use ${SASToken} como credencial.

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);

Lectura de los mensajes de una cola

La operación busca uno o varios mensajes desde la parte frontal de la cola. Use ${SASToken} como credencial.

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()));

mensajes de una cola

La operación recupera uno o varios mensajes desde la parte frontal de la cola. Use ${SASToken} como credencial.

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()));

Eliminar mensaje de una cola

La operación elimina un mensaje de la cola. Use ${SASToken} como credencial.

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);

Obtención de propiedades de cola

La operación recupera las propiedades de cola y metadatos definidos por el usuario en la cola especificada. Los metadatos se asocian con la cola como pares nombre-valor.

Use ${SASToken} como credencial.

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();

Establecimiento de metadatos de cola

La operación establece metadatos definidos por el usuario en la cola especificada. Los metadatos se asocian con la cola como pares nombre-valor.

Use ${SASToken} como credencial.

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);

Solución de problemas

General

Al interactuar con la cola mediante esta biblioteca cliente de Java, los errores devueltos por el servicio corresponden a los mismos códigos de estado HTTP devueltos para las solicitudes de LA API REST . Por ejemplo, si intenta recuperar una cola que no existe en la cuenta de almacenamiento, se devuelve un 404 error, que indica Not Found.

Cliente HTTP predeterminado

Todas las bibliotecas cliente usan de forma predeterminada el cliente HTTP de Netty. Al agregar la dependencia anterior, se configurará automáticamente la biblioteca cliente para usar el cliente HTTP de Netty. La configuración o el cambio del cliente HTTP se detalla en la wiki de clientes HTTP.

Biblioteca SSL predeterminada

De forma predeterminada, todas las bibliotecas cliente usan la biblioteca Boring SSL nativa de Tomcat para habilitar el rendimiento de nivel nativo para las operaciones SSL. La biblioteca Boring SSL es un archivo uber-jar que contiene bibliotecas nativas para Linux, macOS o Windows, que proporciona un mejor rendimiento en comparación con la implementación SSL predeterminada del JDK. Para obtener más información, incluido cómo reducir el tamaño de las dependencias, consulte la sección optimización del rendimiento de la wiki.

Pasos siguientes

Hay disponibles varios ejemplos del SDK de Java de cola de Storage en el repositorio de GitHub del SDK. Estos ejemplos proporcionan código de ejemplo para escenarios adicionales que se suelen encontrar al trabajar con Key Vault:

Ejemplos de pasos siguientes

Los ejemplos se explican detalladamente aquí.

Contribuciones

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para más detalles, visite https://cla.microsoft.com.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo será necesario que lo haga una vez en todos los repositorios con nuestro CLA.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.

Para más información sobre cómo contribuir a este repositorio, consulte la guía de contribución.

  1. Bifurcación
  2. Creación de la rama de características (git checkout -b my-new-feature)
  3. Confirmar los cambios (git commit -am 'Add some feature')
  4. Inserción en la rama (git push origin my-new-feature)
  5. Creación de una nueva solicitud de incorporación de cambios

Impresiones