Biblioteca de clientes da Fila de Armazenamento do Azure para Java – versão 12.19.1

Artigo
10/25/2023

O armazenamento de filas do Azure é um serviço para armazenamento de um grande número de mensagens que podem ser acessadas de qualquer lugar do mundo por meio de chamadas autenticadas usando HTTP ou HTTPS. Uma única mensagem de fila pode ter até 64 KB de tamanho e uma fila pode conter milhões de mensagens, até o limite de capacidade total de uma conta de armazenamento.

Código-fonte | Documentação de referência da API | Documentação do produto | Exemplos

Introdução

Pré-requisitos

JDK (Java Development Kit) com a versão 8 ou superior
Assinatura do Azure
Criar conta de armazenamento

Incluir o pacote

Incluir o arquivo da BOM

Inclua o azure-sdk-bom em seu projeto para assumir a dependência da versão ga da biblioteca. No trecho a seguir, substitua o espaço reservado {bom_version_to_target} pelo número de versão. Para saber mais sobre o BOM, consulte o BOM README do SDK do 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>

Depois, inclua a dependência direta na seção de dependências sem a marca de versão.

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

Incluir dependência direta

Se você quiser assumir a dependência de uma versão específica da biblioteca que não está presente no BOM, adicione a dependência direta ao seu projeto da seguinte maneira.

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

Criar uma conta de armazenamento

Para criar uma Conta de Armazenamento, você pode usar o Portal do Azure ou a CLI do Azure.

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

Autenticar o cliente

Para interagir com o serviço de Armazenamento (Blob, Fila, Mensagem, MessageId, Arquivo), você precisará criar uma instância da classe Cliente de Serviço. Para tornar isso possível, você precisará da cadeia de caracteres SAS da Conta SAS (assinatura de acesso compartilhado) da conta de Armazenamento. Saiba mais em Token SAS

Obter credenciais

SAS Token

a. Use o snippet da CLI do Azure abaixo para obter o token SAS da conta de Armazenamento.

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, obtenha o Token SAS da conta no Portal do Azure.

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

Credencial de chave compartilhada

a. Use o nome da conta e a chave da conta. Nome da conta é o nome da conta de armazenamento.

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

b. Usar o cadeia de conexão

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

Principais conceitos

Formato de URL

As filas podem ser endereçáveis usando o seguinte formato de URL: a seguinte URL aborda uma fila no diagrama: https://myaccount.queue.core.windows.net/images-to-download

Sintaxe do URI de recurso

Para a conta de armazenamento, o URI de base para operações de fila inclui apenas o nome da conta:

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

Para uma fila, o URI de base inclui o nome da conta e o nome da fila:

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

Tratando exceções

Usa a seção gerada a queueServiceClient partir do Cliente do Serviço de Fila abaixo.

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

Nomes de fila

Cada fila em uma conta deve ter um nome exclusivo. O nome da fila deve ser um nome DNS válido e não pode ser alterado depois de criado. Os nomes de fila devem confirmar as seguintes regras:

Um nome de fila deve iniciar com uma letra ou um número e pode conter somente letras, números e traço (-).
A primeira e a última letra no nome da fila devem ser alfanuméricas. O caractere de traço (-) não pode ser o primeiro nem o último caractere. Os caracteres de traço consecutivos não são permitidos no nome da fila.
Todas as letras em um nome de fila devem ser minúsculas.
Um nome de fila deve ter de 3 a 63 caracteres.

Serviços de fila

O serviço de fila faz operações nas filas na conta de armazenamento e gerencia as propriedades da fila.

Cliente de Serviço de Fila

