Criar APIs sem servidor no Visual Studio usando o Azure Functions e a integração do Gerenciamento de API
APIs REST são frequentemente descritas usando um arquivo de definição OpenAPI (anteriormente conhecido como Swagger). Esse 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, irá aprender a:
- Criar o projeto de código no Visual Studio
- Instale a extensão OpenAPI
- Adicione um ponto de extremidade de gatilho HTTP, que inclui definições de OpenAPI
- Teste APIs de função localmente usando a funcionalidade OpenAPI integrada
- Publicar projeto em um aplicativo de função no Azure
- Habilite a integração do Gerenciamento de API
- Baixe o arquivo de definição OpenAPI
A função sem servidor que você cria fornece uma API que permite determinar se um reparo de emergência em uma turbina eólica é econômico. Como você cria o aplicativo de função e a instância de Gerenciamento de API em uma camada de consumo, seu custo para concluir este tutorial é mínimo.
Pré-requisitos
Visual Studio 2022. Certifique-se de selecionar a carga de trabalho de desenvolvimento do Azure durante a instalação.
Uma assinatura ativa do Azure, 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ção no Azure. Você também criará uma função acionada por HTTP a partir de um modelo que suporte a geração de arquivos de definição OpenAPI (anteriormente Swagger file).
No menu Visual Studio, selecione Arquivo>Novo>Projeto.
Em Criar um novo projeto, insira funções na caixa de pesquisa, escolha o modelo Azure Functions e selecione Avançar.
Em Configurar seu novo projeto, insira um nome de projeto para seu projeto como
TurbineRepaire, em seguida, selecione Criar.Para criar um novo aplicativo do Azure Functions, selecione uma destas opções para o trabalhador do Functions, onde a opção escolhida depende do modelo de processo escolhido:
.NET 8.0 Isolado (Suporte de 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 de modelo de trabalhador isolado.
Para o restante das opções, use os valores na tabela a seguir:
Definição valor Description Modelo de função Vazio Isso cria um projeto sem um gatilho, o que lhe dá mais controle sobre o nome da função acionada HTTP quando você a adiciona mais tarde. Usar o Azurite para a conta de armazenamento em tempo de execução (AzureWebJobsStorage) Selecionados Você pode usar o emulador para o desenvolvimento local de funções de gatilho HTTP. Como um aplicativo de função no Azure requer uma conta de armazenamento, uma é atribuída ou criada quando você publica seu projeto no Azure. Nível de autorização Função Ao executar 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. Selecione Criar para criar o projeto de função.
Em seguida, atualize o projeto instalando a extensão OpenAPI para Azure Functions, que permite a descoberta de pontos de extremidade de API em seu aplicativo.
Instale a extensão OpenAPI
Para instalar a extensão OpenAPI:
No menu Ferramentas, selecione Console do Gerenciador> de Pacotes NuGet.
No console, execute o seguinte comando Install-Package para instalar a extensão OpenAPI:
NuGet\Install-Package Microsoft.Azure.Functions.Worker.Extensions.OpenApi -Version 1.5.1Talvez 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:
No Gerenciador de Soluções, clique com o botão direito do mouse no nó do projeto e selecione Adicionar>Nova Função do Azure.
Introduza Turbine.cs para a classe e, em seguida, selecione Adicionar.
Escolha o modelo de gatilho Http, defina Nível de autorização como Função e 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 por 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 da função
A função usa um gatilho HTTP que usa dois parâmetros:
| Nome do parâmetro | Description |
|---|---|
| hours | O tempo estimado para fazer um reparo da turbina, até a hora inteira mais próxima. |
| capacidade | A capacidade da turbina, em quilowatts. |
Em seguida, a função calcula quanto custa um reparo e quanto a turbina poderia gerar em um período de 24 horas. Os parâmetros são fornecidos na cadeia de caracteres de consulta ou na carga útil de uma solicitação POST.
No arquivo de projeto Turbine.cs, substitua o conteúdo da classe gerada a partir do modelo de gatilho HTTP pelo seguinte código, que depende do seu 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; }
}
}
}
Este código de função devolve uma mensagem de ou No para indicar se uma reparação de Yes emergência é rentável. Ele também retorna a oportunidade de receita que a turbina representa e o custo para consertar a turbina.
Executar e verificar a API localmente
Quando você executa a função, os pontos de extremidade OpenAPI facilitam a experimentação da função localmente usando uma página gerada. Você não precisa fornecer teclas de acesso de função ao executar localmente.
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 são mostrados na saída, juntamente com o ponto de extremidade da função.
No navegador, abra o ponto de extremidade RenderSwaggerUI, que deve se parecer com
http://localhost:7071/api/swagger/ui. Uma página é renderizada, com base em suas definições de OpenAPI.Selecione POST>Experimente, insira valores para
hoursecapacitycomo parâmetros de consulta ou no corpo da solicitação JSON e selecione Executar.
Quando você insere valores inteiros como 6 para
hourse 2500 paracapacity, obtém uma resposta JSON semelhante ao exemplo a seguir:
Agora, tem uma função que determina a rentabilidade das reparações de emergência. Em seguida, você publica suas definições de projeto e API no Azure.
Publicar o projeto no Azure
Antes de publicar seu projeto, você deve ter um aplicativo de função em sua assinatura do Azure. A publicação do Visual Studio cria um aplicativo de função na primeira vez que você publica seu projeto. Ele também pode criar uma instância de Gerenciamento de API que se integra ao seu aplicativo de função para expor a API TurbineRepair.
No Gerenciador de Soluções, clique com o botão direito do mouse no projeto e selecione Publicar e, em Destino, selecione Azure e Avançar.
Para o destino Específico, escolha Aplicativo de Função do Azure (Windows) para criar um aplicativo de função executado no Windows e selecione Avançar.
Em Instância de Função, escolha + Criar uma nova Função do Azure....
Crie uma nova instância usando os valores especificados na tabela a seguir:
Definição valor Descrição Nome Nome globalmente exclusivo Nome que identifica exclusivamente a sua nova aplicação de funções. Aceite este nome ou introduza um novo nome. Os caracteres válidos são: a-z,0-9, e-.Subscrição a sua subscrição A subscrição do Azure que deve utilizar. Aceite esta subscrição ou selecione uma nova na lista pendente. Grupo de recursos Nome do grupo de recursos O grupo de recursos no qual criar seu aplicativo de função. Selecione um grupo de recursos existente na lista suspensa ou escolha Novo para criar um novo grupo de recursos. Tipo de Plano Consumo Quando você publica seu projeto em um aplicativo de função que é 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. Location Localização do serviço Escolha um local em uma região perto de você ou outros serviços que suas funções acessam. Armazenamento do Azure Conta de armazenamento de uso geral Uma conta de Armazenamento do Azure é exigida pelo tempo de execução do Functions. Selecione Novo para configurar uma conta de armazenamento de uso geral. Você também pode escolher uma conta existente que atenda aos requisitos da conta de armazenamento. 
Selecione Criar para criar um aplicativo de função e seus recursos relacionados no Azure. O status da criação de recursos é mostrado no canto inferior esquerdo da janela.
De volta à instância Functions, verifique se a opção Executar do arquivo do pacote está marcada. Seu aplicativo de função é implantado usando o Zip Deploy com o modo Run-From-Package habilitado. Este método de implementação é recomendado para o seu projeto de funções, uma vez que resulta num melhor desempenho.
Selecione Avançar e, na página Gerenciamento de API, escolha também + Criar uma API de Gerenciamento de API.
Crie uma API no Gerenciamento de API usando valores na tabela a seguir:
Definição valor Description Nome da API TurbineRepair Nome para a API. Nome da subscrição a sua subscrição A subscrição do Azure que deve utilizar. Aceite esta subscrição ou selecione uma nova na lista pendente. Grupo de recursos Nome do grupo de recursos Selecione o mesmo grupo de recursos que seu aplicativo de função 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. 
Selecione Criar para criar a instância de Gerenciamento de API com a API TurbineRepair a partir da integração de funções.
Selecione Concluir e, após a conclusão do processo de criação do perfil de publicação, selecione Fechar.
Verifique se a página Publicar agora diz Pronto para publicar e selecione Publicar para implantar o pacote que contém seus arquivos de projeto em seu novo aplicativo de função no Azure.
Após a conclusão da implantação, a URL raiz do aplicativo de função no Azure é mostrada na guia Publicar .
Obter a tecla de acesso da função
Na guia Publicar, selecione as reticências (...) ao lado de Hospedagem e selecione Abrir no portal do Azure. O aplicativo de função que você criou é aberto no portal do Azure em seu navegador padrão.
Em Funções na página Visão geral, selecione >Turbina e, em seguida, selecione Teclas de função.
Em Teclas de função, selecione o ícone Copiar para a área de transferência ao lado da tecla 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 a Gestão de API
Na página do aplicativo de função, expanda API e selecione Gerenciamento de API.
Se o aplicativo de função ainda não estiver conectado à nova instância de Gerenciamento de API, selecione-o em Gerenciamento de API, selecione Documento OpenAPI da API>no Azure Functions, verifique se a opção Importar funções está marcada e selecione Vincular API. Certifique-se de que apenas TurbineRepair está selecionado para importação e, em seguida, Selecionar.
Selecione Ir para Gerenciamento de API na parte superior da página e, na instância de Gerenciamento de API, expanda APIs.
Em APIs>Todas as APIs, selecione OpenAPI Document on Azure Functions>POST Run e, em Processamento de entrada, selecione Adicionar política>Definir parâmetros de consulta.
Abaixo de Processamento de entrada, em Definir parâmetros de consulta, digite
codeNome, selecione +Valor, cole a tecla de função copiada e selecione Salvar. O Gerenciamento de API inclui a tecla de função quando ela 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 turbine API para verificar se ele funciona quando hospedado no Azure.
Verificar a API no Azure
Na API, selecione a guia Test e, em seguida, POST Run, insira o seguinte código no Request body>Raw e selecione Enviar:
{ "hours": "6", "capacity": "2500" }
Como antes, você também pode fornecer os mesmos valores que os parâmetros de consulta.
Selecione Enviar e exiba a resposta HTTP para verificar se os mesmos resultados são retornados da API.
Faça o download da definição da OpenAPI
Se sua API funcionar conforme o esperado, você poderá baixar a definição de OpenAPI para as novas APIs hospedadas do Gerenciamento de API.
-
- Em APIs, selecione OpenAPI Document on Azure Functions, selecione as reticências (...) e selecione Exportar.
Escolha os meios de exportação de API, incluindo arquivos OpenAPI em vários formatos. Você também pode exportar APIs do Gerenciamento de API do Azure para a Power Platform.
Clean up resources (Limpar recursos)
Nos passos anteriores, criou os recursos do Azure num grupo de recursos. Se provavelmente não necessitar desses recursos no futuro, pode eliminá-los ao eliminar o grupo de recursos.
No menu do portal do Azure ou na página inicial , selecione Grupos de recursos. Em seguida, 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 você deseja excluir.
Selecione Eliminar grupo de recursos, escreva o nome do grupo na caixa de texto a confirmar e, em seguida, selecione Eliminar.
Próximos passos
Você usou o Visual Studio 2022 para criar uma função que é autodocumentável por causa da extensão OpenAPI e integrada ao Gerenciamento de API. Agora você pode refinar a definição em Gerenciamento de API no portal. Você também pode saber mais sobre o Gerenciamento de API.