Crie uma definição de OpenAPI para uma API sem servidor usando o Gerenciamento de API do AzureCreate an OpenAPI definition for a serverless API using Azure API Management

APIs REST geralmente são descritas usando uma definição de OpenAPI.REST APIs are often described using an OpenAPI definition. Esta definição contém informações sobre as operações que estão disponíveis em uma API e como os dados de solicitação e resposta para a API devem ser estruturados.This definition contains information about what operations are available in an API and how the request and response data for the API should be structured.

Neste tutorial, você deve criar uma função que determina se um reparo de emergência em uma turbina eólica é eficaz em termos de custo.In this tutorial, you create a function that determines whether an emergency repair on a wind turbine is cost-effective. Em seguida, crie uma definição de OpenAPI para o aplicativo de funções usando o Gerenciamento de API do Azure para que a função possa ser chamada de outros aplicativos e serviços.You then create an OpenAPI definition for the function app using Azure API Management so that the function can be called from other apps and services.

Neste tutorial, você aprenderá como:In this tutorial, you learn how to:

  • Criar uma função no AzureCreate a function in Azure
  • Gerar uma definição de OpenAPI usando o Gerenciamento de API do AzureGenerate an OpenAPI definition using Azure API Management
  • Testar a definição chamando a funçãoTest the definition by calling the function
  • Baixar a definição de OpenAPIDownload the OpenAPI definition

Criar um aplicativo de funçõesCreate a function app

Você deve ter um aplicativo de funções para hospedar a execução de suas funções.You must have a function app to host the execution of your functions. Um aplicativo de funções lhe permite agrupar funções como uma unidade lógica para facilitar o gerenciamento, a implantação, o dimensionamento e o compartilhamento de recursos.A function app lets you group functions as a logical unit for easier management, deployment, scaling, and sharing of resources.

  1. Selecione o botão Criar um recurso no canto superior esquerdo do portal do Azure e selecione Computação > Aplicativo de funções.Select the Create a resource button found on the upper left-hand corner of the Azure portal, then select Compute > Function App.

    Criar um aplicativo de funções no portal do Azure

  2. Use as configurações do aplicativo de funções especificadas na tabela abaixo da imagem.Use the function app settings as specified in the table below the image.

    Definir novas configurações do aplicativo de funções

    ConfiguraçãoSetting Valor sugeridoSuggested value DESCRIÇÃODescription
    Nome do aplicativoApp name Nome globalmente exclusivoGlobally unique name Nome que identifica seu novo aplicativo de funções.Name that identifies your new function app. Os caracteres válidos são a-z, 0-9 e -.Valid characters are a-z, 0-9, and -.
    AssinaturaSubscription Sua assinaturaYour subscription A assinatura na qual este novo aplicativo de funções será criado.The subscription under which this new function app is created.
    Grupo de RecursosResource Group myResourceGroupmyResourceGroup Nome do novo grupo de recursos no qual criar o seu aplicativo de funções.Name for the new resource group in which to create your function app.
    SOOS WindowsWindows As opções de linguagem disponíveis dependem do sistema operacional do aplicativo de funções.The language options available depend on the OS of the function app. Por exemplo, o Python requer o Linux.For example, Python requires Linux.
    Plano de hospedagemHosting plan Plano de consumoConsumption plan Plano de hospedagem que define como os recursos são alocados para seu aplicativo de funções.Hosting plan that defines how resources are allocated to your function app. No Plano de Consumo padrão, os recursos são adicionados dinamicamente conforme exigido por suas funções.In the default Consumption Plan, resources are added dynamically as required by your functions. Nesta hospedagem sem servidor, você só paga pelo tempo durante o qual suas funções são executadas.In this serverless hosting, you only pay for the time your functions run. Quando você executa em um Plano do Serviço de Aplicativo, deve gerenciar o dimensionamento do aplicativo de funções.When you run in an App Service plan, you must manage the scaling of your function app.
    LocalidadeLocation Europa OcidentalWest Europe Escolha uma região perto de você ou perto de outros serviços que suas funções acessam.Choose a region near you or near other services your functions access.
    Pilha de tempo de execuçãoRuntime stack Linguagem preferencialPreferred language Escolha um tempo de execução compatível com sua linguagem de programação de funções favorita.Choose a runtime that supports your favorite function programming language. Escolha .NET para funções C# e F#.Choose .NET for C# and F# functions.
    ArmazenamentoStorage Nome globalmente exclusivoGlobally unique name Crie uma conta de armazenamento usada pelo seu aplicativo de funções.Create a storage account used by your function app. Os nomes da conta de armazenamento devem ter entre 3 e 24 caracteres e podem conter apenas números e letras minúsculas.Storage account names must be between 3 and 24 characters in length and may contain numbers and lowercase letters only. Você também pode usar uma conta existente, mas ela precisa atender aos requisitos da conta de armazenamento.You can also use an existing account, which must meets the storage account requirements.
    Application InsightsApplication Insights PadrãoDefault Cria um recurso do Application Insights do mesmo nome do aplicativo na região com suporte mais próxima.Creates an Application Insights resource of the same App name in the nearest supported region. Ao expandir essa configuração, você pode alterar o Novo nome do recurso ou escolher um Local diferente em uma geografia do Azure onde deseja armazenar seus dados.By expanding this setting, you can change the New resource name or choose a different Location in an Azure geography where you want to store your data.
  3. Selecione Criar para provisionar e implantar o aplicativo de funções.Select Create to provision and deploy the function app.

  4. Selecione o ícone da Notificação no canto superior direito do portal e veja se a mensagem Implantação concluída com êxito é exibida.Select the Notification icon in the upper-right corner of the portal and watch for the Deployment succeeded message.

    Definir novas configurações do aplicativo de funções

  5. Selecione Ir para recursos para exibir o novo aplicativo de funções.Select Go to resource to view your new function app. Você também pode selecionar Fixar no painel.You can also select Pin to dashboard. A fixação torna mais fácil retornar a esse recurso de aplicativo de função no seu painel.Pinning makes it easier to return to this function app resource from your dashboard.

