Serverloze API's maken in Visual Studio met behulp van Azure Functions en API Management-integratie

Artikel
06/01/2023

REST-API's worden vaak beschreven met behulp van de definitie van een OpenAPI. Dit bestand bevat informatie over bewerkingen in een API en hoe de aanvraag- en antwoordgegevens voor de API moeten worden gestructureerd.

In deze zelfstudie leert u het volgende:

Een serverloos functieproject maken in Visual Studio
Functie-API's lokaal testen met behulp van ingebouwde OpenAPI-functionaliteit
Project publiceren naar een functie-app in Azure met API Management-integratie
Haal de toegangssleutel voor de functie op en stel deze in API Management
Het OpenAPI-definitiebestand downloaden

De serverloze functie die u maakt, biedt een API waarmee u kunt bepalen of een noodherstel op een windturbine rendabel is. Omdat zowel de functie-app als API Management-exemplaar dat u maakt gebruik maken van verbruiksplannen, zijn de kosten voor het voltooien van deze zelfstudie minimaal.

Notitie

De OpenAPI- en API Management-integratie die in dit artikel worden beschreven, wordt momenteel alleen ondersteund voor C#-klassenbibliotheekfuncties in proces. Geïsoleerd werkproces C#-klassebibliotheekfuncties en alle andere taalruntimes moeten in plaats daarvan Gebruikmaken van Azure API Management-integratie vanuit de portal.

Vereisten

Visual Studio 2022. Zorg ervoor dat u de workload Azure-ontwikkeling selecteert tijdens de installatie.
Als u een actief Azure-abonnement hebt, moet u een gratis account maken voordat u begint.

Een Functions-project maken

De Azure Functions-projectsjabloon in Visual Studio maakt een project dat u kunt publiceren in een functie-app in Azure. U maakt ook een door HTTP geactiveerde functie die het genereren van een OpenAPI-definitiebestand (voorheen Swagger-bestand) ondersteunt.

Selecteer in Visual Studio-menu Bestand>Nieuw>Project.
Voer in Een nieuw project makenfuncties in het zoekvenster in, kies de sjabloon Azure Functions en selecteer vervolgens Volgende.
Voer in Het nieuwe project configureren een projectnaam in voor uw project, zoals TurbineRepair, en selecteer vervolgens Maken.

Gebruik de waarden in de volgende tabel voor de instellingen van Een nieuw Azure Functions-toepassing:

Instelling	Waarde	Beschrijving
Functions-werkrol	.NET 6	Met deze waarde maakt u een functieproject dat in verwerking wordt uitgevoerd op versie 4.x van de Azure Functions runtime, die vereist is voor het genereren van OpenAPI-bestanden.
Functiesjabloon	HTTP-trigger met OpenAPI	Met deze waarde maakt u een functie die wordt geactiveerd door een HTTP-aanvraag, met de mogelijkheid om een OpenAPI-definitiebestand te genereren.
Azurite gebruiken voor runtimeopslagaccount (AzureWebJobsStorage)	Geselecteerd	U kunt de emulator gebruiken voor de lokale ontwikkeling van HTTP-triggerfuncties. Omdat voor een functie-app in Azure een opslagaccount is vereist, wordt er een toegewezen of gemaakt wanneer u uw project naar Azure publiceert.
Verificatieniveau	Functie	Wanneer clients worden uitgevoerd in Azure, moeten ze een sleutel opgeven bij het openen van het eindpunt. Zie functietoegangssleutels voor meer informatie over sleutels en autorisatie.

Azure Functions-projectinstellingen

Selecteer Maken om het functieproject en de HTTP-triggerfunctie te maken, met ondersteuning voor OpenAPI.

Visual Studio maakt een project en klasse met de naam Function1 die standaardcode bevat voor het type HTTP-triggerfunctie. Vervolgens vervangt u deze functiesjablooncode door uw eigen aangepaste code.

De functiecode bijwerken

De functie maakt gebruik van een HTTP-trigger die twee parameters nodig heeft:

Parameternaam	Beschrijving
Uur	De geschatte tijd om een turbinereparatie uit te voeren, tot het dichtstbijzijnde hele uur.
capacity	De capaciteit van de turbine in kilowatt.

De functie berekent vervolgens hoeveel reparatiekosten en hoeveel omzet de turbine in een periode van 24 uur zou kunnen maken. Parameters worden opgegeven in de querytekenreeks of in de nettolading van een POST-aanvraag.

Vervang in het projectbestand Function1.cs de inhoud van de gegenereerde code van de klassebibliotheek door de volgende code:

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

