Erstellen serverloser APIs in Visual Studio mit Azure Functions und Integration von API Management

REST-APIs werden häufig mithilfe einer OpenAPI-Definition beschrieben (früher als Swagger-Datei bezeichnet). Diese Datei enthält Informationen zu Vorgängen in einer API sowie zur Strukturierung der Anforderungs- und Antwortdaten für die API.

In diesem Tutorial lernen Sie Folgendes:

Die serverlose Funktion, die Sie erstellen, stellt eine API bereit, mit der Sie ermitteln können, ob eine Notfallreparatur an einer Windturbine kostengünstig ist. Da Sie sowohl die Funktions-App als auch die API Management-Instanz in einem Verbrauchstarif erstellen, sind die Kosten für die Durchführung dieses Tutorials minimal.

Voraussetzungen

• Visual Studio 2022 Wählen Sie bei der Installation unbedingt die Workload Azure-Entwicklung aus.

• Wenn Sie nicht über ein aktives Azure-Abonnement verfügen, können Sie ein kostenloses Konto erstellen, bevor Sie beginnen.

Erstellen des Codeprojekts

Mit der Azure Functions-Projektvorlage in Visual Studio wird ein Projekt erstellt, das Sie in einer Funktions-App in Azure veröffentlichen können. Außerdem erstellen Sie eine per HTTP ausgelöste Funktion aus einer Vorlage, die die Generierung von OpenAPI-Definitionsdateien (ehemals Swagger-Datei) unterstützt.

1. Wählen Sie im Visual Studio-Menü Datei>Neu>Projekt aus.

2. Geben Sie unter Neues Projekt erstellen den Suchbegriff functions in das Suchfeld ein, und wählen Sie die Vorlage Azure Functions und anschließend Weiter aus.

3. Geben Sie unter Neues Projekt konfigurieren im Feld Projektname einen Namen für Ihr Projekt ein, und wählen Sie anschließend TurbineRepair und dann Erstellen aus.

4. Wählen Sie für die Einstellungen zum Erstellen einer neuen Azure Functions-Anwendung eine der folgenden Optionen für Functions-Worker aus, wobei die von Ihnen ausgewählte Option von Ihrem ausgewählten Prozessmodell abhängt:

   • Isoliertes Workermodell
   • In-Process

   .NET 8.0 Isolated (Long Term Support): Ihre C#-Funktionen werden im isolierten Workermodell ausgeführt, was empfohlen wird. Weitere Informationen finden Sie im Leitfaden zum isolierten Workermodell.

5. Verwenden Sie für die restlichen Optionen die Werte in der folgenden Tabelle:

   Einstellung	Wert	Beschreibung
   Funktionsvorlage	Leer	Dadurch wird ein Projekt ohne Trigger erstellt, wodurch Sie mehr Kontrolle über den Namen der ausgelösten HTTP-Funktion haben, wenn Sie sie später hinzufügen.
   Verwenden von Azurite für das Runtimespeicherkonto (AzureWebJobsStorage)	Ausgewählt	Sie können den Emulator für die lokale Entwicklung von HTTP-Triggerfunktionen verwenden. Da für eine Funktions-App in Azure ein Speicherkonto erforderlich ist, wird ein Speicherkonto zugewiesen oder erstellt, wenn Sie Ihr Projekt in Azure veröffentlichen.
   Autorisierungsstufe	Funktion	Bei der Ausführung in Azure müssen Clients beim Zugriff auf den Endpunkt einen Schlüssel angeben. Weitere Informationen finden Sie unter Autorisierungsebene.

6. Wählen Sie Erstellen aus, um das Funktionsprojekt zu erstellen.

Als Nächstes aktualisieren Sie das Projekt, indem Sie die OpenAPI-Erweiterung für Azure Functions installieren, die die Auffindbarkeit von API-Endpunkten in Ihrer App ermöglicht.

Installieren der OpenAPI-Erweiterung

So installieren Sie die OpenAPI-Erweiterung:

1. Wählen Sie im Menü Tools die Option NuGet-Paket-Manager>Paket-Manager-Konsole aus.

2. Führen Sie in der Konsole den folgenden Install-Package-Befehl aus, um die OpenAPI-Erweiterung zu installieren:

   • Isoliertes Workermodell
   • In-Process-Modell

   NuGet\Install-Package Microsoft.Azure.Functions.Worker.Extensions.OpenApi -Version 1.5.1
   

   Möglicherweise müssen Sie die jeweilige Version basierend auf Ihrer Version von .NET aktualisieren.

