Skapa serverlösa API:er i Visual Studio med hjälp av Azure Functions och API Management integrering

Artikel
06/01/2023

REST-API:er beskrivs ofta med en OpenAPI-definition. Den här filen innehåller information om åtgärder i ett API och hur begärande- och svarsdata för API:et ska struktureras.

I den här guiden får du lära dig att:

Skapa ett serverlöst funktionsprojekt i Visual Studio
Testa funktions-API:er lokalt med hjälp av inbyggda OpenAPI-funktioner
Publicera projektet till en funktionsapp i Azure med API Management-integrering
Hämta åtkomstnyckeln för funktionen och ange den i API Management
Ladda ned OpenAPI-definitionsfilen

Den serverlösa funktion som du skapar tillhandahåller ett API som gör att du kan avgöra om en nödreparation på en vindturbin är kostnadseffektiv. Eftersom både funktionsappen och API Management instans som du skapar använder förbrukningsplaner är kostnaden för att slutföra den här självstudien minimal.

Anteckning

OpenAPI- och API Management-integreringen som visas i den här artikeln stöds för närvarande endast för C#-klassbiblioteksfunktioner. Isolerad arbetsprocess C#-klassbiblioteksfunktioner och alla andra språkkörningar bör i stället använda Azure API Management integrering från portalen.

Förutsättningar

Visual Studio 2022. Se till att du väljer arbetsbelastningen Azure-utveckling under installationen.
Skapa ett kostnadsfritt konto innan du börjar med en aktiv Azure-prenumeration.

Skapa ett Functions-projekt

Den Azure Functions projektmallen i Visual Studio skapar ett projekt som du kan publicera till en funktionsapp i Azure. Du skapar också en HTTP-utlöst funktion som stöder generering av OpenAPI-definitionsfiler (tidigare Swagger-fil).

På Visual Studio-menyn väljer du Arkiv>nytt>projekt.
I Skapa ett nytt projekt anger du funktioner i sökrutan, väljer mallen Azure Functions och väljer sedan Nästa.
I Konfigurera det nya projektet anger du ett projektnamn för projektet som TurbineRepairoch väljer sedan Skapa.

Använd värdena i följande tabell för att skapa en ny Azure Functions programinställningar:

Inställning	Värde	Beskrivning
Functions Worker	.NET 6	Det här värdet skapar ett funktionsprojekt som körs i processen på version 4.x av Azure Functions-körningen, vilket krävs för generering av OpenAPI-filer.
Funktionsmall	HTTP-utlösare med OpenAPI	Det här värdet skapar en funktion som utlöses av en HTTP-begäran, med möjlighet att generera en OpenAPI-definitionsfil.
Använda Azurite för körningslagringskonto (AzureWebJobsStorage)	Markerat	Du kan använda emulatorn för lokal utveckling av HTTP-utlösarfunktioner. Eftersom en funktionsapp i Azure kräver ett lagringskonto tilldelas eller skapas en när du publicerar projektet till Azure.
Auktoriseringsnivå	Funktion	När du kör i Azure måste klienterna ange en nyckel vid åtkomst till slutpunkten. Mer information om nycklar och auktorisering finns i funktionsåtkomstnycklar.

Azure Functions projektinställningar

Välj Skapa för att skapa funktionsprojekt- och HTTP-utlösarfunktionen, med stöd för OpenAPI.

Visual Studio skapar ett projekt och en klass med namnet Function1 som innehåller exempelkod för http-utlösarens funktionstyp. Sedan ersätter du den här funktionsmallkoden med din egen anpassade kod.

Uppdatera funktionskoden

Funktionen använder en HTTP-utlösare som tar två parametrar:

Parameternamn	Beskrivning
Timmar	Den beräknade tiden för att göra en turbinreparation, upp till närmaste hela timme.
capacity	Kapaciteten av turbinen, i kilowatts.

Funktionen beräknar sedan hur mycket en reparation kostar och hur mycket intäkter turbinen kan göra under en 24-timmarsperiod. Parametrar anges antingen i frågesträngen eller i nyttolasten för en POST-begäran.

