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

Artikel
04/11/2023

REST-APIs werden häufig mithilfe einer OpenAPI-Definition beschrieben. 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:

Erstellen eines serverlosen Funktionsprojekts in Visual Studio
Lokales Testen von Funktions-APIs mithilfe der integrierten OpenAPI-Funktionalität
Veröffentlichen eines Projekts in einer Funktions-App in Azure mit API Management-Integration
Abrufen des Zugriffsschlüssels für die Funktion und dessen Festlegung in API Management
Herunterladen der OpenAPI-Definitionsdatei

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 sowohl die Funktions-App als auch die API Management-Instanz, die Sie erstellen, einen Verbrauchsplan verwendet, sind die Kosten für die Durchführung dieses Tutorials minimal.

Hinweis

Die in diesem Artikel vorgestellte OpenAPI- und API Management-Integration wird derzeit nur für In-Process-Funktionen der C#-Klassenbibliothek unterstützt. Isolierter Workerprozess: Funktionen von C#-Klassenbibliothek und alle anderen Sprachruntimes sollten stattdessen die Azure API Management-Integration aus dem Portal verwenden.

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 eines Functions-Projekts

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, die die Generierung von OpenAPI-Definitionsdateien (ehemals Swagger-Datei) unterstützt.

Wählen Sie im Visual Studio-Menü Datei>Neu>Projekt aus.
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.
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.

Verwenden Sie für die Einstellungen zum Erstellen einer neuen Azure Functions-Anwendung die Werte in der folgenden Tabelle:

Einstellung	Wert	BESCHREIBUNG
Functions-Worker	.NET 6	Mit diesem Wert wird ein Funktionsprojekt erstellt, das prozessintern in Version 4.x der Azure Functions-Runtime ausgeführt wird, da dies für die OpenAPI-Dateigenerierung erforderlich ist.
Funktionsvorlage	HTTP-Trigger mit OpenAPI	Dieser Wert erstellt eine Funktion, die durch eine HTTP-Anforderung ausgelöst wird, mit der Möglichkeit, eine OpenAPI-Definitionsdatei zu generieren.
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 zu Schlüsseln und Autorisierung finden Sie unter Funktionszugriffsschlüssel.

Azure Functions-Projekteinstellungen

Wählen Sie Erstellen aus, um das Funktionsprojekt und die HTTP-Triggerfunktion mit Unterstützung für OpenAPI zu erstellen.

Visual Studio erstellt ein Projekt und eine Klasse namens Function1 mit Codebausteinen für den Funktionstyp „HTTP-Trigger“. Als Nächstes ersetzen Sie diesen Funktionsvorlagencode durch Ihren eigenen benutzerdefinierten Code.

Aktualisieren des Funktionscodes

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

Parametername	BESCHREIBUNG
hours	Die geschätzte Zeit für eine Turbinenreparatur bis zur nächsten ganzen Stunde.
Kapazität	Die Kapazität der Turbine in Kilowatt.

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 Projektdatei „Function1.cs“ den Inhalt des generierten Klassenbibliothekscodes durch den folgenden 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; } 
    }
}

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.

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.
Ö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.
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.
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.

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.
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.
Wählen Sie unter Funktionsinstanz die Option + Neue Azure Functions-Instanz erstellen aus.

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.

Erstellen einer neuen Funktions-App in Azure mit Storage

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.
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.
Wählen Sie Weiter und auf der API Management-Seite auch + API Management-API erstellen aus.

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 auf der serverlosen Ebene zu erstellen.

Erstellen einer API Management-Instanz mit API

Wählen Sie Erstellen aus, um die API Management-Instanz mit der TurbineRepair-API aus der Funktionsintegration zu erstellen.
Wählen Sie Fertig stellen aus, ü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

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.
Wählen Sie unter Funktionen die Option Funktionen>TurbineRepair und dann Funktionsschlüssel aus.
Wählen Sie unter Funktionsschlüssel die Option Standard aus, und kopieren Sie den Wert. Sie können diesen Schlüssel jetzt im API Management festlegen, damit er auf den Funktionsendpunkt zugreifen kann.

Konfigurieren von API Management

Wählen Sie auf der Registerkarte Veröffentlichen die Auslassungspunkte ( ... ) neben Hosting und dann API im Azure-Portal öffnen aus. Die API Management-Instanz, die Sie erstellt haben, wird im Azure-Portal in Ihrem Standardbrowser geöffnet. Diese API Management-Instanz ist bereits mit Ihrer Funktions-App verknüpft.
Wählen Sie unter APIs die Option OpenAPI-Dokument für Azure Functions>NACH Ausführung aus, und wählen Sie dann unter Eingehende Verarbeitung die Option Richtlinie hinzufügen aus.
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 die API aufrufen, um zu überprüfen, ob er funktioniert, wenn er in Azure gehostet wird.

Überprüfen der API in Azure

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.
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 wie erwartet funktioniert, können Sie die OpenAPI-Definition herunterladen.

1. Wählen Sie unter APIs die Option OpenAPI-Dokument für Azure Functions, die Auslassungspunkte (...) und dann Exportieren aus.
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 Extension selbstdokumentierend und in 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.

Bearbeiten von APIs