O cliente executa as interações com o serviço Fila, cria ou exclui uma fila, obtém e configura propriedades da fila, lista filas na conta e obtém estatísticas de fila. Existe um cliente assíncrono, QueueServiceAsyncCliente síncrono QueueClientno SDK, permitindo a seleção de um cliente com base no caso de uso de um aplicativo. Depois de ter o valor do SASToken, você poderá criar o cliente de serviço de fila com ${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");

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

Fila

QueueClient

Depois de ter o valor do SASToken, você poderá criar o cliente de serviço de fila com ${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);

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

Exemplos

As seções a seguir fornecem vários snippets de código que abrangem algumas das tarefas mais comuns do Serviço de Configuração, incluindo:

Criar um cliente
Criar uma fila
Excluir uma fila
Listar as filas na conta
Obter propriedades na conta fila
Definir propriedades na conta fila
Obter estatísticas da fila
Enfileirar mensagem em uma fila
Atualizar uma mensagem em uma fila
Espiar mensagens em uma fila
Receber mensagens de uma fila
Excluir mensagem de uma fila
Obter propriedades de Fila
Definir/atualizar metadados de fila

Criar um cliente

Temos duas maneiras de criar QueueService ou Queue Client. Aqui, o queueServiceClient será usado como exemplo. As mesmas coisas se aplicam a queueClient.

Primeiro, crie o cliente com base na URL/ponto de extremidade completo (por exemplo, com queueName, com 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();

Podemos criar o queueServiceClient do construtor usando ${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();

Criar uma fila

Crie uma fila na Conta de Armazenamento usando ${SASToken} como credencial. Gera StorageException Se a fila não for criada.

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

Excluir uma fila

Exclua uma fila na Conta de Armazenamento usando ${SASToken} como credencial. Gerará StorageException se a fila não for excluída.

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

Listar filas na conta

Liste todas as filas na conta usando ${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()));

Obter propriedades na conta de fila

Obtenha propriedades de fila na conta, incluindo propriedades para regras de Análise de Armazenamento e CORS (Compartilhamento de Recursos entre Origens).

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

Definir propriedades na conta de fila

Defina as propriedades da fila na conta, incluindo propriedades para regras de Análise de Armazenamento e CORS (Compartilhamento de Recursos entre Origens).

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

Obter estatísticas de serviço de fila

A operação Get Queue Service Stats recupera as estatísticas relacionadas à replicação para o serviço Fila.

Use ${SASToken} como credencial. Ela está disponível apenas no ponto de extremidade de local secundário quando a replicação georredundante de acesso de leitura está habilitada para a conta de armazenamento.

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

Enfileirar mensagem em uma fila

A operação adiciona uma nova mensagem à parte de trás da fila de mensagens. Um tempo limite de visibilidade também pode ser especificado para tornar a mensagem invisível até que o tempo limite de visibilidade expire.

Use ${SASToken} como credencial. Uma mensagem deve estar em um formato que pode ser incluído em uma solicitação XML com codificação UTF-8. A mensagem codificada pode ter até 64 KB de tamanho para as versões 2011-08-18 e mais recentes ou 8 KB de tamanho para versões 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");

Atualizar uma mensagem em uma fila

A operação atualiza uma mensagem na fila de mensagens. 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);

Espiar mensagens em uma fila

A operação espia uma ou mais mensagens da frente da fila. 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()));

Receber mensagens de uma fila

A operação recupera uma ou mais mensagens da frente da fila. 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()));

Excluir mensagem de uma fila

A operação exclui uma mensagem da fila. 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);

Obter propriedades de fila

A operação recupera os metadados definidos pelo usuário e as propriedades da fila na fila especificada. Os metadados são associados à fila como pares de nome-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();

Definir metadados de fila

A operação define metadados definidos pelo usuário na fila especificada. Os metadados são associados à fila como pares de nome-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);

Solução de problemas

Geral

Quando você interage com a fila usando essa biblioteca de clientes Java, os erros retornados pelo serviço correspondem aos mesmos códigos http status retornados para solicitações de API REST. Por exemplo, se você tentar recuperar uma fila que não existe em sua Conta de Armazenamento, um 404 erro será retornado, indicando Not Found.

Cliente HTTP padrão

Por padrão, todas as bibliotecas de cliente usam o cliente HTTP do Netty. Adicionar a dependência acima configurará automaticamente a biblioteca de cliente para usar o cliente HTTP do Netty. A configuração ou a alteração do cliente HTTP é detalhada no wiki de clientes HTTP.

Biblioteca SSL padrão

Todas as bibliotecas de cliente, por padrão, usam a biblioteca SSL com o uso do Tomcat nativo para habilitar o desempenho de nível nativo para operações SSL. A biblioteca SSL é um uber jar que contém bibliotecas nativas para Linux/macOS/Windows e fornece melhor desempenho em comparação com a implementação SSL padrão no JDK. Para obter mais informações, incluindo como reduzir o tamanho da dependência, consulte a seção ajuste de desempenho da wiki.

Próximas etapas

Vários exemplos de SDK do Java da Fila de Armazenamento estão disponíveis para você no repositório GitHub do SDK. Esses exemplos fornecem código de exemplo para cenários adicionais comumente encontrados ao trabalhar com Key Vault:

Próximas etapas Exemplos

Os exemplos são explicados em detalhes aqui.

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite https://cla.microsoft.com.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.

Para obter detalhes sobre como contribuir para esse repositório, consulte o guia de contribuição.

Bifurcar
Criar seu branch de recurso (git checkout -b my-new-feature)
Confirmar suas alterações (git commit -am 'Add some feature')
Enviar por push para o branch (git push origin my-new-feature)
Criar nova solicitação de pull

Impressões

Compartilhar via

Biblioteca de clientes da Fila de Armazenamento do Azure para Java – versão 12.19.1

Introdução

Pré-requisitos

Incluir o pacote

Incluir o arquivo da BOM

Incluir dependência direta

Criar uma conta de armazenamento

Autenticar o cliente

Obter credenciais

Principais conceitos

Formato de URL

Sintaxe do URI de recurso

Tratando exceções

Nomes de fila

Serviços de fila

Cliente de Serviço de Fila

Fila

QueueClient

Exemplos

Criar um cliente

Criar uma fila

Excluir uma fila

Listar filas na conta

Obter propriedades na conta de fila

Definir propriedades na conta de fila

Obter estatísticas de serviço de fila

Enfileirar mensagem em uma fila

Atualizar uma mensagem em uma fila

Espiar mensagens em uma fila

Receber mensagens de uma fila

Excluir mensagem de uma fila

Obter propriedades de fila

Definir metadados de fila

Solução de problemas

Geral

Cliente HTTP padrão

Biblioteca SSL padrão

Próximas etapas

Próximas etapas Exemplos

Contribuição

Comentários

Recursos adicionais