I projektfilen Function1.cs ersätter du innehållet i den genererade klassbibliotekskoden med följande kod:

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

Den här funktionskoden returnerar ett meddelande om Yes eller No för att ange om en nödreparation är kostnadseffektiv. Den returnerar också den intäktsmöjlighet som turbinen representerar och kostnaden för att åtgärda turbinen.

Köra och verifiera API:et lokalt

När du kör funktionen gör OpenAPI-slutpunkterna det enkelt att testa funktionen lokalt med hjälp av en genererad sida. Du behöver inte ange funktionsåtkomstnycklar när du kör lokalt.

Starta projektet genom att trycka på F5. När Functions-körningen startar lokalt visas en uppsättning OpenAPI- och Swagger-slutpunkter i utdata, tillsammans med funktionsslutpunkten.
Öppna slutpunkten RenderSwaggerUI i webbläsaren, som bör se ut som http://localhost:7071/api/swagger/ui. En sida återges baserat på dina OpenAPI-definitioner.
Välj POST>Prova, ange värden för hours och capacity antingen som frågeparametrar eller i JSON-begärandetexten och välj Kör.
När du anger heltalsvärden som 6 för hours och 2 500 för capacityfår du ett JSON-svar som ser ut som i följande exempel:

Nu har du en funktion som avgör om en nödreparation är kostnadseffektiv. Därefter publicerar du dina projekt- och API-definitioner till Azure.

Publicera projektet på Azure

Innan du kan publicera projektet måste du ha en funktionsapp i din Azure-prenumeration. Visual Studio-publicering skapar en funktionsapp första gången du publicerar projektet. Den kan också skapa en API Management-instans som integreras med din funktionsapp för att exponera TurbineRepair-API:et.

I Solution Explorer högerklickar du på projektet och väljer Publicera och i Mål väljer du Azure och sedan Nästa.
För Det specifika målet väljer du Azure Function App (Windows) för att skapa en funktionsapp som körs i Windows och väljer sedan Nästa.
I Funktionsinstans väljer du + Skapa en ny Azure-funktion....

Skapa en ny instans med de värden som anges i följande tabell:

Inställning	Värde	Beskrivning
Namn	Globalt unikt namn	Namn som unikt identifierar din nya funktionsapp. Acceptera det här namnet eller ange ett nytt namn. Giltiga tecken är: `a-z`, `0-9`och `-`.
Prenumeration	Din prenumeration	Den Azure-prenumeration som ska användas. Acceptera den här prenumerationen eller välj en ny i listrutan.
Resursgrupp	Namnet på resursgruppen	Den resursgrupp där du vill skapa din funktionsapp. Välj en befintlig resursgrupp i listrutan eller välj Ny för att skapa en ny resursgrupp.
Plantyp	Förbrukning	När du publicerar projektet till en funktionsapp som körs i en förbrukningsplan betalar du bara för körningar av funktionsappen. Andra värdplaner medför högre kostnader.
Plats	Platsen för tjänsten	Välj en plats i en region nära dig eller andra tjänster som dina funktioner har åtkomst till.
Azure Storage	Allmänt lagringskonto	Ett Azure Storage-konto krävs av Functions-körningen. Välj Ny för att konfigurera ett allmänt lagringskonto. Du kan också välja ett befintligt konto som uppfyller kraven för lagringskontot.

Skapa en ny funktionsapp i Azure med Storage

Välj Skapa för att skapa en funktionsapp och dess relaterade resurser i Azure. Status för resursskapande visas längst ned till vänster i fönstret.
När du är tillbaka i Functions-instansen kontrollerar du att Kör från paketfilen är markerad. Funktionsappen distribueras med zip-distribution med läget Kör från paket aktiverat. Den här distributionsmetoden rekommenderas för ditt funktionsprojekt eftersom den ger bättre prestanda.
Välj Nästa. På sidan API Management väljer du även + Skapa ett API Management-API.

