Como usar o armazenamento de filas do C++

• .NET
• Java
• Python
• Node.js
• C++
• Ruby
• PHP

Dica

Experimente usar o Gerenciador de Armazenamento do Microsoft Azure

O Gerenciador de Armazenamento do Microsoft Azure é um aplicativo autônomo e gratuito da Microsoft que possibilita o trabalho visual com os dados do Armazenamento do Azure no Windows, MacOS e Linux.

Visão geral

Este guia lhe mostrará como executar cenários comuns usando o serviço de Armazenamento de Fila do Azure. Os exemplos são escritos em C++ e usam a biblioteca de clientes de Armazenamento do Azure para C++. Os cenários abrangidos incluem inserir, exibir, obter e excluir mensagens da fila, bem como criar e excluir filas.

Observação

Este guia tem como alvo a biblioteca de clientes de Armazenamento do Azure para C++, v1.0.0 e superior. A versão recomendada é a biblioteca de clientes de Armazenamento do Azure v2.2.0, que está disponível via NuGet ou GitHub.

O que é armazenamento em 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. O armazenamento em fila é usado com frequência para criar uma lista de pendências de trabalho a ser processada de forma assíncrona.

Conceitos do serviço Fila

O serviço Fila do Azure contém os seguintes componentes:

• Conta de Armazenamento: todo o acesso ao Armazenamento do Azure é feito através de uma conta de armazenamento. Para saber mais sobre as contas de armazenamento, confira Visão geral da conta de armazenamento.

• Fila: uma fila contém um conjunto de mensagens. Todas as mensagens devem estar em uma fila. Observe que o nome da fila deve estar em letras minúsculas. Para saber mais sobre filas de nomenclatura, confira Nomenclatura de filas e metadados.

• Mensagem: uma mensagem, em qualquer formato, de até 64 KB. O tempo máximo que uma mensagem pode ficar na fila é de sete dias. Para a versão 2017-07-29 ou posterior, a vida útil máxima pode ser qualquer número positivo ou -1, indicando que a mensagem não expira. Se esse parâmetro for omitido, a vida útil padrão será de sete dias.

• Formato de URL: as filas são endereçáveis usando o seguinte formato: http://<storage account>.queue.core.windows.net/<queue>

  A URL a seguir endereça um fila no diagrama:

  http://myaccount.queue.core.windows.net/incoming-orders

Criar uma conta de armazenamento do Azure

A maneira mais fácil de criar sua primeira conta de armazenamento do Azure é usando o portal do Azure. Para saber mais, consulte Criar uma conta de armazenamento.

Você também pode criar uma conta de armazenamento do Azure usando o Azure PowerShell, a CLI do Azure ou o Provedor de Recursos de Armazenamento do Azure para .NET.

Se você preferir não criar uma conta de armazenamento no Azure neste momento, também pode usar o emulador de armazenamento Azurite para executar e testar seu código em um ambiente local. Para obter mais informações, consulte Usar o emulador Azurite para desenvolvimento local do armazenamento do Azure.

Criar um aplicativo em C++

Neste guia, você usará os recursos de armazenamento que podem ser executados em um aplicativo C++.

Para isso, você precisará instalar a biblioteca de clientes de Armazenamento do Azure para C++ e criar uma conta de Armazenamento do Azure em sua assinatura do Azure.

Para instalar a biblioteca de clientes de Armazenamento do Azure para C++, você pode usar os seguintes métodos:

• Linux: Siga as instruções fornecidas na página LEIAME da biblioteca de clientes do Armazenamento do Microsoft Azure para C++: Introdução ao Linux.
• Windows: No Windows, use vcpkg como o gerenciador de dependências. Siga o início rápido para inicializar vcpkg. Em seguir, use este comando para instalar a biblioteca:

.\vcpkg.exe install azure-storage-cpp

Você pode encontrar um guia de criação do código-fonte e exportá-lo para o NuGet no arquivo LEIAME.

Configurar seu aplicativo para acessar o Armazenamento de Filas

Adicione as seguintes instruções include à parte superior do arquivo C++ no qual deseja usar as APIs de Armazenamento do Azure para acessar as filas:

#include <was/storage_account.h>
#include <was/queue.h>

Configurar uma cadeia de conexão de Armazenamento do Azure

Um cliente de Armazenamento do Azure usa uma cadeia de conexão para armazenar pontos de extremidade e credenciais para acessar serviços de gerenciamento de dados. Ao executar um aplicativo cliente, é necessário fornecer a cadeia de conexão de armazenamento no formato a seguir, usando o nome de sua conta de armazenamento e a tecla de acesso ao armazenamento da conta de armazenamento listada no portal do Azure para os valores AccountName e AccountKey. Para obter informações sobre as contas de armazenamento e as teclas de acesso, veja Sobre as contas de armazenamento do Azure. Este exemplo mostra como você pode declarar um campo estático para armazenar a cadeia de conexão:

// Define the connection-string with your values.
const utility::string_t storage_connection_string(U("DefaultEndpointsProtocol=https;AccountName=your_storage_account;AccountKey=your_storage_account_key"));

Para testar um aplicativo no computador local do Windows, você pode usar o emulador de armazenamento do Azure. O Azurite é um utilitário que simula o Armazenamento de Blob do Azure e o Armazenamento de Filas no computador local de desenvolvimento. Este exemplo mostra como você pode declarar um campo estático para manter a cadeia de conexão em seu emulador de armazenamento local:

// Define the connection-string with Azurite.
const utility::string_t storage_connection_string(U("UseDevelopmentStorage=true;"));  

Para iniciar o Azurite, confira Usar o emulador Azurite para o desenvolvimento local do Armazenamento do Azure.

Os exemplos abaixo pressupõem que você usou um desses dois métodos para obter a cadeia de conexão do armazenamento.

Recuperar sua cadeia de conexão

Você pode usar a classe cloud_storage_account para representar as informações de sua conta de armazenamento. Para recuperar as informações da conta de armazenamento na cadeia de conexão de armazenamento, você pode usar o método parse .

// Retrieve storage account from connection string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);

Como criar uma fila

Um objeto cloud_queue_client permite que você obtenha objetos de referência para filas. O código a seguir cria um objeto cloud_queue_client.

// Retrieve storage account from connection string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);

// Create a queue client.
azure::storage::cloud_queue_client queue_client = storage_account.create_cloud_queue_client();

Use o objeto cloud_queue_client para obter uma referência à fila que deseja usar. Você poderá criar a fila se ela não existir.

// Retrieve a reference to a queue.
azure::storage::cloud_queue queue = queue_client.get_queue_reference(U("my-sample-queue"));

// Create the queue if it doesn't already exist.
queue.create_if_not_exists();  

Como inserir uma mensagem em uma fila

Para inserir uma mensagem em uma fila existente, primeiro crie uma nova cloud_queue_message. Em seguida, chame o método add_message. Um cloud_queue_message pode ser criado por meio de uma cadeia de caracteres (em formato UTF-8) ou de uma matriz de bytes. Este é o código que cria uma fila (se não existir) e insere a mensagem Hello, World:

// Retrieve storage account from connection-string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);

// Create the queue client.
azure::storage::cloud_queue_client queue_client = storage_account.create_cloud_queue_client();

// Retrieve a reference to a queue.
azure::storage::cloud_queue queue = queue_client.get_queue_reference(U("my-sample-queue"));

// Create the queue if it doesn't already exist.
queue.create_if_not_exists();

// Create a message and add it to the queue.
azure::storage::cloud_queue_message message1(U("Hello, World"));
queue.add_message(message1);  

Como inspecionar a próxima mensagem

Você pode inspecionar a mensagem na frente de uma fila sem removê-la da fila chamando o método peek_message.

// Retrieve storage account from connection-string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);

// Create the queue client.
azure::storage::cloud_queue_client queue_client = storage_account.create_cloud_queue_client();

// Retrieve a reference to a queue.
azure::storage::cloud_queue queue = queue_client.get_queue_reference(U("my-sample-queue"));

// Peek at the next message.
azure::storage::cloud_queue_message peeked_message = queue.peek_message();

// Output the message content.
std::wcout << U("Peeked message content: ") << peeked_message.content_as_string() << std::endl;

Como alterar o conteúdo de uma mensagem em fila

Você pode alterar o conteúdo de uma mensagem in-loco na fila. Se a mensagem representar uma tarefa de trabalho, você poderá usar esse recurso para atualizar o status da tarefa de trabalho. O código a seguir atualiza a mensagem da fila com novo conteúdo e define o tempo limite de visibilidade para estender mais 60 segundos. Isso salva o estado do trabalho associado à mensagem e dá ao cliente mais um minuto para continuar trabalhando na mensagem. Você pode usar essa técnica para acompanhar fluxos de trabalho de várias etapas em mensagens em fila, sem a necessidade de começar desde o início, caso uma etapa de processamento falhe devido a uma falha de hardware ou de software. Normalmente, você mantém uma contagem de repetições e, se a mensagem for repetida mais de n vezes, você a exclui. Isso protege contra uma mensagem que dispara um erro do aplicativo sempre que for processada.

// Retrieve storage account from connection-string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);

// Create the queue client.
azure::storage::cloud_queue_client queue_client = storage_account.create_cloud_queue_client();

// Retrieve a reference to a queue.
azure::storage::cloud_queue queue = queue_client.get_queue_reference(U("my-sample-queue"));

// Get the message from the queue and update the message contents.
// The visibility timeout "0" means make it visible immediately.
// The visibility timeout "60" means the client can get another minute to continue
// working on the message.
azure::storage::cloud_queue_message changed_message = queue.get_message();

