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

Artigo
06/01/2023

APIs REST geralmente são descritas usando uma definição de OpenAPI. 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á como:

Criar um projeto de função sem servidor no Visual Studio
Testar APIs de função localmente usando a funcionalidade interna OpenAPI
Publicar um projeto em um aplicativo de funções no Azure com integração do Gerenciamento de API
Obter a chave de acesso para a função e defini-la no Gerenciamento de API
Baixar o arquivo de definição de OpenAPI

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 o aplicativo de funções e a instância do Gerenciamento de API que você cria usam planos de consumo, seu custo para concluir este tutorial é mínimo.

Observação

Atualmente, a integração do OpenAPI e do Gerenciamento de API apresentada neste artigo tem suporte apenas para funções da biblioteca de classes C# em processo. Funções da biblioteca de classes C# em processo de trabalho isolado e todos os outros runtimes de idioma devem usar a integração de Gerenciamento de API do Azure no portal.

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 um projeto do Functions

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 deverá criar uma função HTTP acionada que ofereça suporte à geração do arquivo de definição OpenAPI (antigo arquivo Swagger).

No menu do Visual Studio, selecione Arquivo>Novo>Projeto.
Em Criar um projeto, insira funções na caixa de pesquisa, escolha o modelo Azure Functions e, em seguida, selecione Próximo.
Em Configurar seu novo projeto, insira um Nome de projeto para seu projeto, como TurbineRepair, e selecione Criar.

Para as configurações de Criar um aplicativo do Azure Functions, use os valores da tabela a seguir:

Configuração	Valor	Descrição
Função de trabalho do Functions	.NET 6	Esse valor cria um projeto de função que é executado em processo na versão 4.x do runtime do Azure Functions, que é necessário para a geração de arquivos OpenAPI.
Modelo de função	Gatilho HTTP com OpenAPI	Esse valor cria uma função acionada por uma solicitação HTTP, com a capacidade de gerar um arquivo de definição de OpenAPI.
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 sobre chaves e autorização, consulte Chaves de acesso de função.

Configurações do projeto do Azure Functions

Selecione Criar para criar o projeto de função e a função de gatilho HTTP, com suporte para OpenAPI.

O Visual Studio cria um projeto e uma classe chamada Function1 que contém o código clichê do tipo de função do gatilho HTTP. Em seguida, substitua esse código de modelo de função pelo seu próprio, personalizado.

Atualizar o código de função

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

Nome do parâmetro	Descrição
horas	Tempo estimado para um reparo de turbina até a hora inteira mais próxima.
capacidade	A capacidade da turbina, em quilowatts.

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 Function1.cs, substitua o conteúdo do código da biblioteca de classes gerado por este:

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 Turbines
    {
        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.

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.
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.
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.
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.

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.
Para o Destino específico, escolha Aplicativo Azure Function (Windows) , para criar um aplicativo de funções executado no Windows, e selecione Avançar.
Em Instância de Função, escolha + Criar uma nova função do Azure... .

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.

Criar um novo aplicativo de funções no Azure com Armazenamento

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.
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.
Selecione Próximo e, na página Gerenciamento de API, escolha também + Criar uma API no Gerenciamento de API.

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 do Gerenciamento de API na camada sem servidor.

Criar uma instância do Gerenciamento de API do Azure

Selecione Criar para criar a instância do Gerenciamento de API com a API TurbineRepair da integração de funções.
Selecione Concluir, verifique se a página Publicar informa Pronto para publicação e selecione Publicar, para implantar no novo aplicativo de funções no Azure o pacote que contém os arquivos do projeto.

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

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.
Em Funções, selecione Funções>TurbineRepair e Chaves de função.
Em Teclas de função, selecione padrão e copie o valor. Agora você pode definir essa chave no Gerenciamento de API para que possa acessar o ponto de extremidade da função.

Configurar o Gerenciamento de API

Na guia Publicar, selecione as reticências ( ... ), ao lado de Hospedagem, e Abrir API no portal do Azure. A instância do Gerenciamento de API que você criou é aberta no portal do Azure no navegador padrão. Esta instância do Gerenciamento de API já está vinculada ao seu aplicativo de funções.
Em APIs, selecione Documento OpenAPI no Azure Functions>Execução de POST e, em Processamento de Entrada, selecione Adicionar política.
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.

Com a chave de função definida, você pode chamar a API para verificar se ela funciona quando hospedada no Azure.

Verificar a API no Azure

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.
Selecione Enviar e veja a resposta HTTPpara verificar se a API retorna os mesmos resultados.

Baixar a definição de OpenAPI

Se sua API funcionar conforme esperado, será possível baixar a definição de OpenAPI.

1. Em APIs, selecione Documento OpenAPI no Azure Functions, selecione as reticências (...) e Exportar.
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 autodocumentada devido à Extensão OpenAPI e a integrou 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.

Editar a definição de OpenAPI no Gerenciamento de API