Criar APIs sem servidor no Visual Studio usando o Azure Functions e o Gerenciamento de API

As APIs REST geralmente são descritas usando um arquivo de definição OpenAPI (anteriormente conhecido como Swagger). Este arquivo contém informações sobre operações em uma API e como os dados de solicitação e resposta para a API devem ser estruturados.

Neste tutorial, você aprenderá a:

A função sem servidor criada fornece uma API que permite determinar se um reparo de emergência em uma turbina de vento é econômico. Como você cria o aplicativo de funções e a instância de Gerenciamento de API em uma camada de consumo, o custo para concluir este tutorial é mínimo.

Pré-requisitos

• Visual Studio 2022. Verifique se você selecionou a carga de trabalho de desenvolvimento do Azure durante a instalação.

• Se você não tiver uma assinatura do Azure ativa, crie uma conta gratuita antes de começar.

Criar o projeto de código

O modelo de projeto do Azure Functions no Visual Studio cria um projeto que você pode publicar em um aplicativo de funções no Azure. Você também criará uma função disparada por HTTP a partir de um modelo que dá suporte à geração de arquivo de definição OpenAPI (antigo arquivo Swagger).

1. No menu do Visual Studio, selecione Arquivo>Novo>Projeto.

2. Em Criar um projeto, insira funções na caixa de pesquisa, escolha o modelo Azure Functions e, em seguida, selecione Próximo.

3. Em Configurar seu novo projeto, insira um Nome de projeto para seu projeto, como TurbineRepair, e selecione Criar.

4. Para o Criar um novo aplicativo do Azure Functions configurações, selecione uma dessas opções para o trabalhador do Functions, sendo que a opção que você escolher depende do modelo de processo escolhido:

   • Modelo de trabalho isolado
   • Em processo

   .NET 8.0 Isolado (Suporte a Longo Prazo): suas funções C# são executadas no modelo de trabalho isolado, o que é recomendado. Para obter mais informações, consulte o guia do modelo de trabalho isolado.

5. Para o restante das opções, use os valores na tabela a seguir:

   Configuração	Valor	Descrição
   Modelo de função	Empty (vazio)	Isso cria um projeto sem um gatilho, o que lhe dá mais controle sobre o nome da função disparada por HTTP quando você o adiciona mais tarde.
   Usar Azurite para runtime de conta de armazenamento (AzureWebJobsStorage)	Selected	O emulador pode ser usado para o desenvolvimento local de funções de gatilho HTTP. Como um aplicativo de funções no Azure requer uma conta de armazenamento, ela será atribuída ou criada quando você publicar seu projeto no Azure.
   Nível de autorização	Função	Em execuções no Azure, os clientes devem fornecer uma chave ao acessar o ponto de extremidade. Para obter mais informações, consulte Nível de autorização.

6. Selecione Criar para criar o projeto de função.

Em seguida, você atualiza o projeto instalando a extensão OpenAPI para o Azure Functions, que permite a descoberta de pontos de extremidade de API em seu aplicativo.

Instalar a extensão OpenAPI

Para instalar a extensão OpenAPI:

1. No menu Ferramentas, selecione Gerenciador de Pacotes NuGet>Console do Gerenciador de Pacotes.

2. No console, execute o seguinte comando Install-Package para instalar a extensão OpenAPI:

   • Modelo de trabalho isolado
   • Modelo em processo

   NuGet\Install-Package Microsoft.Azure.Functions.Worker.Extensions.OpenApi -Version 1.5.1
   

   Talvez seja necessário atualizar a versão específica, com base na sua versão do .NET.

Agora, você pode adicionar sua função de ponto de extremidade HTTP.

Adicionar uma função de ponto de extremidade HTTP

Em uma biblioteca de classes C#, as associações usadas pela função são definidas aplicando atributos no código. Para criar uma função com um gatilho HTTP:

1. No Gerenciador de Soluções, clique com o botão direito do mouse no nó do seu projeto e selecione Adicionar>Novo Azure Function.

2. Insira Turbine.cs para a classe e selecione Adicionar.

3. Escolha o modelo de Gatilho de HTTP, defina o nível de autorização como Função e, em seguida, selecione Adicionar. Um arquivo de código Turbine.cs é adicionado ao seu projeto que define um novo ponto de extremidade de função com um gatilho HTTP.

Agora você pode substituir o código do modelo de gatilho HTTP pelo código que implementa o ponto de extremidade da função Turbine, juntamente com atributos que usam OpenAPI para definir o ponto de extremidade.