Jetzt können Sie Ihre HTTP-Endpunktfunktion hinzufügen.

Hinzufügen einer HTTP-Endpunktfunktion

In einer C#-Klassenbibliothek werden die von der Funktion verwendeten Bindungen durch Anwendung von Attributen im Code definiert. So erstellen Sie eine Funktion mit einem HTTP-Trigger:

1. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf den Projektknoten, und wählen Sie Hinzufügen>Neue Azure-Funktion aus.

2. Geben Sie Turbine.cs für die Klasse ein, und wählen Sie dann Hinzufügen aus.

3. Wählen Sie die Vorlage HTTP-Trigger aus, legen Sie Autorisierungsstufe auf Funktion fest, und wählen Sie dann Hinzufügen aus. Ihrem Projekt wird eine Turbine.cs-Codedatei hinzugefügt, die einen neuen Funktionsendpunkt mit einem HTTP-Trigger definiert.

Jetzt können Sie den HTTP-Triggervorlagencode durch Code ersetzen, der den Turbine-Funktionsendpunkt implementiert, zusammen mit Attributen, die OpenAPI zum Definieren des Endpunkts verwenden.

Aktualisieren des Funktionscodes

Die Funktion verwendet einen HTTP-Trigger, der zwei Parameter annimmt:

Die Funktion berechnet dann die Kosten einer Reparatur und den Umsatzerlös, der in einem Zeitraum von 24 Stunden von der Turbine generiert werden könnte. Parameter werden entweder in der Abfragezeichenfolge oder in der Nutzlast einer POST-Anforderung angegeben.

Ersetzen Sie in der Turbine.cs-Projektdatei den Inhalt der Klasse, die aus der HTTP-Triggervorlage generiert wurde, durch den folgenden Code, der von Ihrem Prozessmodell abhängt:

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

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

Von diesem Funktionscode wird durch Rückgabe von Yes oder No angegeben, ob eine Notfallreparatur kosteneffizient ist. Darüber hinaus werden der mögliche Umsatzerlös der Turbine und die Kosten für die Reparatur zurückgegeben.

Lokales Ausführen und Überprüfen der API

Wenn Sie die Funktion ausführen, erleichtern die OpenAPI-Endpunkte das lokale Testen der Funktion mithilfe einer generierten Seite. Sie müssen bei der lokalen Ausführung keine Funktionszugriffsschlüssel bereitstellen.

1. Drücken Sie F5, um das Projekt zu starten. Wenn die Functions-Runtime lokal gestartet wird, werden in der Ausgabe eine Reihe von OpenAPI- und Swagger-Endpunkten zusammen mit dem Funktionsendpunkt angezeigt.

2. Öffnen Sie in Ihrem Browser den RenderSwaggerUI-Endpunkt, der so http://localhost:7071/api/swagger/ui aussehen sollte. Eine Seite wird basierend auf Ihren OpenAPI-Definitionen gerendert.

3. Wählen Sie POST>Ausprobieren aus, geben Sie Werte für hours und capacity entweder als Abfrageparameter oder im JSON-Anforderungstext ein, und wählen Sie Ausführen aus.

   

4. Wenn Sie ganzzahlige Werte wie 6 für hours und 2500 für capacity eingeben, erhalten Sie eine JSON-Antwort, die wie im folgenden Beispiel aussieht:

   

Sie haben jetzt eine Funktion, die die Kosteneffizienz von Notfallreparaturen ermittelt. Veröffentlichen Sie als Nächstes Ihr Projekt und Ihre API-Definitionen in Azure.

Veröffentlichen des Projekts in Azure

Sie müssen in Ihrem Azure-Abonnement über eine Funktions-App verfügen, um Ihr Projekt veröffentlichen zu können. Bei der Veröffentlichung in Visual Studio wird eine Funktions-App erstellt, wenn Sie das Projekt zum ersten Mal veröffentlichen. Es kann auch eine API Management-Instanz erstellt werden, die in Ihre Funktions-App integriert wird, um die TurbineRepair-API verfügbar zu machen.

1. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf das Projekt, und wählen Sie Veröffentlichen aus. Wählen Sie unter Ziel die Option Azure und anschließend Weiter aus.

2. Wählen Sie für Bestimmtes Ziel die Option Azure-Funktions-App (Windows) aus, um eine Funktions-App zu erstellen, die unter Windows ausgeführt wird, und wählen Sie dann Weiter aus.

