Exercício – ler dados com enlaces de entrada

20 minutos

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

Quando um usuário envia uma solicitação com texto, a função localizar marcador tenta encontrar uma entrada em seu banco de dados que contém um marcador com o texto como chave ou ID. O sistema retorna um resultado que indica se você encontrou a entrada.

Quando a função do Azure recebe uma solicitação com uma ID de indicador, ela primeiro verifica se a solicitação é válida. Se não estiver, uma resposta de erro será gerada. Se a solicitação for válida, a função verificará se a ID do indicador existe no banco de dados do Azure Cosmos DB. Se não existir, é gerada uma resposta de erro. Se o ID do marcador for encontrado, será gerada uma resposta de êxito.

Tem de armazenar os dados em algum lado. No fluxograma anterior, o armazenamento de dados é uma instância do Azure Cosmos DB. Mas, como você se conecta a um banco de dados a partir de uma função e lê dados? No mundo das funções, vai configurar um enlace de entrada para essa tarefa. Configurar uma associação de entrada por meio do portal do Azure é simples. Como você verá em breve, você não precisa escrever código ou abrir uma conexão de armazenamento. Os enlaces e o runtime das Funções do Azure tratam dessas tarefas automaticamente.

Criar uma conta do Azure Cosmos DB

Nota

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

Criar uma conta de base de dados

Uma conta de base de dados é um contentor para gerir uma ou mais bases de dados. Antes de podermos criar uma base de dados, é necessário criar uma conta de base de dados.

No menu de recursos do portal do Azure ou na página inicial, selecione Criar um recurso. O painel Criar um recurso é exibido.
No menu Criar um recurso, selecione Bancos de Dados e, em seguida, procure e selecione Azure Cosmos DB. O painel Qual API melhor se adapta à sua carga de trabalho? é exibido.
Na opção Azure Cosmos DB para NoSQL, selecione Criar para que possamos criar um gatilho do Cosmos DB e ligações de entrada/saída. O painel Criar Conta do Azure Cosmos DB - Azure Cosmos DB para NoSQL é exibido.

Na guia Noções básicas, insira os seguintes valores para cada configuração.

Definição	valor	Description
Detalhes do Projeto
Subscrição	Subscrição de Assistente	A assinatura do Azure que funciona com os recursos na área restrita.
Grupo de Recursos	Na lista suspensa, selecione [nome do grupo de recursos da área restrita]	O grupo de recursos para sua área restrita.
Detalhes da instância
Nome da Conta	`globally unique name`	Insira um nome exclusivo, mas identificável, para sua conta do Azure Cosmos DB; `documents.azure.com` é anexado ao nome fornecido. `3 - 50 lowercase characters, numbers, or hyphens (-)`.
Location	`region`	Selecione a região mais próxima de si.

Aceite os valores padrão para as configurações restantes e selecione Revisar + criar para validar sua entrada. É apresentada uma notificação de Êxito da Validação.
Selecione Criar para provisionar e implantar uma conta de banco de dados.
A implementação pode demorar algum tempo. Aguarde uma mensagem de Implantação bem-sucedida no hub de Notificações antes de continuar.
Selecione Ir para recurso para ir para a conta de banco de dados no portal. O painel Início rápido da sua conta do Azure Cosmos DB é exibido.

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

Adicionar um contentor

Em um Azure Cosmos DB, um contêiner é usado para armazenar várias entidades geradas pelo usuário, também chamadas de itens. Criamos um contêiner chamado Favoritos.

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

No menu da sua conta do Azure Cosmos DB, selecione Data Explorer. O painel Data Explorer da sua conta do 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 seguintes valores para cada configuração.

Definição	valor	Description
ID da base de dados	Selecione Criar novo e insira func-io-learn-db para a ID do banco de dados	Os nomes dos bancos de dados podem ter de 1 a 255 caracteres e não podem conter `/, \\, #, ?`, nem um espaço à direita. Você pode inserir o que quiser, mas estamos usando func-io-learn-db neste módulo.
Banco de dados Max RU/s	4000	Aceite a taxa de transferência padrão de 4000 unidades de solicitação por segundo (RU/s). Para reduzir a latência, você pode aumentar o desempenho mais tarde.
ID do contentor	Marcadores	Os IDs dos contentores têm os mesmos requisitos em termos de carateres que os nomes das bases de dados. Estamos usando Favoritos neste módulo.
Chave de partição	/id	A chave de partição especifica a forma como os documentos nas coleções do Azure Cosmos DB são distribuídos em partições de dados lógicas. 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 principais estratégias de partição do Azure Cosmos DB, explore os módulos do Microsoft Learn Azure Cosmos DB.

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