Atualizar o código de função

A função usa um gatilho HTTP que emprega dois parâmetros:

Em seguida, a função calculará o custo do reparo e a receita gerada pela turbina em um período de 24 horas. Os parâmetros são fornecidos na cadeia de caracteres de consulta ou na carga de uma solicitação POST.

No arquivo de projeto Turbine.cs, substitua o conteúdo da classe gerada do modelo de gatilho HTTP pelo seguinte código, que depende do modelo de processo:

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.Attributes;
using Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.Enums;
using Microsoft.Extensions.Logging;
using Microsoft.OpenApi.Models;
using Newtonsoft.Json;
using System.Net;

namespace TurbineRepair
{
    public class Turbine
    {
        const double revenuePerkW = 0.12;
        const double technicianCost = 250;
        const double turbineCost = 100;

        private readonly ILogger<Turbine> _logger;

        public Turbine(ILogger<Turbine> logger)
        {
            _logger = logger;
        }

        [Function("TurbineRepair")]
        [OpenApiOperation(operationId: "Run")]
        [OpenApiSecurity("function_key", SecuritySchemeType.ApiKey, Name = "code", In = OpenApiSecurityLocationType.Query)]
        [OpenApiRequestBody("application/json", typeof(RequestBodyModel),
            Description = "JSON request body containing { hours, capacity}")]
        [OpenApiResponseWithBody(statusCode: HttpStatusCode.OK, contentType: "application/json", bodyType: typeof(string),
            Description = "The OK response message containing a JSON result.")]
        public static async Task<IActionResult> Run(
            [HttpTrigger(AuthorizationLevel.Function, "post", Route = null)] HttpRequest req,
            ILogger log)
        {
            // Get request body data.
            string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
            dynamic? data = JsonConvert.DeserializeObject(requestBody);
            int? capacity = data?.capacity;
            int? hours = data?.hours;

            // Return bad request if capacity or hours are not passed in
            if (capacity == null || hours == null)
            {
                return new BadRequestObjectResult("Please pass capacity and hours in the request body");
            }
            // Formulas to calculate revenue and cost
            double? revenueOpportunity = capacity * revenuePerkW * 24;
            double? costToFix = hours * technicianCost + turbineCost;
            string repairTurbine;

            if (revenueOpportunity > costToFix)
            {
                repairTurbine = "Yes";
            }
            else
            {
                repairTurbine = "No";
            };

            return new OkObjectResult(new
            {
                message = repairTurbine,
                revenueOpportunity = "$" + revenueOpportunity,
                costToFix = "$" + costToFix
            });
        }
        public class RequestBodyModel
        {
            public int Hours { get; set; }
            public int Capacity { get; set; }
        }
    }
}

using System;
using System.IO;
using System.Net;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.Attributes;
using Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.Enums;
using Microsoft.Extensions.Logging;
using Microsoft.OpenApi.Models;
using Newtonsoft.Json;

namespace TurbineRepair
{
    public static class Turbine
    {
        const double revenuePerkW = 0.12;
        const double technicianCost = 250;
        const double turbineCost = 100;

        [FunctionName("TurbineRepair")]
        [OpenApiOperation(operationId: "Run")]
        [OpenApiSecurity("function_key", SecuritySchemeType.ApiKey, Name = "code", In = OpenApiSecurityLocationType.Query)]
        [OpenApiRequestBody("application/json", typeof(RequestBodyModel), 
            Description = "JSON request body containing { hours, capacity}")]
        [OpenApiResponseWithBody(statusCode: HttpStatusCode.OK, contentType: "application/json", bodyType: typeof(string),
            Description = "The OK response message containing a JSON result.")]
        public static async Task<IActionResult> Run(
            [HttpTrigger(AuthorizationLevel.Function, "post", Route = null)] HttpRequest req,
            ILogger log)
        {
            // Get request body data.
            string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
            dynamic data = JsonConvert.DeserializeObject(requestBody);
            int? capacity = data?.capacity;
            int? hours = data?.hours;

            // Return bad request if capacity or hours are not passed in
            if (capacity == null || hours == null)
            {
                return new BadRequestObjectResult("Please pass capacity and hours in the request body");
            }
            // Formulas to calculate revenue and cost
            double? revenueOpportunity = capacity * revenuePerkW * 24;
            double? costToFix = (hours * technicianCost) + turbineCost;
            string repairTurbine;

            if (revenueOpportunity > costToFix)
            {
                repairTurbine = "Yes";
            }
            else
            {
                repairTurbine = "No";
            };

            return (ActionResult)new OkObjectResult(new
            {
                message = repairTurbine,
                revenueOpportunity = "$" + revenueOpportunity,
                costToFix = "$" + costToFix
            });
        }
    }
    public class RequestBodyModel
    {
        public int Hours { get; set; }
        public int Capacity { get; set; } 
    }
}

