Queue trigger

7 minutos

Uma fila de mensagens é um componente de software usado para lidar com mensagens entre processos, threads ou aplicativos. Uma fila pode armazenar uma mensagem e os trabalhadores podem buscá-la quando é um bom momento.

Na nuvem, as filas de mensagens podem gerar eventos com uma carga útil. Um serviço como o Azure Functions pode ouvir essa mensagem e executar seu código quando uma mensagem é publicada.

Trabalhar com filas de mensagens

Para que uma função do Azure possa consumir uma mensagem de uma fila de mensagens, ela precisa de um gatilho e, possivelmente, de uma ligação.

Uma função do Azure precisa ouvir uma fila específica para que seu código seja acionado quando uma nova mensagem for publicada nessa fila. Para configurar um gatilho, você precisa fornecer as credenciais adequadas para que o código de gatilho saiba como se conectar à fila de mensagens. Você cria uma entrada no arquivo function.json para a função que está ouvindo a fila. bindings No elemento , especifique estas propriedades em uma entrada:

Property	valor
`name`	Um nome ao qual você pode se referir no código
`type`	`queueTrigger`
`direction`	`in`
`queueName`	Como se chama a fila
`connection`	Uma variável de configuração no local.settings.json

Uma entrada de exemplo pode ser definida assim:

{
    "name": "myQueueItem",
    "type": "queueTrigger",
    "direction": "in",
    "queueName": "messages-incoming",
    "connection": "AzureWebJobsStorage"
  }

Se essa fila estiver em uma conta de armazenamento, o AzureWebJobsStorage valor será o valor da cadeia de conexão.

Você não precisa estritamente de uma associação ao consumir uma mensagem de uma fila. No entanto, se você quiser gravar em uma fila, precisará de uma ligação de saída. Com essa vinculação, você obtém uma referência à fila pretendida.

Nota

Atualmente, apenas ligações de saída são suportadas para filas.

Programar localmente

Como desenvolvedor, você quer ciclos de feedback curtos. Você também deseja garantir que sua experiência de desenvolvedor seja o mais próxima possível de um ambiente de produção. Uma maneira de atingir esses dois objetivos é usando um emulador de fila.

Um emulador de fila permite simular mensagens de fila reais às quais sua função do Azure responderá. Para usar o emulador:

Instale o emulador. Procure Azurite no Visual Studio Code ou baixe a extensão Azurite.
Para usar a funcionalidade do emulador, inicie-a selecionando Azure: Start Queue Service na paleta de comandos.

A execução deste comando inicia um ouvinte chamado Azure Storage Explorer que outro aplicativo pode pegar. O Storage Explorer é um aplicativo cliente que permite navegar pelos recursos da nuvem e usar a funcionalidade do emulador.
Baixe o Gerenciador de Armazenamento do Azure. Em seguida, abra o aplicativo e você verá a seguinte indicação de que o emulador está funcionando:
Crie uma fila no emulador. Você usará essa fila como parte da configuração do ponto de extremidade da função. Ao clicar com o botão direito do mouse no elemento queue, você pode criar uma nova fila.
Para garantir que seu aplicativo Functions use o emulador, você precisa definir a cadeia de conexão corretamente. Abra local.settings.json, localize o AzureWebJobsStorage elemento e dê-lhe o valor "UseDevelopmentStorage=true".

Nota

Lembre-se de definir essa propriedade de forma diferente à medida que você se move para a nuvem. Ele deve apontar para um recurso real no Azure quando em produção.

Construa a função

Agora você tem um emulador local configurado e ele tem uma fila nele. Você também configurou seu projeto para apontar para o emulador local. Agora você precisa criar uma função para lidar com um gatilho de fila.

Criar um ponto de extremidade de função

Você está pronto para criar uma função que possa lidar com mensagens de fila de entrada. Crie uma pasta para sua função e nomeie-a, por exemplo, queueTrigger. Em seguida, crie um arquivo function.json e forneça a ele o seguinte conteúdo:

{
  "bindings": [{
    "name" "queueItem",
    "type": "queueTrigger",
    "direction": "in",
    "queueName" : "items",
    "connection": "AzureWebJobsStorage"
  }]
}

