Anterior

Seguinte

Exercício – escrever dados com vínculos de saída

Concluído

No exercício anterior, implementamos um cenário para procurar marcadores em um banco de dados do Azure Cosmos DB. Configurámos um enlace de entrada para ler dados da nossa coleção de marcadores. No entanto, podemos fazer muito mais. Vamos expandir o cenário para incluir a escrita. Considere o fluxograma seguinte:

Nesse cenário, recebemos solicitações para adicionar marcadores à nossa coleção. Os pedidos transmitem a chave pretendida, ou o ID, juntamente com o URL do marcador. Como você pode ver no fluxograma, respondemos com um erro se a chave já existir em nosso back-end.

Se a chave que nos foi passada não for encontrada, adicionamos o novo marcador à nossa base de dados. Podíamos ficar por aqui, mas vamos fazer um pouco mais.

Repara noutro passo no fluxograma? Até agora, não fizemos muito com os dados que recebemos em termos de processamento. Movemos o que recebemos para uma base de dados. No entanto, em uma solução real, provavelmente processaríamos os dados de alguma forma. Podemos fazer todo o processamento na mesma função, mas neste exercício, mostramos um padrão que descarrega o processamento adicional para outro componente ou parte da lógica de negócios.

O que pode ser um bom exemplo de descarregamento de trabalho no nosso cenário de favoritos? E se enviássemos o novo marcador para um serviço de geração de códigos QR? Esse serviço, por sua vez, geraria um código QR para a URL, armazenaria a imagem no Blob Storage e adicionaria o endereço da imagem QR à entrada em nossa coleção de favoritos. Chamar um serviço para gerar uma imagem QR é demorado. Assim, em vez de esperar pelo resultado, entregamos a tarefa a uma função e deixamos que ela conclua essa tarefa de forma assíncrona.

Assim como o Azure Functions dá suporte a associações de entrada para várias fontes de integração, ele também tem um conjunto de modelos para associações de saída para facilitar a gravação de dados em fontes de dados. Os enlaces de saída também são configurados no ficheiro function.json. Como você pode ver neste exercício, podemos configurar nossa função para trabalhar com várias fontes de dados e serviços.

Importante

Este exercício baseia-se nos recursos de área restrita e recursos que você criou em unidades anteriores; especificamente, o banco de dados do Azure Cosmos DB, marcadores e associações de entrada. Se não tiver completado os exercícios nas unidades anteriores, não poderá completar este exercício.

Criar uma função acionada por HTTP

1. No portal do Azure, vá para o aplicativo de função que você criou selecionando o nome do aplicativo de função no caminho de trilha na parte superior da página da função HttpTrigger2.

2. Na guia Funções na página Visão geral, você deve ter as funções de gatilho HTTP que você criou.

3. Selecione Criar na guia Funções . O painel de funções Criar é exibido.

4. Na seção Selecione um modelo, selecione Gatilho HTTP e, em seguida, selecione Criar. O painel Visão geral da função HttpTrigger3 é exibido.

Adicionar um enlace de entrada do Azure Cosmos DB

Vamos adicionar outra associação de entrada do Azure Cosmos DB.

1. No menu Função HttpTrigger3, selecione Integração. O painel Integração é exibido.

2. Na caixa Entradas, selecione Adicionar entrada. O painel Criar entrada é exibido.

3. Na lista suspensa Tipo de Vinculação, selecione Azure Cosmos DB.

4. A configuração de conexão da conta do Cosmos DB deve ser preenchida previamente com a conexão criada no exercício anterior.

   Se não vir a sua ligação listada, siga estes passos para criar uma nova ligação.

   1. Na seção Detalhes do Azure Cosmos DB, na configuração de conexão da conta do Cosmos DB, selecione o link Novo.

   2. Quando a caixa de diálogo Nova conexão do Cosmos DB for exibida, selecione OK para criar a conexão. Uma nova conexão de conta do Cosmos DB é criada.

