Serverloze API's maken in Visual Studio met behulp van Azure Functions en API Management-integratie
REST API's worden vaak beschreven met behulp van een OpenAPI-definitiebestand (voorheen bekend als Swagger). 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:
- Het codeproject maken in Visual Studio
- De OpenAPI-extensie installeren
- Een HTTP-triggereindpunt toevoegen, dat OpenAPI-definities bevat
- Functie-API's lokaal testen met behulp van ingebouwde OpenAPI-functionaliteit
- Project publiceren naar een functie-app in Azure
- API Management-integratie inschakelen
- 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 u zowel de functie-app als het API Management-exemplaar in een verbruikslaag maakt, zijn uw kosten voor het voltooien van deze zelfstudie minimaal.
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.
Het codeproject 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 op basis van een sjabloon 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.Selecteer voor de instellingen voor het maken van een nieuwe Azure Functions-toepassing een van deze opties voor Functions Worker, waarbij de optie die u kiest, afhankelijk is van het gekozen procesmodel:
.NET 8.0 Isolated (langetermijnondersteuning): uw C#-functies worden uitgevoerd in het geïsoleerde werkrolmodel. Dit wordt aanbevolen. Zie de handleiding voor geïsoleerde werkrollen voor meer informatie.
Gebruik voor de rest van de opties de waarden in de volgende tabel:
Instelling Weergegeven als Beschrijving Functiesjabloon Leeg Hiermee maakt u een project zonder trigger, waardoor u meer controle hebt over de naam van de door HTTP geactiveerde functie wanneer u het later toevoegt. 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. Selecteer Maken om het functieproject te maken.
Vervolgens werkt u het project bij door de OpenAPI-extensie voor Azure Functions te installeren, waardoor API-eindpunten in uw app kunnen worden gedetecteerd.
De OpenAPI-extensie installeren
De OpenAPI-extensie installeren:
Selecteer in het menu Hulpprogramma’s de optie NuGet Package Manager>Package Manager Console.
Voer in de console de volgende installatiepakketopdracht uit om de OpenAPI-extensie te installeren:
NuGet\Install-Package Microsoft.Azure.Functions.Worker.Extensions.OpenApi -Version 1.5.1Mogelijk moet u de specifieke versie bijwerken op basis van uw versie van .NET.
U kunt nu uw HTTP-eindpuntfunctie toevoegen.
Een HTTP-eindpuntfunctie toevoegen
In een C#-klassebibliotheek worden de bindingen die door de functie worden gebruikt, gedefinieerd door kenmerken in de code toe te passen. Een functie maken met een HTTP-trigger:
Klik in Solution Explorer met de rechtermuisknop op het projectknooppunt en selecteer Nieuwe Azure-functie toevoegen>.
Voer Turbine.cs in voor de klasse en selecteer vervolgens Toevoegen.
Kies de http-triggersjabloon , stel autorisatieniveau in op Functie en selecteer Vervolgens Toevoegen. Er wordt een Turbine.cs codebestand toegevoegd aan uw project waarmee een nieuw functie-eindpunt met een HTTP-trigger wordt gedefinieerd.
U kunt nu de HTTP-triggersjablooncode vervangen door code waarmee het eindpunt van de turbinefunctie wordt geïmplementeerd, samen met kenmerken die gebruikmaken van OpenAPI om eindpunten te definiëren.
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 Turbine.cs projectbestand de inhoud van de klasse die is gegenereerd op basis van de HTTP-triggersjabloon door de volgende code, die afhankelijk is van uw procesmodel:
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.Functions.Worker;
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;
using System.Net;
namespace TurbineRepair
{
public class Turbine
{
const double revenuePerkW = 0.12;
const double technicianCost = 250;
const double turbineCost = 100;
private readonly ILogger<Turbine> _logger;
public Turbine(ILogger<Turbine> logger)
{
_logger = logger;
}
[Function("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 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
hoursandcapacityas query parameters or in the JSON request body, and select Execute.
Wanneer u gehele getallen invoert, zoals 6 voor
hoursen 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-9en-.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. 
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 op dezelfde locatie in de serverloze laag. Selecteer OK om het exemplaar te maken. 
Selecteer Maken om het API Management-exemplaar te maken met de TurbineRepair-API uit de functie-integratie.
Selecteer Voltooien en nadat het proces voor het maken van het publicatieprofiel is voltooid, selecteert u Sluiten.
Controleer of de pagina Publiceren nu Gereed is voor publicatie en selecteer 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 Functies op de pagina Overzicht de optie >Turbine en selecteer vervolgens Functietoetsen.
Selecteer onder Functietoetsen het pictogram Kopiëren naar klembord naast de standaardsleutel . U kunt nu deze sleutel instellen die u hebt gekopieerd in API Management, zodat deze toegang heeft tot het functie-eindpunt.
API Management configureren
Vouw op de pagina van de functie-app DE API uit en selecteer API Management.
Als de functie-app nog niet is verbonden met het nieuwe API Management-exemplaar, selecteert u deze onder API Management, selecteert u API>OpenAPI-document in Azure Functions, controleert u of importfuncties zijn ingeschakeld en selecteert u Koppelings-API. Zorg ervoor dat alleen TurbineRepair is geselecteerd voor importeren en selecteer vervolgens.
Selecteer Ga naar API Management boven aan de pagina en vouw in het API Management-exemplaar API's uit.
Selecteer onder API's Alle API's> OpenAPI-document in Azure Functions>POST Run en selecteer vervolgens onder Binnenkomende verwerking de optie Queryparameters voor het instellen van beleid>toevoegen.
Onder de binnenkomende verwerking, in Queryparameters instellen, typt
codeu 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 het turbine API-eindpunt aanroepen om te controleren of het 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 werkt zoals verwacht, kunt u de OpenAPI-definitie downloaden voor de nieuwe gehoste API's van API Management.
-
- 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.