Esse código de função retorna uma mensagem de Yes ou No para indicar se um reparo de emergência é econômico. Ele também retorna a oportunidade de receita que a turbina representa e o custo para reparar a turbina.

Executar e verificar a API localmente

Quando você executa a função, os pontos de extremidade OpenAPI facilitam o teste local da função com o uso de uma página gerada. Você não precisa fornecer chaves de acesso de função em execuções locais.

1. Pressione F5 para iniciar o projeto. Quando o tempo de execução do Functions é iniciado localmente, um conjunto de pontos de extremidade OpenAPI e Swagger é mostrado na saída, juntamente com o ponto de extremidade da função.

2. No navegador, abra o ponto de extremidade RenderSwaggerUI, que deve ser parecido com http://localhost:7071/api/swagger/ui. É renderizada uma página com base nas suas definições de OpenAPI.

3. Selecione POST>Experimentar, insira valores para hours e capacity, seja como parâmetros de consulta ou no corpo da solicitação JSON, e selecione Executar.

   

4. Ao inserir valores inteiros, como 6 para hours e 2500 para capacity, você obterá uma resposta JSON semelhante a este exemplo:

   

Agora você tem uma função que determina o custo-benefício de reparos de emergências. Em seguida, publique seu projeto e as definições de API no Azure.

Publicar o projeto no Azure

Antes de publicar o projeto, você deve ter um aplicativo de funções em sua assinatura do Azure. A publicação do Visual Studio cria um aplicativo de funções para você na primeira publicação do seu projeto. Ela também pode criar uma instância do Gerenciamento de API que se integre ao seu aplicativo de funções para expor a API TurbineRepair.

1. No Gerenciador de Soluções, clique com o botão direito do mouse no projeto e selecione Publicar. Depois, em Destino, selecione Azure e Avançar.

2. Para o Destino específico, escolha Aplicativo Azure Function (Windows) , para criar um aplicativo de funções executado no Windows, e selecione Avançar.

3. Em Instância de Função, escolha + Criar uma nova função do Azure... .

   

4. Crie uma instância usando os valores especificados nesta tabela:

   Configuração	Valor	Descrição
   Nome	Nome globalmente exclusivo	Nome que identifica seu novo aplicativo de funções de forma exclusiva. Aceite esse nome ou insira um novo nome. Os caracteres válidos são: a-z, 0-9 e -.
   Assinatura	Sua assinatura	A assinatura do Azure a utilizar. Aceite esta assinatura ou selecione uma nova na lista suspensa.
   Grupo de recursos	Nome do seu grupo de recursos	O grupo de recursos no qual criar o seu aplicativo de funções. Selecione um grupo de recursos existente na lista suspensa ou escolha Novo para criar um grupo de recursos.
   Tipo de Plano	Consumo	Quando você publica seu projeto em um aplicativo de funções executado em um Plano de consumo, você paga apenas pelas execuções do seu aplicativo de funções. Outros planos de hospedagem incorrem em custos mais altos.
   Localidade	Local do serviço	Escolha um Local em uma região perto de você ou de outros serviços acessados pelas suas funções.
   Armazenamento do Azure	Conta de armazenamento para uso geral	Uma conta do Armazenamento do Azure é requerida pelo runtime do Functions. Selecione Novo para configurar uma conta de armazenamento para uso geral. Você também pode escolher uma conta existente que atenda aos requisitos da conta de armazenamento.

   

5. Selecione Criar para criar um aplicativo de funções e recursos relacionados no Azure. O status da criação do recurso é mostrado na parte inferior esquerda da janela.

6. Na Instância do Functions, verifique se Executar no arquivo do pacote está marcado. Seu aplicativo de funções é implantado usando a Implantação de Zip com o modo Run-From-Package habilitado. Esse método de implantação é recomendado para o seu projeto do Functions, pois resulta em melhor desempenho.

7. Selecione Próximo e, na página Gerenciamento de API, escolha também + Criar uma API no Gerenciamento de API.