3. Wählen Sie unter Funktionsinstanz die Option + Neue Azure Functions-Instanz erstellen aus.

   

4. Erstellen Sie eine neue Instanz mit den Werten aus der folgenden Tabelle:

   Einstellung	Wert	Beschreibung
   Name	Global eindeutiger Name	Name, der Ihre neue Funktions-App eindeutig identifiziert. Übernehmen Sie diesen Namen, oder geben Sie einen neuen Namen ein. Gültige Zeichen: a-z, 0-9 und -.
   Abonnement	Ihr Abonnement	Das zu verwendende Azure-Abonnement. Übernehmen Sie dieses Abonnement, oder wählen Sie in der Dropdownliste ein neues Abonnement aus.
   Ressourcengruppe	Name Ihrer Ressourcengruppe	Die Ressourcengruppe, in der Ihre Funktions-App erstellt werden soll. Wählen Sie in der Dropdownliste eine vorhandene Ressourcengruppe aus, oder wählen Sie Neu aus, um eine neue Ressourcengruppe zu erstellen.
   Plantyp	Nutzung	Wenn Sie Ihr Projekt in einer Funktions-App veröffentlichen, die in einem Verbrauchsplan ausgeführt wird, bezahlen Sie nur für die Ausführungen Ihrer Funktions-App. Für andere Hostingpläne fallen höhere Kosten an.
   Location	Standort des Diensts	Wählen Sie einen Standort in einer Region in Ihrer Nähe oder in der Nähe anderer Dienste aus, auf die Ihre Funktionen zugreifen.
   Azure Storage	Universelles Speicherkonto	Für die Functions-Runtime wird ein Azure Storage-Konto benötigt. Wählen Sie Neu aus, um ein universelles Speicherkonto zu konfigurieren. Sie können auch ein vorhandenes Konto auswählen, das die Anforderungen an das Speicherkonto erfüllt.

   

5. Wählen Sie Erstellen aus, um eine Funktions-App und die zugehörigen Ressourcen in Azure zu erstellen. Der Status der Ressourcenerstellung wird links unten im Fenster angezeigt.

6. Vergewissern Sie sich unter Funktionsinstanz, dass die Option Aus Paketdatei ausführen aktiviert ist. Ihre Funktions-App wird unter Verwendung der ZIP-Bereitstellung mit aktiviertem Modus Run-From-Package bereitgestellt. Diese Bereitstellungsmethode wird für Ihr Funktionsprojekt empfohlen, da damit eine bessere Leistung erzielt wird.

7. Wählen Sie Weiter und auf der API Management-Seite auch + API Management-API erstellen aus.

8. Erstellen Sie mithilfe der Werte in der folgenden Tabelle eine API in API Management:

   Einstellung	Wert	Beschreibung
   API-Name	TurbineRepair	Name für die API.
   Abonnementname	Ihr Abonnement	Das zu verwendende Azure-Abonnement. Übernehmen Sie dieses Abonnement, oder wählen Sie in der Dropdownliste ein neues Abonnement aus.
   Ressourcengruppe	Name Ihrer Ressourcengruppe	Wählen Sie in der Dropdownliste die gleiche Ressourcengruppe aus, die von Ihrer Funktions-App verwendet wird.
   API Management-Dienst	Neue Instanz	Wählen Sie Neu aus, um eine neue API Management-Instanz am selben Standort wie der serverlose Tarif zu erstellen. Wählen Sie OK aus, um die Instanz zu erstellen.

   

9. Wählen Sie Erstellen aus, um die API Management-Instanz mit der TurbineRepair-API aus der Funktionsintegration zu erstellen.

10. Wählen Sie Fertig stellen aus, und wählen Sie nach der Erstellung des Veröffentlichungsprofils Schließen aus.

11. Überprüfen Sie, ob auf der Seite „Veröffentlichen“ Bereit zur Veröffentlichung angezeigt wird, und wählen Sie dann Veröffentlichen aus, um das Paket mit Ihren Projektdateien in der neuen Funktions-App in Azure bereitzustellen.

    Nach Abschluss der Bereitstellung wird die Stamm-URL der Funktions-App in Azure auf der Registerkarte Veröffentlichen angezeigt.

Abrufen eines Funktionszugriffsschlüssels