Criar a funçãoCreate the function

Este tutorial usa uma função disparada por HTTP que usa dois parâmetros:This tutorial uses an HTTP triggered function that takes two parameters:

  • O tempo estimado para reparar uma turbina, em horas.The estimated time to make a turbine repair, in hours.
  • A capacidade da turbina, em quilowatts.The capacity of the turbine, in kilowatts.

A função, em seguida, calcula o custo do reparo e o valor da receita que a turbina proporcionaria em um período de 24 horas.The function then calculates how much a repair will cost, and how much revenue the turbine could make in a 24 hour period. PARA criar uma função disparada pelo HTTP no portal do Azure.TO create the HTTP triggered function in the Azure portal.

  1. Expanda seu aplicativo de funções e selecione o botão + ao lado de Functions.Expand your function app and select the + button next to Functions. Selecione No portal > Continuar.Select In-portal > Continue.

  2. Selecione Mais modelos... e, em seguida, Concluir e exibir modelosSelect More templates..., then select Finish and view templates

  3. Selecione o acionador HTTP, digite TurbineRepair para sua função Nome, escolha Function para Nível de autenticação e, em seguida, selecione Criar.Select HTTP trigger, type TurbineRepair for the function Name, choose Function for Authentication level, and then select Create.

    Criar função HTTP para OpenAPI

  4. Substitua o conteúdo do arquivo do script C# run.csx pelo código abaixo e selecione Salvar:Replace the contents of the run.csx C# script file with the following code, then choose Save:

    #r "Newtonsoft.Json"
    
    using System.Net;
    using Microsoft.AspNetCore.Mvc;
    using Microsoft.Extensions.Primitives;
    using Newtonsoft.Json;
    
    const double revenuePerkW = 0.12;
    const double technicianCost = 250;
    const double turbineCost = 100;
    
    public static async Task<IActionResult> Run(HttpRequest req, ILogger log)
    {
        // Get query strings if they exist
        int tempVal;
        int? hours = Int32.TryParse(req.Query["hours"], out tempVal) ? tempVal : (int?)null;
        int? capacity = Int32.TryParse(req.Query["capacity"], out tempVal) ? tempVal : (int?)null;
    
        // Get request body
        string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
        dynamic data = JsonConvert.DeserializeObject(requestBody);
    
        // Use request body if a query was not sent
        capacity = capacity ?? data?.capacity;
        hours = 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 on the query string or 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
        });
    }
    

    Esse código de função retorna uma mensagem de Yes ou No para indicar se um reparo de emergência é econômico, bem como as oportunidades de receita que representa a turbina e o custo para reparar a turbina.This function code returns a message of Yes or No to indicate whether an emergency repair is cost-effective, as well as the revenue opportunity that the turbine represents, and the cost to fix the turbine.

  5. Para testar a função, clique em Testar na extremidade direita para expandir a guia Teste. Digite o seguinte valor para o Corpo da solicitação e clique em Executar.To test the function, click Test at the far right to expand the test tab. Enter the following value for the Request body, and then click Run.

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

    Testar a função no portal do Azure

    O valor a seguir é retornado no corpo da resposta.The following value is returned in the body of the response.

    {"message":"Yes","revenueOpportunity":"$7200","costToFix":"$1600"}
    

Agora você tem uma função que determina o custo-benefício de reparos de emergências.Now you have a function that determines the cost-effectiveness of emergency repairs. Em seguida, você pode gerar uma definição de OpenAPI para o aplicativo de funções.Next, you generate an OpenAPI definition for the function app.

Gerar a definição de OpenAPIGenerate the OpenAPI definition