Deze functiecode retourneert het bericht Yes of No om aan te geven of een noodherstelproces al dan niet rendabel is. Daarnaast retourneert de code de kans op omzet van de turbine en de reparatiekosten.

De API lokaal uitvoeren en controleren

Wanneer u de functie uitvoert, kunt u met de OpenAPI-eindpunten de functie eenvoudig lokaal uitproberen met behulp van een gegenereerde pagina. U hoeft geen functietoegangssleutels op te geven wanneer u lokaal wordt uitgevoerd.

Druk op F5 om het project te starten. Wanneer functions-runtime lokaal wordt gestart, wordt een set OpenAPI- en Swagger-eindpunten weergegeven in de uitvoer, samen met het functie-eindpunt.
Open in uw browser het Eindpunt RenderSwaggerUI, dat er als http://localhost:7071/api/swagger/uivolgt uit moet zien. Er wordt een pagina weergegeven op basis van uw OpenAPI-definities.
Selecteer POST>Uitproberen, voer waarden in voor hours en capacity als queryparameters of in de hoofdtekst van de JSON-aanvraag en selecteer Uitvoeren.
Wanneer u waarden voor gehele getallen invoert, zoals 6 voor hours en 2500 voor capacity, krijgt u een JSON-antwoord dat eruitziet als in het volgende voorbeeld:

U hebt nu een functie die de kosteneffectiviteit van noodreparaties bepaalt. Vervolgens publiceert u uw project- en API-definities naar Azure.

Het project naar Azure publiceren

Voordat u uw project kunt publiceren, moet u een functie-app in uw Azure-abonnement hebben. Visual Studio publishing maakt een functie-app de eerste keer dat u uw project publiceert. Het kan ook een API Management-exemplaar maken dat kan worden geïntegreerd met uw functie-app om de TurbineRepair-API beschikbaar te maken.

Klik in Solution Explorer met de rechtermuisknop op het project en selecteer Publiceren en selecteer in Doelde optie Azure en vervolgens Volgende.
Kies voor specifiek doelAzure-functie-app (Windows) om een functie-app te maken die wordt uitgevoerd op Windows. Selecteer vervolgens Volgende.
Kies in Functie-exemplaarde optie + Een nieuwe Azure-functie maken....

Maak een nieuw exemplaar met behulp van de waarden die in de volgende tabel zijn opgegeven:

Instelling	Waarde	Beschrijving
Naam	Wereldwijd unieke naam	Naam waarmee uw nieuwe functie-app uniek wordt aangeduid. Accepteer deze naam of voer een nieuwe in. Geldige tekens zijn `a-z`, `0-9` en `-`.
Abonnement	Uw abonnement	Het te gebruiken Azure-abonnement. Accepteer dit abonnement of selecteer een nieuwe uit de vervolgkeuzelijst.
Resourcegroep	Naam van uw resourcegroep	De resourcegroep waarin uw functie-app moet worden gemaakt. Selecteer een bestaande resourcegroep uit de vervolgkeuzelijst of kies Nieuwe om een nieuwe resourcegroep te maken.
Abonnemtsype	Verbruik	Wanneer u uw project publiceert in een functie-app die wordt uitgevoerd in een verbruiksabonnement, betaalt u alleen voor uitvoeringen van uw functie-app. Andere hostingabonnement kosten meer.
Locatie	Locatie van de service	Kies een Locatie in een regio bij u in de buurt of in de buurt van andere services die door uw functies worden gebruikt.
Azure Storage	Storage-account voor algemeen gebruik	Er is een Azure Storage-account vereist voor de Functions-runtime. Selecteer Nieuw om een algemeen opslagaccount te configureren. U kunt ook een bestaand account kiezen dat voldoet aan de vereisten voor een opslagaccount.

Een nieuwe functie-app maken in Azure met Storage

Selecteer Maken om een functie-app en de bijbehorende resources te maken in Azure. De status van het maken van resources wordt linksonder in het venster weergegeven.
Als u terug bent in het Functions-exemplaar, controleert u of Uitvoeren vanuit pakketbestand is ingeschakeld. Uw functie-app wordt geïmplementeerd met Zip-implementeren met de modus Uitvoeren vanuit pakket ingeschakeld. Deze implementatiemethode wordt aanbevolen voor uw Functions-project, omdat dit resulteert in betere prestaties.
Selecteer Volgende en kies op API Management pagina ook + Een API Management API maken.

Maak een API in API Management met behulp van waarden in de volgende tabel:

