Exercício – Ler dados com associações de entrada

20 minutos

Imagine que você queira criar um serviço de pesquisa simples de favoritos. Inicialmente, o serviço é somente leitura. Se os usuários quiserem localizar uma entrada, eles enviarão uma solicitação com a ID da entrada e nossa função retornará a URL. O fluxograma a seguir ilustra o fluxo lógico.

Quando um usuário envia uma solicitação com texto, a função de localizar favorito tenta localizar uma entrada no banco de dados que contenha um favorito com o texto como uma chave ou ID. O sistema retorna um resultado que indica se você encontrou a entrada.

Ao receber uma solicitação com uma ID do favorito, a função do Azure primeiro verifica se ela é válida. Se não for, uma resposta de erro será gerada. Se a solicitação for válida, a função verificará se a ID do favorito existe no banco de dados Azure Cosmos DB. Se não existir, uma resposta de erro será gerada. Caso a ID do indicador seja encontrada, uma resposta de êxito será gerada.

É necessário armazenar os dados em algum lugar. No fluxograma anterior, o armazenamento de dados é mostrado como uma instância do Azure Cosmos DB. Mas como você se conecta ao banco de dados por meio de uma função e lê os dados? No cenário de funções, você configura uma associação de entrada para esse trabalho. A configuração de uma associação de entrada por meio do portal do Azure é simples. Como você vê em breve, você não precisa escrever código ou abrir uma conexão de armazenamento. O Azure Functions Runtime e as associações cuidam dessas tarefas para você.

Criar uma conta do Azure Cosmos DB

Observação

Este exercício não pretende ser um tutorial sobre o Azure Cosmos DB. Se você estiver interessado em saber mais, consulte o roteiro de aprendizagem completo sobre o Azure Cosmos DB no final deste módulo.

Criar uma conta de banco de dados

Uma conta de banco de dados é um contêiner para o gerenciamento de um ou mais bancos de dados. Antes de criarmos um banco de dados, precisamos criar uma conta de banco de dados.

No menu de recursos do portal do Azure ou na página inicial, selecione Criar um recurso. O painel Criar um recurso será exibido.
No menu Criar um recurso, selecione Bancos de dados, depois pesquise e escolha Azure Cosmos DB. O painel Qual API melhor se adapta à sua carga de trabalho? é exibido.
Na opção Azure Cosmos DB for NoSQL, selecione Criar para que possamos criar um gatilho do Cosmos DB e as associações de entrada/saída. O painel Criar Conta do Azure Cosmos DB – Azure Cosmos DB for NoSQL é exibido.

Na guia Básico, insira os valores a seguir para cada configuração.

Configuração	Valor	Descrição
Detalhes do projeto
Subscription	Assinatura do Concierge	A assinatura do Azure que funciona com os recursos na área restrita.
Grupo de recursos	Na lista suspensa, selecione o [nome do grupo de recursos da área restrita]	O grupo de recursos da sua área restrita.
Detalhes da Instância
Nome da Conta	`globally unique name`	Insira um nome exclusivo, mas identificável para a sua conta do Azure Cosmos DB; `documents.azure.com` será acrescentado ao nome que você fornecer. `3 - 50 lowercase characters, numbers, or hyphens (-)`.
Localização	`region`	Selecione a região mais próxima de você.

Aceite os valores padrão para as configurações restantes e selecione Revisar + criar para validar sua entrada. Uma notificação de Validação bem-sucedida é exibida.
Selecione Criar para provisionar e implantar a conta do banco de dados.
A implantação pode levar algum tempo. Aguarde uma mensagem de Implantação bem-sucedida no Hub de notificações para continuar.
Selecione Ir para recurso para navegar até a conta do banco de dados no portal. O painel Início Rápido é exibido para sua conta do Azure Cosmos DB.

Em seguida, adicionamos um contêiner e, em seguida, adicionamos um banco de dados à conta do Azure Cosmos DB.

Adicionar um contêiner

No Azure Cosmos DB, um contêiner é usado para armazenar uma variedade de entidades geradas pelo usuário, também chamadas de itens. Criamos um contêiner chamado Indicadores.