Desloque-se para 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 DATA sob NOSQL API.
Selecione func-io-learn-db para expandi-lo. Observe que seu banco de dados func-io-learn-db contém vários membros filho, incluindo Scale e Bookmarks.
Expanda o contêiner Favoritos . Observe que vários membros filhos já o preenchem previamente.

Na próxima tarefa, você adiciona alguns dados, também conhecidos como itens, ao contêiner Favoritos.

Adicionar dados de teste

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

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

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

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

Na barra de comandos, selecione Salvar.

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

Property	Description
`_rid`	ID de recurso é um identificador exclusivo que também é hierárquico pela pilha de recursos no modelo de recurso. O ID é usado internamente para posicionamento e navegação do recurso do item.
`_self`	URI endereçável exclusivo para o recurso.
`_etag`	É necessário para o controlo da simultaneidade otimista.
`_attachments`	Caminho endereçável para o recurso de anexos.
`_ts`	Carimbo de data/hora da última atualização deste recurso.

Vamos adicionar mais alguns itens ao contêiner Favoritos . Na barra de comandos, selecione Novo Item. Crie mais quatro itens com o conteúdo seguinte. 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 terminar de inserir os dados do marcador, seu contêiner deverá se parecer com a imagem a seguir.

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

Criar a função

Vá para o aplicativo de função que você criou na unidade anterior. No menu de recursos, selecione Página Inicial e, na seção Recursos recentes, você verá seu aplicativo de função (Tipo é igual a Aplicativo de Função). Selecione a sua aplicação de funções. O painel Aplicativo de função é 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 de funções Criar é exibido, listando modelos para gatilhos suportados.
Na seção Selecione um modelo, selecione Gatilho HTTP e, em seguida, selecione Avançar.
Aceite todas as configurações padrão e selecione Criar para criar sua função.

O painel Visão geral da função HttpTrigger2 é exibido.

Verificar a função

Você pode verificar 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 (tecla de função) na lista suspensa, selecione o ícone Copiar para área de transferência e selecione OK.
Cole o URL da função que você copiou na barra de endereço de uma nova guia do navegador. Anexe o valor &name=<your name> da cadeia de caracteres de consulta ao final da URL, substituindo <your name> pelo seu nome, e pressione Enter. A função do Azure deve retornar uma resposta personalizada no navegador.

Agora que temos nossa função esquelética funcionando, vamos voltar nossa atenção para a leitura de dados do seu Azure Cosmos DB ou, em nosso cenário, do contêiner de Favoritos .

Adicionar um enlace de entrada do Azure Cosmos DB

Para ler dados da base de dados, tem de definir um enlace de entrada. Como você vê aqui, você pode configurar uma associação que pode falar com seu banco de dados em apenas algumas etapas.

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

Você usou um modelo que criou uma solicitação de gatilho HTTP com uma ligaçã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 é exibido.
Na lista suspensa Tipo de vinculação, selecione Azure Cosmos DB.
Na seção Detalhes do Azure Cosmos DB, na configuração de conexão da conta do Cosmos DB, selecione o link Novo. A caixa de diálogo Nova conexão do Cosmos DB é exibida.

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

Queremos procurar um marcador com um ID específico, então vamos vincular o ID que recebemos na cadeia de caracteres de consulta à associação.

Vamos concluir as configurações no painel Criar entrada . Insira os seguintes valores para cada configuração. Para saber mais sobre a finalidade de cada configuração, selecione o ícone de informações nesse campo.

Definição	valor	Description
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. Esse valor é o nome do banco de dados que definimos.
Nome da Coleção	`Bookmarks`	A recolha a partir da qual lemos os dados. Esse cenário foi definido.
ID do Documento	`id`	Adicione a ID do documento que definimos quando criamos o contêiner Bookmarks Azure Cosmos DB.
Chave de partição	`/id`	Adicione a chave de partição que você definiu quando criou a coleção Bookmarks Azure Cosmos DB. A chave introduzida aqui (especificada no formato de enlace de entrada `<key>`) deve corresponder à presente na coleção.
Consulta SQL (opcional)	Deixar em branco	Você está recuperando apenas um documento de cada vez com base na ID. Portanto, filtrar com a configuração ID do documento é melhor do que usar uma consulta SQL nesta instância. Poderia criar uma Consulta SQL para devolver uma entrada (`SELECT * from b where b.ID = id`). Essa consulta iria, de facto, devolver um documento, mas iria devolvê-lo numa coleção de documentos. O seu código teria de manipular uma coleção desnecessariamente. Utilize a abordagem de Consulta SQL quando quiser obter múltiplos documentos.