changed_message.set_content(U("Changed message"));
queue.update_message(changed_message, std::chrono::seconds(60), true);

// Output the message content.
std::wcout << U("Changed message content: ") << changed_message.content_as_string() << std::endl;  

Como remover a próxima mensagem da fila

Seu código remove uma mensagem de um fila em duas etapas. Ao chamar get_message, você recebe a próxima mensagem em uma fila. Uma mensagem retornada de get_message torna-se invisível para todas as outras mensagens de leitura de código da fila. Para terminar de remover a mensagem da fila, você também deve chamar delete_message. Este processo de duas etapas de remover uma mensagem garante que quando o código não processa uma mensagem devido à falhas de hardware ou de software, outra instância do seu código pode receber a mesma mensagem e tentar novamente. O código chamará delete_message logo depois que a mensagem tiver sido processada.

// Retrieve storage account from connection-string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);

// Create the queue client.
azure::storage::cloud_queue_client queue_client = storage_account.create_cloud_queue_client();

// Retrieve a reference to a queue.
azure::storage::cloud_queue queue = queue_client.get_queue_reference(U("my-sample-queue"));

// Get the next message.
azure::storage::cloud_queue_message dequeued_message = queue.get_message();
std::wcout << U("Dequeued message: ") << dequeued_message.content_as_string() << std::endl;

// Delete the message.
queue.delete_message(dequeued_message);

Como fazer: Use opções adicionais para remover mensagens da fila

Há duas maneiras de personalizar a recuperação da mensagem de uma fila. Primeiro, você pode obter um lote de mensagens (até 32). Segundo, você pode definir um tempo limite de invisibilidade mais longo ou mais curto, permitindo mais ou menos tempo para seu código processar totalmente cada mensagem. O exemplo de código a seguir usa o método get_messages para receber 20 mensagens em uma chamada. Em seguida, ele processa cada mensagem usando um loop for. Ele também define o tempo limite de invisibilidade de cinco minutos para cada mensagem. Observe que os 5 minutos começam para todas as mensagens ao mesmo tempo; portanto, depois de 5 minutos desde a chamada para get_messages, todas as mensagens que não tenham sido excluídas se tornarão visíveis novamente.

// Retrieve storage account from connection-string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);

// Create the queue client.
azure::storage::cloud_queue_client queue_client = storage_account.create_cloud_queue_client();

// Retrieve a reference to a queue.
azure::storage::cloud_queue queue = queue_client.get_queue_reference(U("my-sample-queue"));

// Dequeue some queue messages (maximum 32 at a time) and set their visibility timeout to
// 5 minutes (300 seconds).
azure::storage::queue_request_options options;
azure::storage::operation_context context;

// Retrieve 20 messages from the queue with a visibility timeout of 300 seconds.
std::vector<azure::storage::cloud_queue_message> messages = queue.get_messages(20, std::chrono::seconds(300), options, context);

for (auto it = messages.cbegin(); it != messages.cend(); ++it)
{
    // Display the contents of the message.
    std::wcout << U("Get: ") << it->content_as_string() << std::endl;
}

Como obter o comprimento da fila

Você pode obter uma estimativa do número de mensagens em uma fila. O método download_attributes retorna propriedades de fila, incluindo a contagem de mensagens. O método approximate_message_count obtém o número aproximado de mensagens na fila.

// Retrieve storage account from connection-string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);

// Create the queue client.
azure::storage::cloud_queue_client queue_client = storage_account.create_cloud_queue_client();

// Retrieve a reference to a queue.
azure::storage::cloud_queue queue = queue_client.get_queue_reference(U("my-sample-queue"));

// Fetch the queue attributes.
queue.download_attributes();

// Retrieve the cached approximate message count.
int cachedMessageCount = queue.approximate_message_count();

// Display number of messages.
std::wcout << U("Number of messages in queue: ") << cachedMessageCount << std::endl;  

Como excluir uma fila

Para excluir uma fila e todas as mensagens que ela contém, chame o método delete_queue_if_exists no objeto da fila.

// Retrieve storage account from connection-string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);

// Create the queue client.
azure::storage::cloud_queue_client queue_client = storage_account.create_cloud_queue_client();

// Retrieve a reference to a queue.
azure::storage::cloud_queue queue = queue_client.get_queue_reference(U("my-sample-queue"));

// If the queue exists and delete it.
queue.delete_queue_if_exists();  

Próximas etapas

Agora que você aprendeu os conceitos básicos do Armazenamento de Filas, siga estes links para saber mais sobre o armazenamento do Azure.

• Como usar o Armazenamento de Blobs do C++
• Como usar o Armazenamento de Tabelas do C++
• Listar recursos do Armazenamento do Azure no C++
• Referência da biblioteca de clientes de Armazenamento do Azure para C++
• Documentação do Armazenamento do Azure