Instelling	Waarde	Beschrijving
API-naam	TurbineRepair	Naam voor de API.
Abonnementsnaam	Uw abonnement	Het te gebruiken Azure-abonnement. Accepteer dit abonnement of selecteer een nieuwe uit de vervolgkeuzelijst.
Resourcegroep	Naam van uw resourcegroep	Selecteer dezelfde resourcegroep als uw functie-app in de vervolgkeuzelijst.
API Management service	Nieuw exemplaar	Selecteer Nieuw om een nieuw API Management exemplaar te maken in de serverloze laag.

API Management-exemplaar maken met API

Selecteer Maken om het API Management-exemplaar te maken met de TurbineRepair-API van de functieintegratie.
selecteer Voltooien, controleer of op de pagina Publiceren de tekst Gereed voor publicatie staat en selecteer vervolgens Publiceren om het pakket met uw projectbestanden te implementeren in uw nieuwe functie-app in Azure.

Nadat de implementatie is voltooid, wordt de hoofd-URL van de functie-app in Azure weergegeven op het tabblad Publiceren .

De functietoegangssleutel ophalen

Selecteer op het tabblad Publiceren het beletselteken (...) naast Hosting en selecteer Openen in Azure Portal. De functie-app die u hebt gemaakt, wordt geopend in de Azure Portal in uw standaardbrowser.
Selecteer onder Functiesde optie Functies>TurbineVernieuwen en selecteer vervolgens Functietoetsen.
Selecteer onder Functietoetsende optie standaard en kopieer de waarde. U kunt deze sleutel nu instellen in API Management zodat deze toegang heeft tot het functie-eindpunt.

API Management configureren

Selecteer op het tabblad Publiceren het beletselteken (...) naast Hosting en selecteer API openen in Azure Portal. Het API Management exemplaar dat u hebt gemaakt, wordt geopend in de Azure Portal in uw standaardbrowser. Deze API Management-instantie is al gekoppeld aan uw functie-app.
Selecteer onder API'sde optie OpenAPI-document op Azure Functions>POST Run en selecteer vervolgens onder Binnenkomende verwerkingde optie Beleid toevoegen.
Typ onder Inkomende verwerking in Queryparameterscode instellen bij Naam, selecteer +Waarde, plak de gekopieerde functietoets en selecteer Opslaan. API Management bevat de functiesleutel wanneer deze aanroepen doorgeeft aan het functie-eindpunt.

Nu de functiesleutel is ingesteld, kunt u de API aanroepen om te controleren of deze werkt wanneer deze wordt gehost in Azure.

De API controleren in Azure

Selecteer in de API het tabblad Testen en vervolgens POST Uitvoeren, voer de volgende code in de aanvraagbody>Raw in en selecteer Verzenden:
```
{
    "hours": "6",
    "capacity": "2500"
}
```
Net als voorheen kunt u ook dezelfde waarden opgeven als queryparameters.
Selecteer Verzenden en bekijk vervolgens het HTTP-antwoord om te controleren of dezelfde resultaten worden geretourneerd door de API.

De OpenAPI-definitie downloaden

Als uw API zoals verwacht functioneert, kunt u de OpenAPI-definitie downloaden.

1. Selecteer onder API'sde optie OpenAPI-document op Azure Functions, selecteer het beletselteken (...) en selecteer Exporteren.
Kies de methode voor API-export, inclusief OpenAPI-bestanden in verschillende indelingen. U kunt ook API's exporteren van Azure API Management naar Power Platform.

Resources opschonen

In de voorgaande stappen hebt u Azure-resources in een resourcegroep gemaakt. Als u deze resources in de toekomst waarschijnlijk niet nodig hebt, kunt u ze verwijderen door de resourcegroep te verwijderen.

Selecteer Resourcegroepen in het menu of op de beginpagina van de Azure-portal. Selecteer vervolgens op de pagina Resourcegroepen de groep die u hebt gemaakt.

Controleer op de pagina myResourceGroup of de weergegeven resources de resources zijn die u wilt verwijderen.

Selecteer Resourcegroep verwijderen, typ de naam van de groep in het tekstvak om te bevestigen en selecteer vervolgens Verwijderen.

Volgende stappen

U hebt Visual Studio 2022 gebruikt om een functie te maken die zichzelf documenteert vanwege de OpenAPI-extensie en die is geïntegreerd met API Management. U kunt nu de definitie verfijnen in API Management in de portal. Ook kunt u meer informatie over API Management raadplegen.

De OpenAPI-definitie bewerken in API Management