O valor do name elemento é importante, porque você se referirá a ele posteriormente em seu código para analisar os dados de entrada da fila. Ele precisa ser do tipo queueTrigger para que a fila o acione quando houver uma nova mensagem.

O queueName elemento identifica exclusivamente com qual fila você está interagindo. Tudo o que você inserir aqui precisa corresponder ao que você chama de fila no emulador ou ao que você mais tarde chama de fila real no Azure.

O connection elemento aponta para o AzureWebJobsStorage valor do elemento em local.settings.json.

Manipular uma mensagem de fila

Para lidar com uma mensagem de fila de entrada, você precisa escrever código que possa analisar a mensagem que você precisa. Nesse ponto, você pode decidir o que fazer a seguir. Por exemplo, você pode iniciar uma solicitação da Web, colocar essa mensagem em outra fila ou enviar a mensagem para um banco de dados.

Configurar uma rota

Você precisa de uma rota para lidar com solicitações de entrada. O Azure Functions manipulará solicitações para uma fila na raiz. Quando você configura uma rota da seguinte maneira, sua solicitação será invocada como http://localhost:<port>/queueTrigger:

http.HandleFunc("/queueTrigger", handleQueueTrigger)

Descodificar um pedido

Quando a mensagem da fila é enviada para você, ela tem esta forma:

{
  "Data": {
    "queueItem": "your message"
  },
  "Metadata": {
    "DequeueCount": 1,
    "ExpirationTime": "2019-10-16T17:58:31+00:00",
    "Id": "800ae4b3-bdd2-4c08-badd-f08e5a34b865",
    "InsertionTime": "2019-10-09T17:58:31+00:00",
    "NextVisibleTime": "2019-10-09T18:08:32+00:00",
    "PopReceipt": "AgAAAAMAAAAAAAAAAgtnj8x+1QE=",
    "sys": {
      "MethodName": "QueueTrigger",
      "UtcNow": "2019-10-09T17:58:32.2205399Z",
      "RandGuid": "24ad4c06-24ad-4e5b-8294-3da9714877e9"
    }
  }
}

Como parte da decodificação dessa solicitação de entrada, você precisa de uma estrutura auxiliar que modele a mensagem anterior. Deverá ter o seguinte aspeto:

type InvokeRequest {
   Data map[string]json.RawMessage
   Metadata map[string]interface{}
}

Comece a escrever código para receber essa solicitação de entrada e decodificá-la:

func handleQueueTrigger(w http.ResponseWrite, r *http.Request) {
   var invokeRequest InvokeRequest
   d := json.NewDecoder(r.Body)
   d.Decode(&invokeRequest)
}

Agora você está em um ponto em que a solicitação foi decodificada, mas precisa analisar a própria mensagem da fila.

Analisar uma mensagem de fila

Depois que a solicitação for decodificada, sua mensagem de fila poderá ser recuperada da solicitação na Data propriedade. Você também precisa fazer referência à mensagem pelo valor da name propriedade que você configurou no arquivo function.json . O código para recuperar a mensagem é uma linha única como esta:

invokeRequest.Data["queueItem"]

Como você precisa ser capaz de ler essa mensagem em texto não criptografado, você usará uma biblioteca JSON e a analisará. A biblioteca JSON usará um Unmarshal() método que usa dois parâmetros: a mensagem a ser analisada e a variável na qual colocar a mensagem analisada. Portanto, seu código precisa ter esta aparência:

var parsedMessage string
json.Unmarshal(invokeRequest.Data["queueItem"], &parsedMessage)

Neste ponto, parsedMessage contém a sua mensagem. Se você quiser imprimi-lo no console, use o seguinte código:

fmt.Println(parsedMessage) // your message

Nota

Se a sua mensagem é algo mais avançado do que uma cadeia de caracteres, então parsedMessage precisa ter uma estrutura que corresponda à forma do que queueMessage está apontando.

Disparar uma mensagem

Para testar seu aplicativo, você pode usar o Gerenciador de Armazenamento do Azure. No painel direito da ferramenta, selecione o botão Adicionar mensagem para criar uma mensagem na fila.

Captura de tela que mostra o botão para adicionar uma mensagem na fila.

Se você tiver seu aplicativo Functions e ele estiver em execução neste momento, ele acionará a associação e seu código será invocado.