1. Wählen Sie auf der Registerkarte Veröffentlichen die Auslassungspunkte ( ... ) neben Hosting und dann Im Azure-Portal öffnen aus. Die von Ihnen erstellte Funktions-App wird im Azure-Portal in Ihrem Standardbrowser geöffnet.

2. Wählen Sie unter Funktionen auf der Seite Übersicht die Option >Turbine und dann Funktionsschlüssel aus.

   

3. Wählen Sie unter Funktionsschlüssel das Symbol zum Kopieren in die Zwischenablage neben dem Schlüssel default aus. Sie können den kopierten Schlüssel jetzt in API Management festlegen, damit auf den Funktionsendpunkt zugegriffen werden kann.

Konfigurieren von API Management

1. Erweitern Sie auf der Funktions-App-Seite API, und wählen Sie API Management aus.

2. Wenn die Funktions-App noch nicht mit der neuen API Management-Instanz verbunden ist, wählen Sie sie unter API Management die Option API>OpenAPI-Dokument in Azure Functions aus, stellen Sie sicher, dass Importfunktionen aktiviert ist, und wählen Sie API verknüpfen aus. Stellen Sie sicher, dass nur TurbineRepair für den Import ausgewählt ist, und wählen Sie dann Auswählen aus.

3. Wählen Sie Zu API Management wechseln oben auf der Seite aus, und erweitern Sie in der API Management-Instanz die Option APIs.

4. Wählen Sie unter APIs>Alle APIs die Option OpenAPI-Dokument in Azure Functions>NACH Ausführung aus, und wählen Sie dann unter Eingehende Verarbeitung die Option Richtlinie hinzufügen>Abfrageparameter festlegen aus.

5. Wählen Sie unter Eingehende Verarbeitung die Option Abfrageparameter festlegen aus, geben Sie code für Name ein, wählen Sie +Wert aus, fügen Sie den kopierten Funktionsschlüssel ein, und wählen Sie Speichern aus. API Management enthält den Funktionsschlüssel, wenn Aufrufe an den Funktionsendpunkt übergeben werden.

   

Da der Funktionsschlüssel nun festgelegt ist, können Sie den API-Endpunkt turbine aufrufen, um zu überprüfen, ob er funktioniert, wenn er in Azure gehostet wird.

Überprüfen der API in Azure

1. Wählen Sie in der API die Registerkarte Test und dann POST-Ausführung aus, geben Sie den folgenden Code in Anforderungstext>Roh ein, und wählen Sie Senden aus:

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

   

   Wie zuvor können Sie auch dieselben Werte als Abfrageparameter angeben.

2. Wählen Sie Senden aus, und zeigen Sie dann die HTTP-Antwort an, um zu überprüfen, ob die gleichen Ergebnisse von der API zurückgegeben werden.

Herunterladen der OpenAPI-Definition

Wenn Ihre API erwartungsgemäß funktioniert, können Sie die OpenAPI-Definition für die neuen gehosteten APIs aus API Management herunterladen.

1. 1. Wählen Sie unter APIs die Option OpenAPI-Dokument für Azure Functions, die Auslassungspunkte (...) und dann Exportieren aus.

   

2. Wählen Sie die Mittel für den API-Export einschließlich OpenAPI-Dateien in verschiedenen Formaten aus. Sie können auch APIs aus Azure API Management auf die Power Platform exportieren.

Bereinigen von Ressourcen

In den vorherigen Schritten haben Sie Azure-Ressourcen in einer Ressourcengruppe erstellt. Wenn Sie diese Ressourcen in Zukunft nicht mehr benötigen, können Sie sie löschen, indem Sie die Ressourcengruppe löschen.

Wählen Sie im Azure-Portalmenü oder auf der Startseite die Option Ressourcengruppen aus. Wählen Sie dann auf der Seite Ressourcengruppen die Gruppe aus, die Sie erstellt haben.

Stellen Sie auf der Seite myResourceGroup sicher, dass die Ressourcen aufgelistet sind, die Sie löschen möchten.

Wählen Sie Ressourcengruppe löschen aus, geben Sie den Namen Ihrer Gruppe zur Bestätigung im Textfeld ein, und wählen Sie anschließend Löschen aus.

Nächste Schritte

Sie haben mit Visual Studio 2022 eine Funktion erstellt, die aufgrund der OpenAPI-Erweiterung selbstdokumentierend und mit API Management integriert ist. Als Nächstes können Sie die Definition in API Management über das Portal anpassen. Außerdem können Sie sich ausführlicher über API Management informieren.