8. Crie uma API no Gerenciamento de API usando os valores da tabela a seguir:

   Configuração	Valor	Descrição
   Nome da API	TurbineRepair	Nome da API.
   Nome da assinatura	Sua assinatura	A assinatura do Azure a utilizar. Aceite esta assinatura ou selecione uma nova na lista suspensa.
   Grupo de recursos	Nome do seu grupo de recursos	Selecione o mesmo grupo de recursos do aplicativo de funções na lista suspensa.
   Serviço de Gerenciamento de API	Nova instância	Selecione Novo para criar uma nova instância de Gerenciamento de API no mesmo local na camada sem servidor. Selecione OK para criar a instância.

   

9. Selecione Criar para criar a instância do Gerenciamento de API com a API TurbineRepair da integração de funções.

10. Selecione Concluir e, após a conclusão do processo de criação do perfil de publicação, selecione Fechar.

11. Verifique se a página Publicar agora diz Pronto para publicar e, em seguida, selecione Publicar para implantar o pacote que contém seus arquivos de projeto em seu novo aplicativo de funções no Azure.

    Concluída a implantação, a URL raiz do aplicativo de funções no Azure é mostrada na guia Publicar.

Obter a chave de acesso de função

1. Na guia publicar, selecione as reticências ( ... ), ao lado de Hospedagem, e Abrir no portal do Azure. O aplicativo de funções criado é aberto no portal do Azure, no seu navegador padrão.

2. Em Functions na página visão geral, selecione >Turbina e, em seguida, selecione teclas de Função.

   

3. Em teclas de Função, selecione o ícone Copiar para área de transferência ao lado da chave de padrão. Agora você pode definir essa chave copiada no Gerenciamento de API para que ela possa acessar o ponto de extremidade da função.

Configurar o Gerenciamento de API

1. Na página do aplicativo de funções, expanda a API e selecione Gerenciamento de API.

2. Se o aplicativo de funções ainda não estiver conectado à nova instância de Gerenciamento de API, selecione-o no Gerenciamento de API, selecione API>Documento OpenaPI da API no Azure Functions, verifique se as funções de importação estão marcadas e selecione API de Link. Verifique se apenas TurbineRepair está selecionado para importação e, em seguida, Selecionar.

3. Selecione Ir para o Gerenciamento de API na parte superior da página e, na instância de Gerenciamento de API, expanda APIs.

4. Em APIs>Todas as APIs, selecione Documento OpenAPI no Azure Functions>POST Run e, em Processamento de entrada selecione Adicionar política>Definir parâmetros de consulta.

5. Abaixo de Processamento de entrada, em Definir parâmetros de consulta, digite code para Nome, selecione +Valor, cole na chave de função copiada e selecione Salvar. O Gerenciamento de API inclui a chave de função quando passa chamadas para o ponto de extremidade da função.

   

Agora que a chave de função está definida, você pode chamar o ponto de extremidade da API turbine para verificar se ela funciona quando hospedada no Azure.

Verificar a API no Azure

1. Na API, selecione a guia Testar e Execução de POST, insira o código a seguir no Corpo da solicitação>Rawe selecione Enviar:

   {
       "hours": "6",
       "capacity": "2500"
   }
   

   

   Como antes, você pode fornecer os mesmos valores dos parâmetros de consulta.

2. Selecione Enviar e veja a resposta HTTPpara verificar se a API retorna os mesmos resultados.

Baixar a definição de OpenAPI

Se a API funcionar conforme o esperado, você poderá baixar a definição de OpenAPI para as novas APIs hospedadas do Gerenciamento de API.

1. 1. Em APIs, selecione Documento OpenAPI no Azure Functions, selecione as reticências (...) e Exportar.

   

2. Escolha os meios de exportação de API, inclusive arquivos OpenAPI em vários formatos. Você também pode exportar APIs do Gerenciamento de API do Azure para o Power Platform.

Limpar os recursos

Nas etapas anteriores, você criou os recursos do Azure em um grupo de recursos. Se você não espera precisar desses recursos no futuro, poderá excluí-los ao excluir o grupo de recursos.

No menu do portal do Azure ou na Página inicial, selecione Grupos de recursos. Na página Grupos de recursos, selecione o grupo que você criou.

Na página myResourceGroup, certifique-se de que os recursos listados são aqueles que deseja excluir.

Selecione Excluir grupo de recursos, digite o nome do seu grupo na caixa de texto para confirmar e selecione Excluir.

Próximas etapas

Você usou o Visual Studio 2022 para criar uma função que é auto-documentada devido à Extensão OpenAPI e integrada ao Gerenciamento de API. Você já pode refinar a definição no Gerenciamento de API no portal. Também é possível saber mais sobre o Gerenciamento de API.