5. Insira os seguintes valores para as outras configurações neste painel. A qualquer momento, para saber mais sobre a finalidade de uma configuração, você pode selecionar o ícone de informações à direita.

   Definição	valor	Descrição
   Nome do parâmetro do documento	bookmark	O nome utilizado para identificar este enlace no código.
   Nome da base de dados	func-io-learn-db	A base de dados a utilizar. Este valor é o nome de base de dados definido anteriormente nesta lição.
   Nome da Coleção	Bookmarks	O nome da coleção a partir da qual os dados são lidos. Definimos essa configuração no início da lição.
   ID do Documento	{id}	Adicione {id} para usar a expressão de associação correta e aceite o parâmetro que é passado na cadeia de caracteres de consulta.
   Chave de partição	{id}	Novamente, adicione {id} para usar a expressão de vinculação correta e aceite o parâmetro que é passado na cadeia de caracteres de consulta.
   Consulta SQL (opcional)	Deixar em branco	Estamos recuperando apenas um item de cada vez com base no ID. Portanto, filtrar com a configuração Document é melhor do que usar uma Consulta SQL neste caso. Poderíamos criar uma Consulta SQL para devolver uma entrada (SELECT * from b where b.ID = /id). Essa consulta realmente retornaria um item, mas o retornaria em uma coleção de itens. O nosso código teria de manipular uma coleção desnecessariamente. Utilize a abordagem de Consulta SQL quando quiser obter múltiplos documentos.

   Como a associação de entrada que criamos no exercício anterior, queremos procurar um marcador com uma ID específica, então vinculamos a ID do documento que nossa função recebe na cadeia de caracteres de consulta à associação, que é conhecida como expressão de vinculação. O gatilho de função é uma solicitação HTTP que usa uma cadeia de caracteres de consulta para especificar a ID a ser pesquisada. A associação retorna 0 (não encontrado) ou 1 (encontrado) documentos.

6. Selecione OK para salvar a configuração de vinculação de entrada.

Agora já temos um enlace de entrada do Azure Cosmos DB. Vamos adicionar uma ligação de saída para que possamos escrever novas entradas à nossa coleção.

Adicionar um enlace de saída do Azure Cosmos DB

1. No painel Integração de HttpTrigger3, na caixa Saídas, selecione Adicionar saída. O painel Criar saída é exibido.

2. Em Tipo de Ligação, na lista suspensa, selecione Azure Cosmos DB.

3. A configuração de conexão da conta do Cosmos DB deve ser preenchida previamente com a conexão criada anteriormente. Caso contrário, expanda a lista suspensa e selecione a conexão que você definiu para a ligação de entrada HttpTrigger3.

4. Insira os seguintes valores para as configurações restantes para a associação de saída.

   Definição	valor	Descrição
   Nome do parâmetro do documento	newbookmark	O nome utilizado para identificar este enlace no código. Este parâmetro é utilizado para escrever uma nova entrada de marcador.
   Nome da base de dados	func-io-learn-db	A base de dados a utilizar. Este valor é o nome de base de dados definido anteriormente nesta lição.
   Nome da Coleção	Bookmarks	O nome da coleção a partir da qual os dados são lidos. Esse valor é o nome do contêiner que definimos anteriormente na lição.
   Chave de partição	/id	Adicione a chave de partição que definimos quando criámos o contentor do Azure Cosmos DB Marcadores anteriormente. A chave inserida aqui (especificada na configuração <key>de vinculação de entrada) deve corresponder à do contêiner.

5. Selecione OK para salvar essa configuração de vinculação de saída.

Agora temos uma encadernação para ler da nossa coleção, e uma encadernação para escrever a ela.

Adicionar um enlace de saída do Armazenamento de Filas do Azure

O Armazenamento de Filas do Azure é um serviço para armazenar mensagens que podem ser acedidas a partir de qualquer local no mundo. O tamanho de uma única mensagem pode chegar a 64 KB, e uma fila pode conter milhões de mensagens - até a capacidade total da conta de armazenamento na qual ela está definida. O diagrama a seguir mostra, em um alto nível, como uma fila é usada em nosso cenário.

Neste exemplo, você vê que uma função chamada add-bookmark adiciona mensagens a uma fila e outra chamada gen-qr-code exibe mensagens da mesma fila e processa a solicitação. Como escrevemos ou enviamos mensagens para a fila a partir do add-bookmark, adicionamos uma nova ligação de saída à sua solução.

Vamos criar a ligação através do portal.

1. No painel Integração da sua função, na caixa Saídas, selecione Adicionar saída. O painel Criar saída é exibido.

2. Na lista suspensa Tipo de Vinculação, selecione Armazenamento de Filas do Azure.

   Se aparecer uma mensagem solicitando que você instale a extensão, selecione instalar e aguarde até que Microsoft.Azure.WebJobs.Extensions.Storage ela seja concluída.

Em seguida, configuramos uma conexão de conta de armazenamento, onde nossa fila está hospedada.

1. Abaixo da Ligação da conta de armazenamento, selecione Nova. A caixa de diálogo Nova conexão de Conta de Armazenamento é exibida.

2. No início deste módulo, quando você criou seu aplicativo funcional, uma conta de armazenamento também foi criada para você. Selecione-o na lista suspensa e, em seguida, selecione OK.

   A configuração de conexão da conta de armazenamento é preenchida com o nome de uma conexão .

