Criar APIs sem servidor no Visual Studio com Funções do Azure e integração de Gestão de API

  • Artigo

As APIs REST são frequentemente descritas com uma definição OpenAPI. Este ficheiro contém informações sobre operações numa API e como os dados de pedido e resposta da API devem ser estruturados.

Neste tutorial, ficará a saber como:

  • Criar um projeto de função sem servidor no Visual Studio
  • Testar as APIs da função localmente com a funcionalidade OpenAPI incorporada
  • Publicar um projeto numa aplicação de funções no Azure com Gestão de API integração
  • Obtenha a chave de acesso da função e defina-a em Gestão de API
  • Transferir o ficheiro de definição openAPI

A função sem servidor que cria fornece uma API que lhe permite determinar se uma reparação de emergência numa turbina eólica é económica. Uma vez que tanto a aplicação de funções como Gestão de API instância que criar utilizam planos de consumo, o custo para concluir este tutorial é mínimo.

Nota

A integração openAPI e Gestão de API apresentada neste artigo é atualmente suportada apenas para funções de biblioteca de classeS C# em processo. Processo de trabalho isolado As funções de biblioteca de classes C# e todos os outros runtimes de idioma devem, em vez disso, utilizar a integração do Azure Gestão de API a partir do portal.

Pré-requisitos

Criar um projeto de Funções

O modelo de projeto Funções do Azure no Visual Studio cria um projeto que pode publicar numa aplicação de funções no Azure. Também irá criar uma função acionada por HTTP que suporte a geração de ficheiros de definição OpenAPI (anteriormente ficheiro Swagger).

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

  2. Em Criar um novo projeto, introduza funções na caixa de pesquisa, selecione o modelo Funções do Azure e, em seguida, selecione Seguinte.

  3. Em Configurar o seu novo projeto, introduza um Nome de projeto para o projeto como TurbineRepaire, em seguida, selecione Criar.

  4. Para criar um novo Funções do Azure definições da aplicação, utilize os valores na tabela seguinte:

    Definição Valor Descrição
    Função de trabalho .NET 6 Este valor cria um projeto de função que é executado em processo na versão 4.x do Funções do Azure runtime, que é necessário para a geração de ficheiros OpenAPI.
    Modelo de função Acionador HTTP com OpenAPI Este valor cria uma função acionada por um pedido HTTP, com a capacidade de gerar um ficheiro de definição OpenAPI.
    Utilizar o Azurite para a conta de armazenamento de runtime (AzureWebJobsStorage) Selecionado Pode utilizar o emulador para o desenvolvimento local de funções de acionador HTTP. Uma vez que uma aplicação de funções no Azure necessita de uma conta de armazenamento, uma é atribuída ou criada quando publica o projeto no Azure.
    Nível de autorização Função Ao executar no Azure, os clientes têm de fornecer uma chave ao aceder ao ponto final. Para obter mais informações sobre chaves e autorização, veja teclas de acesso de funções.

    Funções do Azure definições do projeto

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

O Visual Studio cria um projeto e uma classe com o nome Function1 que contém código boilerplate para o tipo de função de acionador HTTP. Em seguida, substitua este código de modelo de função pelo seu próprio código personalizado.

Atualizar o código da função

A função utiliza um acionador HTTP que utiliza dois parâmetros:

Nome do parâmetro Descrição
horas O tempo estimado para fazer uma reparação de turbina, até à hora inteira mais próxima.
capacidade A capacidade da turbina, em quilowatts.

Em seguida, a função calcula quanto custa uma reparação e a quantidade de receita que a turbina pode obter num período de 24 horas. Os parâmetros são fornecidos na cadeia de consulta ou no payload de um pedido POST.

No ficheiro de projeto Function1.cs, substitua o conteúdo do código da biblioteca de classes gerado pelo seguinte código:

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; } 
    }
}

Este código de função devolve uma mensagem de Yes ou No para indicar se uma reparação de emergência é económica. Também devolve a oportunidade de receita que a turbina representa e o custo para corrigir a turbina.

Executar e verificar a API localmente

Quando executa a função, os pontos finais OpenAPI facilitam a experimentação da função localmente através de uma página gerada. Não precisa de fornecer chaves de acesso de funções ao executar localmente.

  1. Prima F5 para iniciar o projeto. Quando o runtime das Funções é iniciado localmente, é apresentado um conjunto de pontos finais OpenAPI e Swagger na saída, juntamente com o ponto final da função.

  2. No seu browser, abra o ponto final RenderSwaggerUI, que deverá ter o aspeto http://localhost:7071/api/swagger/uide . É composta uma página, com base nas definições de OpenAPI.

  3. Selecione POST>Experimentar, introduza valores para hours e capacity como parâmetros de consulta ou no corpo do pedido JSON e selecione Executar.

    IU do Swagger para testar a API TurbineRepair

  4. Quando introduz valores inteiros como 6 para hours e 2500 para capacity, obtém uma resposta JSON semelhante ao seguinte exemplo:

    Dados JSON de resposta da função TurbineRepair.

Agora, tem uma função que determina a rentabilidade das reparações de emergência. Em seguida, vai publicar o projeto e as definições de API no Azure.

Publicar o projeto no Azure