Vamos usar a ferramenta Data Explorer para criar um banco de dados e um contêiner.

No menu da conta do Azure Cosmos DB, selecione Data Explorer. O painel Data Explorer da sua conta do Azure Cosmos DB é exibido.
Selecione a caixa Novo Contêiner. O painel Novo Contêiner é exibido. Talvez seja necessário rolar para vê-lo.

Insira os valores a seguir para cada configuração.

Configuração	Valor	Descrição
ID do banco de dados	Selecione Criar e insira func-io-learn-db para a ID do Banco de Dados	Nomes de bancos de dados podem ter de 1 a 255 caracteres e não podem conter `/, \\, #, ?` ou um espaço à direita. Você pode inserir o que quiser, mas vamos usar func-io-learn-db neste módulo.
Máximo de RU/s do banco de dados	4000	Aceite a taxa de transferência padrão de 4.000 RU/s (unidades de solicitação por segundo). Para reduzir a latência, você pode aumentar o desempenho mais tarde.
ID do contêiner	Indicadores	As IDs do contêiner têm os mesmos requisitos de caractere dos nomes de bancos de dados. Estamos usando Indicadores neste módulo.
Chave de partição	/id	A chave de partição especifica como os documentos em coleções do Azure Cosmos DB são distribuídos em partições de dados lógicos. Usamos a configuração de Chave de partição como uma conveniência aqui porque não estamos preocupados com o desempenho do banco de dados neste módulo. Para saber mais sobre as estratégias de chave de partição do Azure Cosmos DB, explore os módulos do Microsoft Learn sobre o Azure Cosmos DB.

Aceite os padrões para todas as outras configurações.

Role até a parte inferior do painel e selecione OK. Aguarde alguns minutos para que o banco de dados e o contêiner sejam criados.

Quando concluído, o Data Explorer exibe func-io-learn-db em DADOS na API NOSQL.
Selecione func-io-learn-db para expandi-lo. Observe que o banco de dados func-io-learn-db contém vários membros filho, incluindo Escala e Favoritos.
Expanda o contêiner Indicadores. Observe que vários membros filhos já foram pré-preenchidos.

Na próxima tarefa, você adicionará alguns dados, também conhecidos como itens, ao contêiner de Indicadores.

Adicionar dados de teste

Você deseja adicionar dados ao contêiner Favoritos. Use o Data Explorer para armazenar uma URL e uma ID para cada item.

Expanda o banco de dados func-io-learn-db e o contêiner Bookmarks e selecione Itens. A guia Itens é exibida.
Na barra de comandos, selecione Novo Item.

Substitua o código padrão do novo item pelo código JSON a seguir.

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

Na barra de comandos, selecione Salvar.

Observe que são exibidas mais propriedades do que as duas linhas que adicionamos. Todos elas começam com um (_rid, _self, _etag, _attachments, _ts) sublinhado. Essas propriedades, descritas na tabela a seguir, são geradas pelo sistema para ajudar a gerenciar os itens que você adiciona ao contêiner.

Propriedade	Descrição
`_rid`	A ID do recurso é um identificador exclusivo que também é hierárquico de acordo com a pilha de recursos no modelo de recurso. A ID é utilizada internamente para o posicionamento e a navegação do recurso do item.
`_self`	URI endereçável exclusivo do recurso.
`_etag`	Necessário para o controle de simultaneidade otimista.
`_attachments`	O caminho endereçável do recurso de anexos.
`_ts`	O carimbo de data/hora da última atualização deste recurso.

Vamos adicionar mais alguns itens no contêiner Favoritos. Na barra de comandos, selecione Novo Item. Crie mais quatro itens com o seguinte conteúdo. Adicione os itens selecionando Novo Item e, em seguida, selecionando Salvar depois de copiar e colar cada novo item. Observe como cada item é adicionado à lista de itens.
```
{
    "id": "portal",
    "url": "https://portal.azure.com"
}
```
```
{
    "id": "learn",
    "url": "https://learn.microsoft.com/training"
}
```
```
{
    "id": "marketplace",
    "url": "https://azuremarketplace.microsoft.com/marketplace/apps"
}
```
```
{
    "id": "blog",
    "url": "https://azure.microsoft.com/blog"
}
```
Quando você terminar de inserir os dados do indicador, o contêiner deverá ficar semelhante à imagem a seguir.

