Biblioteca de clientes da Fila de Armazenamento do Azure para Java – versão 12.19.1
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");
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
});
Fila
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.
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);
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
});
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();
Ou
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
Comentários
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja: https://aka.ms/ContentUserFeedback.
Submeter e ver comentários