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

Artikel
07/19/2024

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
De toegangssleutel voor de functie ophalen en instellen 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 het API Management-exemplaar dat u maakt gebruiksabonnementen maakt, uw kosten voor het voltooien van deze zelfstudie minimaal zijn.

Notitie

De OpenAPI- en API Management-integratie die in dit artikel wordt weergegeven, wordt momenteel alleen ondersteund voor C#-klassenbibliotheekfuncties in proces . Geïsoleerde C#-klassebibliotheekfuncties voor werkprocessen 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 Azure-ontwikkelworkload selecteert tijdens de installatie.
Maak een gratis account voordat u begint met een actief Azure-abonnement.

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 ondersteuning biedt voor het genereren van een OpenAPI-definitiebestand (voorheen Swagger-bestand).

Selecteer in Visual Studio-menu Bestand>Nieuw>Project.
Voer in Een nieuw project maken functies 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 TurbineRepairen selecteer vervolgens Maken.

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

Instelling	Weergegeven als	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. Dit is vereist voor het genereren van OpenAPI-bestanden.
Functiesjabloon	HTTP-trigger met OpenAPI	Met deze waarde wordt een functie gemaakt die wordt geactiveerd door een HTTP-aanvraag, met de mogelijkheid om een OpenAPI-definitiebestand te genereren.
Azurite gebruiken voor runtime-opslagaccount (AzureWebJobsStorage)	Uitverkoren	U kunt de emulator gebruiken voor lokale ontwikkeling van HTTP-triggerfuncties. Omdat een functie-app in Azure een opslagaccount vereist, wordt er een toegewezen of gemaakt wanneer u uw project publiceert naar Azure.
Verificatieniveau	Functie	Bij uitvoering in Azure moeten clients een sleutel opgeven bij het openen van het eindpunt. Zie Autorisatieniveau voor meer informatie.

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 gebruikt:

Parameternaam	Beschrijving
hours	De geschatte tijd om een turbinereparatie te maken, tot het dichtstbijzijnde hele uur.
capaciteit	De capaciteit van de turbine in kilowatt.

De functie berekent vervolgens hoeveel reparatiekosten er zijn en hoeveel omzet de turbine in een periode van 24 uur kan opleveren. Parameters worden opgegeven in de querytekenreeks of in de nettolading van een POST-aanvraag.

Vervang in het Function1.cs projectbestand de inhoud van de gegenereerde klassebibliotheekcode 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 verifiëren

Wanneer u de functie uitvoert, maken de OpenAPI-eindpunten het eenvoudig om de functie lokaal uit te proberen 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, worden een set OpenAPI- en Swagger-eindpunten weergegeven in de uitvoer, samen met het functie-eindpunt.
Open in uw browser het RenderSwaggerUI-eindpunt, 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>Try it out, enter values for hours and capacity as query parameters or in the JSON request body, and select Execute.
Wanneer u gehele getallen invoert, zoals 6 voor hours en 2500, capacitykrijgt 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-publicatie 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 in Doel, selecteer Vervolgens Azure.
Kies voor het specifieke doel azure-functie-app (Windows) om een functie-app te maken die wordt uitgevoerd in Windows en selecteer vervolgens Volgende.
Kies in functie-exemplaar + Een nieuwe Azure-functie maken....

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

Instelling	Weergegeven als	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.
Location	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.
Controleer of Uitvoeren vanuit pakketbestand is ingeschakeld in het Functions-exemplaar. 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 de pagina API Management ook + Een API Management-API maken.

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

Instelling	Weergegeven als	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 uit de functie-integratie.
selecteer Voltooien, controleer of de pagina Publiceren gereed is om te publiceren 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 de weglatingstekens (...) naast Hosting en selecteer Openen in De Azure-portal. De functie-app die u hebt gemaakt, wordt geopend in Azure Portal in uw standaardbrowser.
Selecteer onder Functions TurbineRepair> de optie Functietoetsen.
Selecteer onder Functietoetsen de standaardwaarde 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 de weglatingstekens (...) naast Hosting en selecteer Open API in Azure Portal. Het API Management-exemplaar dat u hebt gemaakt, wordt geopend in Azure Portal in uw standaardbrowser. Dit API Management-exemplaar is al gekoppeld aan uw functie-app.
Selecteer onder API's OpenAPI-document in Azure Functions>POST Run en selecteer vervolgens onder Binnenkomende verwerking beleid toevoegen.
Onder de binnenkomende verwerking, in Queryparameters instellen, typt code u voor Naam, selecteert u +Waarde, plakt u de gekopieerde functiesleutel en selecteert u 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 in Azure verifiëren

Selecteer in de API het tabblad Testen en voer vervolgens POST Run in, 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 vanuit de API.

De OpenAPI-definitie downloaden

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

1. Selecteer onder API's OpenAPI-document in Azure Functions, selecteer het beletselteken (...) en selecteer Exporteren.
Kies de middelen voor API-export, inclusief OpenAPI-bestanden in verschillende indelingen. U kunt API's ook exporteren van Azure API Management naar het 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 uw 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 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

Delen via