Embora pudéssemos manter os valores padrão, vamos alterar algumas configurações para dar mais significado às propriedades restantes.

1. Conclua as configurações no painel Criar saída , substituindo os seguintes valores antigos pelos novos valores:

   Definição	Valor antigo	Novo valor	Descrição
   Nome do parâmetro da mensagem	outputQueueItem	newmessage	A propriedade binding que usamos no código.
   Nome da fila	outqueue	bookmarks-post-process	O nome da fila onde estamos colocando marcadores para que outra função possa processá-los ainda mais.

2. Selecione OK para salvar sua configuração de saída para o Armazenamento de Filas do Azure.

Atualizar a implementação da função

Dispomos agora de todas as nossas vinculações. Está na altura de os utilizar na nossa função.

1. Para abrir o arquivo index.js no editor de códigos, selecione sua função, HttpTrigger3.

2. No menu, em Desenvolvedor, selecione Código + Teste. O painel Código + Teste é exibido para sua função.

3. Substitua todo o código no arquivo .js índice pelo código do trecho a seguir e, na barra de comandos, selecione Salvar.

   module.exports = function (context, req) {
   
       var bookmark = context.bindings.bookmark;
       if(bookmark){
               context.res = {
               status: 422,
               body : "Bookmark already exists.",
               headers: {
               'Content-Type': 'application/json'
               }
           };
       }
       else {
           
           // Create a JSON string of our bookmark.
           var bookmarkString = JSON.stringify({ 
               id: req.body.id,
               url: req.body.url
           });
   
           // Write this bookmark to our database.
           context.bindings.newbookmark = bookmarkString;
   
           // Push this bookmark onto our queue for further processing.
           context.bindings.newmessage = bookmarkString;
   
           // Tell the user all is well.
           context.res = {
               status: 200,
               body : "bookmark added!",
               headers: {
               'Content-Type': 'application/json'
               }
           };
       }
       context.done();
   };
   

Vamos explicar o que este código faz:

• Uma vez que esta função altera os nossos dados, esperamos que o pedido HTTP seja um POST e que os dados do marcador façam parte do corpo do pedido.
• O nosso enlace de entrada do Azure Cosmos DB tenta obter um documento ou marcador através do id que recebemos. Se encontrar uma entrada, o bookmark objeto será definido. A condição if(bookmark) verifica se foi encontrada uma entrada.
• Adicionar ao banco de dados é tão simples quanto definir o context.bindings.newbookmark parâmetro binding para a nova entrada de marcador, que criamos como uma cadeia de caracteres JSON.
• Publicar uma mensagem na nossa fila é tão simples como definir o parâmetro context.bindings.newmessage.

Nota

A única tarefa que realizou foi criar um enlace de fila. Nunca criou a fila explicitamente. Está a testemunhar o poder dos enlaces! Tal como a notificação seguinte indica, a fila é criada automaticamente, caso não exista.

.

Já está. Vamos ver o nosso trabalho em ação na secção seguinte.

1. Para abrir o arquivo run.ps1 no editor de códigos, selecione sua função HttpTrigger3 na trilha na parte superior do painel.

2. No menu Função, em Desenvolvedor, selecione Código + Teste. O painel Código + Teste para sua função HttpTrigger3 é exibido, exibindo o conteúdo padrão de run.ps1.

3. Substitua o conteúdo do arquivo pelo código a seguir.

   using namespace System.Net
   
   param($Request, $bookmark, $TriggerMetadata)
   
   if ($bookmark) {
       $status = 422
       $body = "Bookmark already exists."
   }
   else {
       $newBookmark = @{ id = $Request.Body.id; url = $Request.Body.url }
   
       Push-OutputBinding -Name newbookmark -Value $newBookmark
   
       Push-OutputBinding -Name newmessage -Value $newBookmark
   
       $status = [HttpStatusCode]::OK
       $body = "bookmark added!"
   }
   
   Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
       StatusCode = $status
       Body = $body
       ContentType = "application/json"
   })
   

4. Na barra de comandos, selecione Salvar. Uma conexão é feita e uma sessão de arquivo de log é aberta.

Vamos explicar o que este código faz:

• Uma vez que esta função altera os nossos dados, esperamos que o pedido HTTP seja um POST e que os dados do marcador façam parte do corpo do pedido.
• Nossa associação de entrada do Azure Cosmos DB tenta recuperar um documento, ou marcador, usando o id na solicitação. Se encontrar uma entrada, o bookmark objeto será definido. A condição if ($bookmark) verifica se foi encontrada uma entrada.
• Adicionar algo à base de dados é tão simples como chamar Push-OutputBinding com o nome do enlace de saída do Cosmos DB (newbookmark) e o valor do objeto $newBookmark.
• Publicar uma mensagem na nossa fila é tão simples como chamar Push-OutputBinding com o nome do enlace de saída da fila (newmessage) e o valor do objeto $newBookmark.