Para esclarecer por que estamos usando essas configurações, 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 de entrada. Esta sintaxe é conhecida como uma expressão de enlace. A função é acionada por um pedido HTTP que utiliza uma cadeia de consulta para especificar o ID a procurar. Como os IDs são exclusivos em nossa coleção, a associação retorna 0 (não encontrado) ou 1 (encontrado) documentos.

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

Atualizar a implementação da função

Agora que sua ligaçã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 sua função. Ele precisa determinar se um documento foi encontrado no banco de dados que corresponde ao ID que é passado para a função.
Modifique o código de implementação JSON da sua função para que ele aceite um parâmetro que é passado na cadeia de caracteres de consulta.

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

No menu Função da função HttpTrigger2, selecione Código + Teste. O painel Código + Teste é exibido para sua função HttpTrigger2 .

Substitua todo o código no arquivo index.js com o 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 os 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.

Um pedido HTTP de entrada aciona a função e é transmitido um parâmetro de consulta id para o enlace de entrada do Azure Cosmos DB.
Se o banco de dados encontrar um documento que corresponda a essa ID, o bookmark parâmetro será definido como o documento localizado.

Neste exemplo, o código constrói uma resposta que contém o valor de URL encontrado no documento correspondente do banco de dados.
Se nenhum documento for encontrado que corresponda a essa chave, a solicitação responderá com uma carga útil e um código de status que informa ao usuário as más notícias.

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

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

Substitua todo o código no arquivo function.json com o código a seguir. Certifique-se e 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 do PowerShell da sua função

No menu Função da função HttpTrigger2, selecione Código + Teste. O painel Código + Teste aparece para sua função HttpTrigger2 , exibindo o run.ps1 arquivo.

Substitua todo o código no run.ps1 arquivo 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 os 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.

Um pedido HTTP de entrada aciona a função e é transmitido um parâmetro de consulta id para o enlace de entrada do Azure Cosmos DB.
Se o banco de dados encontrar um documento que corresponda a essa ID, o bookmark parâmetro será definido como o documento localizado.

Neste exemplo, o código constrói uma resposta que contém o valor de URL encontrado no documento correspondente do banco de dados.
Se nenhum documento for encontrado que corresponda a essa chave, a solicitação responderá com uma carga útil e um código de status que informa ao usuário as más notícias.

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

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

Modifique os valores para id e partitionKey para que eles aceitem um parâmetro de {id}. Seu código function.json deve ser semelhante ao exemplo a seguir, onde your-database é substituído pelo nome do banco de dados do 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 Código + Teste para sua função HttpTrigger2 .
Na barra de comandos, selecione Obter URL da função. A caixa de diálogo Obter URL da função é exibida.
Na lista suspensa Chave, selecione o padrão em Tecla de função e, em seguida, selecione o ícone Copiar para área de transferência no final da URL.
Cole a tecla de função copiada na barra de endereço de um novo separador do browser e, em seguida, adicione o valor &id=docs da cadeia de caracteres de consulta ao final do URL. O URL resultante deve ser semelhante ao seguinte exemplo:

https://example.azurewebsites.net/api/HttpTrigger2?code=AbCdEfGhIjKlMnOpQrStUvWxYz==&id=docs
Pressione Enter para executar a solicitação. A resposta retornada pela sua 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 marcadores e criamos uma resposta de erro significativa se o marcador solicitado não existir.

Nesta unidade, criou o seu primeiro enlace de entrada manualmente para ler a partir de uma base de dados do Azure Cosmos DB. A quantidade de código que escreveu para procurar na nossa base de dados e ler dados foi mínima, graças aos enlaces. Você fez a maior parte do seu trabalho configurando a vinculação declarativamente, e a plataforma cuidou do resto.

Na unidade seguinte, irá adicionar mais dados à nossa coleção de marcadores através do enlace de saída do Azure Cosmos DB.

Exercício – ler dados com enlaces de entrada

Criar uma conta do Azure Cosmos DB

Criar uma conta de base de dados

Adicionar um contentor

Adicionar dados de teste

Criar a função

Verificar a função

Adicionar um enlace de entrada do Azure Cosmos DB

Atualizar a implementação da função

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

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

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

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

Experimente

Comentários