Antes de poder publicar o projeto, tem de ter uma aplicação de funções na sua subscrição do Azure. A publicação do Visual Studio cria uma aplicação de funções na primeira vez que publicar o seu projeto. Também pode criar uma instância Gestão de API que se integra na sua aplicação de funções para expor a API TurbineRepair.

  1. No Explorador de Soluções, clique com o botão direito do rato no projeto e selecione Publicar e, em Destino, selecione Azure e Seguinte.

  2. Para o destino Específico, selecione Aplicação de Funções do Azure (Windows) para criar uma aplicação de funções que é executada no Windows e, em seguida, selecione Seguinte.

  3. Na Instância de Função, selecione + Criar uma nova Função do Azure....

    Criar uma nova instância da aplicação de funções

  4. Crie uma nova instância com os valores especificados na tabela seguinte:

    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 carateres válidos são: a-z, 0-9e -.
    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 a sua aplicação de funções. Selecione um grupo de recursos existente na lista pendente ou selecione Novo para criar um novo grupo de recursos.
    Tipo de Plano Consumo Quando publica o seu projeto numa aplicação de funções que é executada num plano de Consumo, paga apenas pelas execuções da sua aplicação de funções. Outros planos de alojamento incorrem em custos mais elevados.
    Localização Localização do serviço Escolha uma Localização numa região perto de si ou de outros serviços aos quais as suas funções acedem.
    Armazenamento do Azure Conta de armazenamento para fins gerais É necessária uma conta de Armazenamento do Azure pelo runtime de Funções. Selecione Novo para configurar uma conta de armazenamento para fins gerais. Também pode escolher uma conta existente que cumpra os requisitos da conta de armazenamento.

    Criar uma nova aplicação de funções no Azure com Armazenamento

  5. Selecione Criar para criar uma aplicação de funções e os respetivos recursos relacionados no Azure. O estado da criação de recursos é apresentado no canto inferior esquerdo da janela.

  6. Novamente na instância de Funções, certifique-se de que a opção Executar a partir do ficheiro de pacote está selecionada. A sua aplicação de funções é implementada com a Implementação Zip com o modo Run-From-Package ativado. Este método de implementação é recomendado para o projeto de funções, uma vez que resulta num melhor desempenho.

  7. Selecione Seguinte e, na página Gestão de API, também selecione + Criar uma API de Gestão de API.

  8. Crie uma API no Gestão de API utilizando valores na tabela seguinte:

    Definição Valor Descrição
    Nome da API TurbineRepair Nome da 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 a sua aplicação de funções na lista pendente.
    serviço Gestão de API Nova instância Selecione Novo para criar uma nova instância Gestão de API no escalão sem servidor.

    Criar Gestão de API instância com a API

  9. Selecione Criar para criar a instância Gestão de API com a API TurbineRepair a partir da integração da função.

  10. selecione Concluir, verifique se a página Publicar diz Pronto para publicar e, em seguida, selecione Publicar para implementar o pacote que contém os ficheiros do projeto na sua nova aplicação de funções no Azure.

    Após a conclusão da implementação, o URL de raiz da aplicação de funções no Azure é apresentado no separador Publicar .

Obter a chave de acesso da função

  1. No separador Publicar, selecione as reticências (...) junto a Alojamento e selecione Abrir no portal do Azure. A aplicação de funções que criou é aberta no portal do Azure no browser predefinido.

  2. Em Funções, selecione Funções>TurbineRepair e, em seguida, selecione Teclas de função.

    Obter uma chave de acesso para a função TurbineRepair

  3. Em Teclas de função, selecione predefinição e copie o valor. Agora, pode definir esta chave em Gestão de API para que possa aceder ao ponto final da função.

Configurar a Gestão de API

  1. No separador Publicar, selecione as reticências (...) junto a Alojamento e selecione Abrir API no portal do Azure. A instância Gestão de API que criou é aberta no portal do Azure no browser predefinido. Esta instância Gestão de API já está ligada à sua aplicação de funções.

  2. Em APIs, selecione Documento OpenAPI no Funções do Azure>Post Run e, em Seguida, em Processamento de entrada, selecione Adicionar política.

    Adicionar uma política de entrada à API

  3. Abaixo do Processamento de entrada, em Definir parâmetros de consulta, escreva codenome, selecione +Valor, cole na chave de função copiada e selecione Guardar. Gestão de API inclui a chave de função quando transmite chamadas para o ponto final da função.

    Fornecer credenciais de Função à regra de processamento de entrada da API

Agora que a chave de função está definida, pode chamar a API para verificar se funciona quando está alojada no Azure.

Verificar a API no Azure

  1. Na API, selecione o separador Teste e, em seguida, PÓS-Execução, introduza o seguinte código no Corpo> do pedidoRaw e selecione Enviar:

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

    Página de teste OpenAPI na API de Gestão de API

    Tal como anteriormente, também pode fornecer os mesmos valores que os parâmetros de consulta.

  2. Selecione Enviar e, em seguida, veja a resposta HTTP para verificar se os mesmos resultados são devolvidos a partir da API.

Transferir a definição OpenAPI

Se a sua API funcionar conforme esperado, pode transferir a definição OpenAPI.

    1. Em APIs, selecione Documento OpenAPI no Funções do Azure, selecione as reticências (...) e selecione Exportar.

    Transferir a definição OpenAPI

  2. Escolha os meios de exportação de API, incluindo ficheiros OpenAPI em vários formatos. Também pode exportar APIs do Azure Gestão de API para o Power Platform.

Limpar os 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 portal do Azure ou home page, selecione Grupos de recursos. Em seguida, na página Grupos de recursos , selecione o grupo que criou.

Na página myResourceGroup , certifique-se de que os recursos listados são os que pretende eliminar.

Selecione Eliminar grupo de recursos, escreva o nome do seu grupo na caixa de texto a confirmar e, em seguida, selecione Eliminar.

Passos seguintes

Utilizou o Visual Studio 2022 para criar uma função auto-documentada devido à Extensão OpenAPI e integrada com Gestão de API. Agora, pode refinar a definição no Gestão de API no portal. Também pode saber mais sobre Gestão de API.

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