Introdução ao Armazenamento de Filas do Azure com o F#

2024-10-15

O armazenamento de Filas do Azure fornece mensagens na nuvem entre os componentes do aplicativo. Na criação de aplicativos para escala, os componentes do aplicativo geralmente são desassociados, para que possam ser redimensionados independentemente. O armazenamento de filas fornece mensagens assíncronas para a comunicação entre os componentes do aplicativo, estando eles em execução na nuvem, na área de trabalho, em um servidor local ou em um dispositivo móvel. O armazenamento de Fila também dá suporte ao gerenciamento de tarefas assíncronas e à criação de fluxos de trabalho do processo.

Sobre este tutorial

Este tutorial mostra como escrever um código F# para alguns cenários comuns usando o Armazenamento de Filas do Azure. As tarefas abordadas incluem a criação e a exclusão de filas e a adição, a leitura e a exclusão de mensagens da fila.

Para ter uma visão geral conceitual do armazenamento de filas, confira o guia do .NET para o armazenamento de filas. Para facilitar, esses tutoriais usam cadeias de conexão para autenticar com o Azure. Para obter a segurança ideal, você deve usar o Microsoft Entra ID com identidades gerenciadas.

Pré-requisitos

Para usar este guia, primeiro, você precisará criar uma conta de armazenamento do Azure. Você também precisará ter a chave de acesso de armazenamento para essa conta.

Criar um script F# e iniciar o F# Interativo

Os exemplos deste artigo podem ser usados em um aplicativo F# ou em um script F#. Para criar um script F#, crie um arquivo com a extensão .fsx, por exemplo, queues.fsx, no ambiente de desenvolvimento F#.

Como executar scripts

O F# Interativo, dotnet fsi, pode ser iniciado de maneira interativa ou na linha de comando para executar um script. A sintaxe da linha de comando é

> dotnet fsi [options] [ script-file [arguments] ]

Adicionar pacotes em um script

Em seguida, use #rnuget:package name para instalar o pacote Azure.Storage.Queues e os namespaces open, como

> #r "nuget: Azure.Storage.Queues"
open Azure.Storage.Queues

Adicionar declarações do namespace

Adicione as seguintes instruções open à parte superior do arquivo queues.fsx:

open Azure.Storage.Queues // Namespace for Queue storage types
open System
open System.Text

Obter a cadeia de conexão

Você precisará ter uma cadeia de conexão do Armazenamento do Azure para este tutorial. Para saber mais sobre cadeias de conexão, confira Configurar cadeias de conexão de armazenamento.

Para o tutorial, você vai inserir a cadeia de conexão no script, da seguinte maneira:

let storageConnString = "..." // fill this in from your storage account

Criar o cliente do serviço Fila

A classe QueueClient permite que você recupere filas armazenadas no armazenamento de filas. Esta é uma forma de criar o cliente:

let queueClient = QueueClient(storageConnString, "myqueue")

Agora você está pronto para escrever um código que lê e grava dados no Armazenamento de Filas.

Criar uma fila

Este exemplo mostra como criar uma fila se ela ainda não existe:

queueClient.CreateIfNotExists()

Inserir uma mensagem em uma fila

Para inserir uma mensagem em uma fila existente, primeiro, crie uma mensagem. Em seguida, chame o método SendMessage. Uma mensagem pode ser criada com base em uma cadeia de caracteres (no formato UTF-8) ou uma matriz byte, desta forma:

queueClient.SendMessage("Hello, World") // Insert a String message into a queue
queueClient.SendMessage(BinaryData.FromBytes(Encoding.UTF8.GetBytes("Hello, World"))) // Insert a BinaryData message into a queue

Espiar a próxima mensagem

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

let peekedMessage = queueClient.PeekMessage()
let messageContents = peekedMessage.Value.Body.ToString()

Obter a próxima mensagem para processamento

Você pode recuperar a mensagem na frente de uma fila para processamento chamando o método ReceiveMessage.

let updateMessage = queueClient.ReceiveMessage().Value

Posteriormente, você indica o processamento bem-sucedido da mensagem usando DeleteMessage.

Alterar o conteúdo de uma mensagem na 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 falhar devido a uma falha de hardware ou de software. Normalmente, você mantém uma contagem de repetições e, se a mensagem é repetida algumas vezes, você a exclui. Isso protege contra uma mensagem que dispara um erro do aplicativo sempre que for processada.

queueClient.UpdateMessage(
    updateMessage.MessageId,
    updateMessage.PopReceipt,
    "Updated contents.",
    TimeSpan.FromSeconds(60.0))

Remover a próxima mensagem da fila

Seu código remove uma mensagem de um fila em duas etapas. Ao chamar ReceiveMessage, você recebe a próxima mensagem em uma fila. Uma mensagem retornada de ReceiveMessage torna-se invisível para todas as outras mensagens de leitura de código da fila. Por padrão, essa mensagem permanece invisível por 30 segundos. Para terminar de remover a mensagem da fila, você também deve chamar DeleteMessage. 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á DeleteMessage logo depois que a mensagem tiver sido processada. Todos os métodos Queue que mostramos até agora têm alternativas Async.

let deleteMessage = queueClient.ReceiveMessage().Value
queueClient.DeleteMessage(deleteMessage.MessageId, deleteMessage.PopReceipt)

Usar fluxos de trabalho assíncronos com APIs de Armazenamento de filas comuns

Este exemplo mostra como usar um fluxo de trabalho assíncrono com APIs de Armazenamento de filas comuns.

async {
    let! exists = queueClient.CreateIfNotExistsAsync() |> Async.AwaitTask

    let! delAsyncMessage = queueClient.ReceiveMessageAsync() |> Async.AwaitTask

    // ... process the message here ...

    // Now indicate successful processing:
    queueClient.DeleteMessageAsync(delAsyncMessage.Value.MessageId, delAsyncMessage.Value.PopReceipt) |> Async.AwaitTask
}

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 ReceiveMessages para obter 20 mensagens em uma chamada e processa cada uma das mensagens. Ele também define o tempo limite de invisibilidade de cinco minutos para cada mensagem. Observe que os cinco minutos começam para todas as mensagens ao mesmo tempo. Portanto, após os cinco minutos desde a chamada a ReceiveMessages, todas as mensagens que não tiverem sido excluídas ficarão visíveis novamente.

for dequeueMessage in queueClient.ReceiveMessages(20, Nullable(TimeSpan.FromMinutes(5.))).Value do
        // Process the message here.
        queueClient.DeleteMessage(dequeueMessage.MessageId, dequeueMessage.PopReceipt)

Obter o tamanho da fila

Você pode obter uma estimativa do número de mensagens em uma fila. O método GetProperties solicita que o serviço Fila recupere os atributos da fila, incluindo a contagem de mensagens. A propriedade ApproximateMessagesCount retorna o último valor recuperado pelo método GetProperties.

let properties = queueClient.GetProperties().Value
let count = properties.ApproximateMessagesCount

Excluir uma fila

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

queueClient.DeleteIfExists()

Observação

Se você estiver migrando das bibliotecas antigas, elas codificarão mensagens codificadas em Base64 por padrão, ao contrário das novas bibliotecas, porque elas têm melhor desempenho. Para obter informações sobre como configurar a codificação, confira MessageEncoding.

Compartilhar via