Skapa ett API i API Management med hjälp av värden i följande tabell:

Inställning	Värde	Beskrivning
API-namn	TurbineRepair	Namn på API:et.
Prenumerationsnamn	Din prenumeration	Den Azure-prenumeration som ska användas. Acceptera den här prenumerationen eller välj en ny i listrutan.
Resursgrupp	Namnet på resursgruppen	Välj samma resursgrupp som funktionsappen i listrutan.
API Management-tjänst	Ny instans	Välj Ny för att skapa en ny API Management instans på den serverlösa nivån.

Skapa API Management-instans med API

Välj Skapa för att skapa API Management-instansen med TurbineRepair-API:et från funktionsintegrering.
Välj Slutför, kontrollera att sidan Publicera står Klar att publicera och välj sedan Publicera för att distribuera paketet som innehåller dina projektfiler till din nya funktionsapp i Azure.

När distributionen är klar visas rot-URL:en för funktionsappen i Azure på fliken Publicera .

Hämta funktionens åtkomstnyckel

På fliken Publicera väljer du ellipserna (...) bredvid Värd och väljer Öppna i Azure Portal. Funktionsappen som du skapade öppnas i Azure Portal i standardwebbläsaren.
Under Funktioner väljer du Functions>TurbineRepair och sedan Funktionsnycklar.
Under Funktionsnycklar väljer du standard och kopierar värdet. Nu kan du ange den här nyckeln i API Management så att den kan komma åt funktionsslutpunkten.

Konfigurera API Management

På fliken Publicera väljer du ellipserna (...) bredvid Värd och väljer Öppna API i Azure Portal. Den API Management instans som du skapade öppnas i Azure Portal i standardwebbläsaren. Den här API Management-instansen är redan länkad till din funktionsapp.
Under API:er väljer du OpenAPI-dokument på Azure Functions>POST Kör. Under Inkommande bearbetning väljer du sedan Lägg till princip.
Under Inkommande bearbetning går du till Ange frågeparametrar, skriver code för Namn, väljer +Värde, klistrar in den kopierade funktionsnyckeln och väljer Spara. API Management innehåller funktionsnyckeln när den skickar anrop till funktionsslutpunkten.

Nu när funktionsnyckeln har angetts kan du anropa API:et för att verifiera att det fungerar när det finns i Azure.

Verifiera API:et i Azure

I API:et väljer du fliken Test och sedan POST-körning, anger följande kod i begärandetexten>Raw och väljer Skicka:
```
{
    "hours": "6",
    "capacity": "2500"
}
```
Som tidigare kan du också ange samma värden som frågeparametrar.
Välj Skicka och visa sedan HTTP-svaret för att kontrollera att samma resultat returneras från API:et.

Ladda ned OpenAPI-definitionen

Om ditt API fungerar som förväntat kan du ladda ned OpenAPI-definitionen.

1. Under API:er väljer du OpenAPI-dokument på Azure Functions, väljer ellipserna (...) och sedan Exportera.
Välj metod för API-export, inklusive OpenAPI-filer i olika format. Du kan också exportera API:er från Azure API Management till Power Platform.

Rensa resurser

I de föregående stegen skapade du Azure-resurser i en resursgrupp. Om du inte tror att du behöver dessa resurser i framtiden, kan du ta bort dem genom att ta bort resursgruppen.

På Azure Portal-menyn eller startsidan väljer du Resursgrupper. På sidan Resursgrupper väljer du sedan den grupp som du skapade.

På sidan myResourceGroup kontrollerar du att resurserna i listan är de som du vill ta bort.

Välj Ta bort resursgrupp, skriv namnet på din grupp i textrutan för att bekräfta och välj sedan Ta bort.

Nästa steg

Du har använt Visual Studio 2022 för att skapa en funktion som är självdokumenterad på grund av OpenAPI-tillägget och integrerat med API Management. Nu kan du förfina definitionen i API Management i portalen. Du kan också lära dig mer om API Management.

Redigera OpenAPI-definitionen i API Management