Agora você está pronto para gerar a definição de OpenAPI.Now you're ready to generate the OpenAPI definition.

  1. Selecione o aplicativo de função; em seguida, em Funcionalidades da plataforma, escolha Gerenciamento de API e selecione Criar novo no Gerenciamento de API.Select the function app, then in Platform features, choose API Management and select Create new under API Management.

    Escolher Gerenciamento de API nas Funcionalidades da Plataforma

  2. Use as configurações de Gerenciamento de API conforme especificado na tabela abaixo da imagem.Use the API Management settings as specified in the table below the image.

    Criar um novo serviço de Gerenciamento de API

    ConfiguraçãoSetting Valor sugeridoSuggested value DescriçãoDescription
    NomeName Nome globalmente exclusivoGlobally unique name Um nome é gerado com base no nome do seu aplicativo de funções.A name is generated based on the name of your function app.
    AssinaturaSubscription Sua assinaturaYour subscription A assinatura na qual este novo recurso será criado.The subscription under which this new resource is created.
    Grupo de RecursosResource Group myResourceGroupmyResourceGroup O mesmo recurso que seu aplicativo de funções, que deve estar definido para você.The same resource as your function app, which should get set for you.
    LocalidadeLocation Oeste dos EUAWest US Escolha o local Oeste dos EUA.Choose the West US location.
    Nome da organizaçãoOrganization name ContosoContoso O nome da organização usado no portal do desenvolvedor e para notificações por email.The name of the organization used in the developer portal and for email notifications.
    Email do administradorAdministrator email seu emailyour email Email que recebeu notificações do sistema de Gerenciamento de API.Email that received system notifications from API Management.
    Tipo de preçosPricing tier Consumo (versão prévia)Consumption (preview) A camada de consumo está em versão prévia e não está disponível em todas as regiões.Consumption tier is in preview and isn't available in all regions. Para obter detalhes completos sobre preços, confira a Página de preços de Gerenciamento de APIFor complete pricing details, see the API Management pricing page
  3. Escolha Criar para criar a instância de Gerenciamento de API, o que pode levar vários minutos.Choose Create to create the API Management instance, which may take several minutes.

  4. Selecione Habilitar o Application Insights para enviar logs para o mesmo local que o aplicativo de função, aceite os padrões restantes e selecione API de link.Select Enable Application Insights to send logs to the same place as the function application, then accept the remaining defaults and select Link API.

  5. Importar Funções do Azure é exibido com a função TurbineRepair realçada.The Import Azure Functions opens with the TurbineRepair function highlighted. Clique em Selecionar para continuar.Choose Select to continue.

    Importar Funções do Azure para o Gerenciamento de API

  6. Na página Criar do Aplicativo de funções, aceite os padrões e selecione CriarIn the Create from Function App page, accept the defaults and select Create

    Criar do Aplicativo de funções

A API foi criada para a função.The API is now created for the function.

Testar a APITest the API

Antes de usar a definição de OpenAPI, você deve verificar se a API funciona.Before you use the OpenAPI definition, you should verify that the API works.

  1. Na guia Testar da sua função, selecione a operação POST.On the Test tab of your function, select POST operation.

  2. Insira valores para horas e capacidadeEnter values for hours and capacity

    {
    "hours": "6",
    "capacity": "2500"
    }
    
  3. Clique em Enviar e exiba a resposta HTTP.Click Send, then view the HTTP response.

    API de função de teste

Baixar a definição de OpenAPIDownload the OpenAPI definition

Se sua API funcionar conforme esperado, será possível baixar a definição de OpenAPI.If your API works as expected, you can download the OpenAPI definition.

  1. Selecione Baixar definição de OpenAPI na parte superior da página.Select Download OpenAPI definition at the top of the page.

    Baixar definição de OpenAPI

  2. Abra o arquivo JSON baixado e examine a definição.Open the downloaded JSON file and review the definition.

Limpar recursosClean up resources

Nas etapas anteriores, você criou os recursos do Azure em um grupo de recursos.In the preceding steps, you created Azure resources in a resource group. Se você não espera precisar desses recursos no futuro, poderá excluí-los ao excluir o grupo de recursos.If you don't expect to need these resources in the future, you can delete them by deleting the resource group.

No menu à esquerda no portal do Azure, selecione Grupos de recursos e, em seguida, selecione myResourceGroup.From the left menu in the Azure portal, select Resource groups and then select myResourceGroup.

Na página do grupo de recursos, certifique-se de que os recursos listados são aqueles que deseja excluir.On the resource group page, make sure that the listed resources are the ones you want to delete.

Selecione Excluir, digite myResourceGroup na caixa de texto e selecione Excluir.Select Delete, type myResourceGroup in the text box, and then select Delete.

Próximas etapasNext steps

Você usou a integração do Gerenciamento de API para gerar uma definição de OpenAPI de suas funções.You have used API Management integration to generate an OpenAPI definition of your functions. Agora você pode editar a definição no Gerenciamento de API no portal.You can now edit the definition in API Management in the portal. Também é possível saber mais sobre o Gerenciamento de API.You can also learn more about API Management.