O contêiner Favoritos tem cinco itens. Nesse cenário, se uma solicitação chegar com "id=docs", ela procurará essa ID em seu contêiner de Indicadores e retornará a URL https://learn.microsoft.com/azure. Vamos criar uma função do Azure que procura valores no contêiner Bookmarks.

Criar sua função

Navegue até o aplicativo de funções que você criou na unidade anterior. No menu de recursos, selecione Página Inicial e, na seção Recursos recentes, você deverá ver seu aplicativo de funções (Tipo igual a Aplicativo de Funções). Selecione seu aplicativo de funções. O painel Aplicativo de Funções é exibido.
Na guia Funções na página Visão geral, você deve ter uma função, HttpTrigger1.
Vamos criar outra função. Selecione Criar na guia Funções. O painel Criar função é exibido, listando modelos de gatilhos com suporte.
Na seção Selecionar um modelo, escolha Gatilho HTTP e selecione Avançar.
Aceite todas as configurações padrão e selecione Criar para criar sua função.

O painel de visão geral da Função HttpTrigger2 é exibido.

Verificar a função

Você pode verificar o nosso progresso até agora testando a nova função.

Na barra de comandos, selecione Obter URL da função. A caixa de diálogo Obter URL da função é exibida.
Selecione padrão (chave de função) na lista suspensa e escolha o ícone Copiar para área de transferência e selecione OK.
Cole a URL da função copiada na barra de endereços de uma nova guia do navegador. Acrescente o valor da cadeia de caracteres de consulta &name=<your name> ao final da URL, substituindo <your name> pelo seu nome e, em seguida, pressione Enter. A função do Azure deve retornar uma resposta personalizada no navegador.

Agora que a função básica está funcionando, vamos voltar a atenção para a leitura de dados no Azure Cosmos DB ou, em nosso cenário, on contêiner Favoritos.

Adicionar uma associação de entrada do Azure Cosmos DB

Para ler dados do banco de dados, você precisa definir uma associação de entrada. Como você vê aqui, você pode configurar uma associação que pode conversar com o seu banco de dados em apenas algumas etapas.

No portal do Azure, no menu Função HttpTrigger2 ao longo da parte superior, selecione Integração. O painel Integração é exibido para sua função.

Você usou um modelo que criou uma solicitação de gatilho HTTP com uma associação de saída HTTP. Vamos adicionar uma associação de entrada do Azure Cosmos DB.
Na caixa Gatilho e entradas, selecione Adicionar entrada. O painel Criar Entrada será exibido.
Na lista suspensa Tipo de Associação, selecione Azure Cosmos DB.
Na seção Detalhes do Azure Cosmos DB, na configuração Conexão da conta do Cosmos DB, selecione o link Nova. A caixa de diálogo Nova conexão do Cosmos DB é exibida.

Se for exibida uma mensagem solicitando que você instale a extensão Microsoft.Azure.WebJobs.Extensions.CosmosDB, selecione Instalar e aguarde a conclusão do processo.
Por padrão, o Azure reconhece a conta do Azure Cosmos DB criada anteriormente. Selecione OK para configurar uma conexão com o banco de dados. Uma nova conexão com o banco de dados é configurada e aparece no campo Conexão da conta do Cosmos DB.

Queremos pesquisar um favorito com uma ID específica, portanto, vamos vincular a ID que recebemos na cadeia de caracteres de consulta à associação.

Vamos preencher as configurações do painel Criar Entrada. Insira os valores a seguir para cada configuração. Para saber mais sobre a finalidade de cada configuração, selecione o ícone de informações no campo desejado.