Nota

A única tarefa que realizou foi criar um enlace de fila. Nunca criou a fila explicitamente. Está a testemunhar o poder dos enlaces! Tal como a notificação seguinte indica, a fila é criada automaticamente, caso não exista.

Já está. Vamos ver o nosso trabalho em ação na secção seguinte.

Experimente

Agora que temos vários enlaces de saída, o teste torna-se um pouco mais complicado. Em unidades anteriores, nos contentávamos em testar enviando uma solicitação HTTP com uma cadeia de caracteres de consulta, mas queremos executar uma postagem HTTP desta vez. Também precisamos de verificar se as mensagens estão a chegar a uma fila.

1. Na barra de comandos do painel Código + Teste para sua função HttpTrigger3 , selecione Testar/Executar. Um novo painel é exibido, com a guia Entrada aberta, conforme mostrado nesta imagem:

   

2. Na lista suspensa Método HTTP, verifique se POST está selecionado.

3. Substitua o conteúdo do corpo da solicitação pelo seguinte objeto JSON:

   {
       "id": "docs",
       "url": "https://learn.microsoft.com/azure"
   }
   

4. Selecione Executar.

5. O progresso programático é exibido no painel Logs . Quando concluído, verifique se a guia Saída exibe "Marcador já existe." na configuração de conteúdo de resposta HTTP.

   

   Você adicionou o item de indicador em Exercício - Ler dados com associações de entrada. A resposta confirma que o var bookmark = context.bindings.bookmark JavaScript está funcionando corretamente e que o código do PowerShell está fazendo a mesma conexão.

6. Vamos postar um segundo marcador no banco de dados. Selecione a guia Entrada .

7. Substitua o conteúdo do corpo da solicitação pelo seguinte objeto JSON:

   {
       "id": "github",
       "url": "https://www.github.com"
   }
   

8. Selecione Executar.

9. Verifique se a guia Saída exibe "marcador adicionado!" no conteúdo da resposta HTTP, conforme mostrado na captura de tela a seguir.

   

Parabéns! Sua função funciona como projetado! Mas, e a operação de fila que adicionamos ao código? Vamos ver se alguma mensagem foi escrita numa fila.

Verificar se uma mensagem foi escrita na fila

As filas do Armazenamento de Filas do Azure estão alojadas numa conta de armazenamento. Você configurou a conta de armazenamento quando criou a associação de saída.

1. Na barra de pesquisa global do portal do Azure, insira contas de armazenamento e, na lista de resultados, selecione Contas de armazenamento. O painel Contas de armazenamento é exibido.

   

2. Selecione a conta de armazenamento que você usou para configurar a associação de saída newmessage .

3. No menu Conta de armazenamento, em Armazenamento de dados, selecione Filas para listar as filas hospedadas por essa conta de armazenamento. Verifique se a fila de favoritos-pós-processo está listada, conforme mostrado na captura de tela a seguir.

   

4. Selecione favoritos-pós-processo para listar as mensagens que estão na fila. Se tudo correu conforme planeado, a fila inclui a mensagem que publicou quando adicionou um marcador à base de dados. Deve ter um aspeto semelhante ao seguinte:

   

   Neste exemplo, a mensagem recebeu uma ID exclusiva e a coluna de texto Mensagem exibe seu marcador no formato JSON. Não há nenhuma mensagem para o marcador do Azure docs que você tentou adicionar porque ele já existia no banco de dados.

5. Você pode testar ainda mais a função alterando o corpo da solicitação no painel de teste com novos conjuntos de id/url e executando a função. Observe esta fila para ver mais mensagens a chegarem. Também pode olhar para a base de dados para verificar se foram adicionadas novas entradas.

Neste exercício, expandimos seu conhecimento sobre associações para associações de saída e gravação de dados em seu Azure Cosmos DB. Adicionamos uma associação de saída para postar mensagens em uma fila do Azure. Este exemplo demonstra o verdadeiro poder das associações para ajudá-lo a moldar e mover dados de fontes de entrada para vários destinos. Não escrevemos código de base de dados nem tivemos de gerir cadeias de ligação. Em vez disso, configuramos associações declarativamente e permitimos que a plataforma cuide de proteger conexões, dimensionar nossa função e dimensionar nossas conexões.

Continuar