Configuração	Valor	Descrição
Nome do parâmetro do documento	`bookmark`	O nome usado para identificar essa associação no código.
Nome do banco de dados	`func-io-learn-db`	O banco de dados com o qual trabalhar. Esse valor é o nome do banco de dados que definimos.
Nome da coleção	`Bookmarks`	A coleção da qual lemos os dados. Essa configuração foi definida.
ID do documento	`id`	Adicione a ID do Documento que definimos quando criamos o contêiner Favoritos do Azure Cosmos DB.
Chave de partição	`/id`	Adicione a chave de partição definida ao criar a coleção Favoritos do Azure Cosmos DB. A chave inserida aqui (especificada no formato de associação de entrada `<key>`) deve corresponder à que está na coleção.
Consulta SQL (opcional)	Deixar em branco	Você está recuperando apenas um documento por vez com base na ID. Portanto, a filtragem com a configuração ID do Documento é melhor que o uso de uma Consulta SQL neste caso. Você pode criar uma Consulta SQL para retornar uma entrada (`SELECT * from b where b.ID = id`). Essa consulta, de fato, retornaria um documento, mas em uma coleção de documentos. Seu código precisaria manipular uma coleção desnecessariamente. Use a abordagem de Consulta SQL quando deseja obter vários documentos.

Para esclarecer porque estamos usando essas configurações, queremos pesquisar um indicador com uma ID específica, portanto vinculamos a ID do Documento que nossa função recebe na cadeia de caracteres de consulta à associação de entrada. Essa sintaxe é conhecida como uma expressão de associação. A função é disparada por uma solicitação HTTP que usa uma cadeia de consulta para especificar a ID a ser pesquisada. Como as IDs são exclusivas em nossa coleção, a associação retorna 0 (não encontrado) ou 1 (encontrado).

Para salvar essa configuração de associação de entrada, selecione Adicionar.

Atualizar implementação da função

Agora que sua associação está definida, você pode usá-la em sua função. Você precisa fazer duas alterações para implementar a associação que você criou:

Modifique o código de implementação específico do idioma da função. Ele precisa determinar se um documento foi encontrado no banco de dados que corresponde à ID passada para a função.
Modifique o código de implementação JSON da sua função para aceitar um parâmetro que é passado na cadeia de caracteres de consulta.

Modificar o código de implementação do JavaScript da função

No menu Função da função HttpTrigger2, selecione Codificar + Testar. O painel Codificar + Testar da função HttpTrigger2 será exibido.

Substitua todo o código no arquivo index.js pelo código a seguir.

module.exports = function (context, req) {

    var bookmark = context.bindings.bookmark

    if(bookmark){
        context.res = {
        body: { "url": bookmark.url },
        headers: {
            'Content-Type': 'application/json'
        }
        };
    }
    else {
        context.res = {
            status: 404,
            body : "No bookmarks found",
            headers: {
            'Content-Type': 'application/json'
            }
        };
    }

    context.done();
};

Na barra de comandos, selecione Salvar. Selecione Logs do Sistema de Arquivos na lista suspensa no centro superior do painel de logs (que exibe Logs do App Insights por padrão). O painel Logs é exibido, mostrando que você tem Connected!

Vamos examinar o que esse código está fazendo.

Uma solicitação HTTP de entrada dispara a função e um parâmetro de consulta id é passado para a associação de entrada do Azure Cosmos DB.
Se o banco de dados encontrar um documento que corresponda a essa ID, o parâmetro bookmark será definido como o documento localizado.

Neste exemplo, o código constrói uma resposta que contém o valor da URL encontrado no documento correspondente do banco de dados.
Se não for encontrado nenhum documento correspondente a essa chave, a solicitação responderá com um conteúdo e um código de status que dê a má notícia ao usuário.

Modificar o código de implementação JSON da função

Selecione function.json na lista suspensa no caminho <functionapp> \ HttpTrigger2 \.

Substitua todo o código no arquivo function.json pelo código a seguir. Substitua your-database pelo nome da sua conta do Azure Cosmos DB.

{
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "res"
    },
    {
      "name": "bookmark",
      "direction": "in",
      "type": "cosmosDB",
      "partitionKey": "{id}",
      "databaseName": "func-io-learn-db",
      "containerName": "Bookmarks",
      "connection": "your-database_DOCUMENTDB",
      "id": "{id}",
    }
  ]
}

Na barra de comandos, selecione Salvar.

Modificar o código de implementação PowerShell da função

No menu Função da função HttpTrigger2, selecione Codificar + Testar. O painel Codificar + Testar da função HttpTrigger2 será exibido, mostrando o arquivo run.ps1.

Substitua todo o código no arquivo run.ps1 pelo código a seguir.

using namespace System.Net

param($Request, $bookmark, $TriggerMetadata)

if ($bookmark) {
    $status = [HttpStatusCode]::OK
    $body = @{ url = $bookmark.url }
}
else {
    $status = [HttpStatusCode]::NotFound
    $body = "No bookmarks found"
}

Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = $status
    Body = $body
})

Na barra de comandos, selecione Salvar. Selecione Logs do Sistema de Arquivos na lista suspensa no centro superior do painel de logs (que exibe Logs do App Insights por padrão). O painel Logs é exibido, mostrando que você tem Connected!

Vamos examinar o que esse código está fazendo.

Uma solicitação HTTP de entrada dispara a função e um parâmetro de consulta id é passado para a associação de entrada do Azure Cosmos DB.
Se o banco de dados encontrar um documento que corresponda a essa ID, o parâmetro bookmark será definido como o documento localizado.

Neste exemplo, o código constrói uma resposta que contém o valor da URL encontrado no documento correspondente do banco de dados.
Se não for encontrado nenhum documento correspondente a essa chave, a solicitação responderá com um conteúdo e um código de status que dê a má notícia ao usuário.

Modificar o código de implementação JSON da função

Selecione function.json na lista suspensa no caminho <functionapp> \ HttpTrigger2 \.

Modifique os valores para id e partitionKey a fim de que aceitem um parâmetro de {id}. Seu código function. json deve ser semelhante ao exemplo a seguir, em que your-database é substituído pelo nome do seu banco de dados Cosmos DB.

{
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "Request",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "Response"
    },
    {
      "type": "cosmosDB",
      "name": "bookmark",
      "databaseName": "func-io-learn-db",
      "containerName": "Bookmarks",
      "connection": "your-database_DOCUMENTDB",
      "direction": "in",
      "id": "{id}",
      "partitionKey": "{id}"
    }
  ]
}

Na barra de comandos, selecione Salvar.

Experimente

Você já deve estar no painel Codificar + Testar da sua função HttpTrigger2.
Na barra de comandos, escolha Obter URL da função. A caixa de diálogo Obter URL da função é exibida.
Na lista suspensa Chave, selecione Padrão em Chave de funçãoe selecione o ícone Copiar para área de transferência no final da URL.
Cole a chave da função que você copiou na barra de endereços de uma nova guia do navegador e, em seguida, adicione o valor da cadeia de caracteres de consulta &id=docs ao final da URL. A URL resultante deve ser semelhante ao exemplo a seguir:

https://example.azurewebsites.net/api/HttpTrigger2?code=AbCdEfGhIjKlMnOpQrStUvWxYz==&id=docs
Pressione Enter para executar a solicitação. A resposta retornada pela função deve ser semelhante ao exemplo a seguir.
```
{
  "url": "https://learn.microsoft.com/azure"
}
```
Substitua &id=docs por &id=missing, pressione Enter e observe a resposta. Definimos cinco favoritos e criamos uma resposta de erro significativa para o caso do indicador solicitado não existir.

Nesta unidade, você criou sua primeira associação de entrada manualmente para fazer a leitura de um banco de dados do Azure Cosmos DB. A quantidade de código que você escreveu para pesquisar o banco de dados e ler os dados foi mínima, graças às associações. Você fez a maior parte do trabalho configurando a associação de maneira declarativa e a plataforma cuidou do resto.

Na próxima unidade, você adicionará mais dados à coleção de indicadores por meio de uma associação de saída do Azure Cosmos DB.

Exercício – Ler dados com associações de entrada

Criar uma conta do Azure Cosmos DB

Criar uma conta de banco de dados

Adicionar um contêiner

Adicionar dados de teste

Criar sua função

Verificar a função

Adicionar uma associação de entrada do Azure Cosmos DB

Atualizar implementação da função

Modificar o código de implementação do JavaScript da função

Modificar o código de implementação JSON da função

Modificar o código de implementação PowerShell da função

Modificar o código de implementação JSON da função

Experimente

Comentários