Tworzenie bezserwerowych interfejsów API w programie Visual Studio przy użyciu usługi Azure Functions i integracji usługi API Management

Artykuł
08/08/2024

Interfejsy API REST są często opisywane przy użyciu pliku definicji interfejsu OpenAPI (wcześniej znanego jako Swagger). Ten plik zawiera informacje o operacjach w interfejsie API oraz strukturę danych żądania i odpowiedzi dla interfejsu API.

Z tego samouczka dowiesz się, jak wykonywać następujące czynności:

Tworzenie projektu kodu w programie Visual Studio
Instalowanie rozszerzenia OpenAPI
Dodawanie punktu końcowego wyzwalacza HTTP, który zawiera definicje interfejsu OpenAPI
Testowanie interfejsów API funkcji lokalnie przy użyciu wbudowanych funkcji interfejsu OpenAPI
Publikowanie projektu w aplikacji funkcji na platformie Azure
Włączanie integracji z usługą API Management
Pobieranie pliku definicji interfejsu OpenAPI

Utworzona funkcja bezserwerowa udostępnia interfejs API, który pozwala określić, czy naprawa awaryjne na turbinie wiatrowej jest opłacalna. Ponieważ tworzysz zarówno aplikację funkcji, jak i wystąpienie usługi API Management w warstwie zużycia, koszt ukończenia tego samouczka jest minimalny.

Wymagania wstępne

Visual Studio 2022. Upewnij się, że podczas instalacji wybrano obciążenie programistyczne platformy Azure.
Aktywna subskrypcja platformy Azure przed rozpoczęciem utwórz bezpłatne konto .

Tworzenie projektu kodu

Szablon projektu usługi Azure Functions w programie Visual Studio tworzy projekt, który można opublikować w aplikacji funkcji na platformie Azure. Utworzysz również funkcję wyzwalaną przez protokół HTTP na podstawie szablonu obsługującego generowanie pliku definicji interfejsu OpenAPI (dawniej pliku swagger).

Z menu programu Visual Studio wybierz pozycję Plik>nowy>projekt.
W obszarze Tworzenie nowego projektu wprowadź funkcje w polu wyszukiwania, wybierz szablon usługi Azure Functions , a następnie wybierz pozycję Dalej.
W obszarze Konfigurowanie nowego projektu wprowadź nazwę projektu, taką jak TurbineRepair, a następnie wybierz pozycję Utwórz.
W obszarze Tworzenie nowych ustawień aplikacji usługi Azure Functions wybierz jedną z tych opcji dla procesu roboczego usługi Functions, gdzie wybrana opcja zależy od wybranego modelu procesu:
- Model izolowanego procesu roboczego
- Proces
Izolowana platforma .NET 8.0 (obsługa długoterminowa): Funkcje języka C# działają w modelu izolowanego procesu roboczego, co jest zalecane. Aby uzyskać więcej informacji, zobacz izolowany przewodnik po modelu procesu roboczego.

Ważne

Wsparcie zostanie zakończone dla modelu procesu 10 listopada 2026 r. Zdecydowanie zalecamy przeprowadzenie migracji aplikacji do izolowanego modelu procesu roboczego w celu uzyskania pełnej obsługi.

.NET 8.0 (obsługa długoterminowa): Funkcje języka C# działają w modelu przetwarzania, który zostanie wycofany. Aby dowiedzieć się więcej, zobacz przewodnik po modelu przetwarzania.

W pozostałej części opcji użyj wartości w poniższej tabeli:

Ustawienie	Wartość	Opis
Szablon funkcji	Pusty	Spowoduje to utworzenie projektu bez wyzwalacza, co zapewnia większą kontrolę nad nazwą funkcji wyzwalanej przez protokół HTTP podczas dodawania go później.
Używanie usługi Azurite na potrzeby konta magazynu środowiska uruchomieniowego (AzureWebJobsStorage)	Wybrany	Możesz użyć emulatora do lokalnego opracowywania funkcji wyzwalacza HTTP. Ponieważ aplikacja funkcji na platformie Azure wymaga konta magazynu, jest przypisywana lub tworzona podczas publikowania projektu na platformie Azure.
Poziom autoryzacji	Funkcja	W przypadku uruchamiania na platformie Azure klienci muszą podać klucz podczas uzyskiwania dostępu do punktu końcowego. Aby uzyskać więcej informacji, zobacz Poziom autoryzacji.

Wybierz pozycję Utwórz , aby utworzyć projekt funkcji.

Następnie zaktualizujesz projekt, instalując rozszerzenie OpenAPI dla usługi Azure Functions, co umożliwia odnajdywanie punktów końcowych interfejsu API w aplikacji.

Instalowanie rozszerzenia OpenAPI

Aby zainstalować rozszerzenie OpenAPI:

W menu Narzędzia wybierz pozycję NuGet Menedżer pakietów> Menedżer pakietów Konsola.
W konsoli uruchom następujące polecenie Install-Package , aby zainstalować rozszerzenie OpenAPI:
- Model izolowanego procesu roboczego
- Model w procesie
```
NuGet\Install-Package Microsoft.Azure.Functions.Worker.Extensions.OpenApi -Version 1.5.1
```
Może być konieczne zaktualizowanie określonej wersji na podstawie używanej wersji platformy .NET.
```
NuGet\Install-Package Microsoft.Azure.WebJobs.Extensions.OpenApi -Version 1.5.1
```
Może być konieczne zaktualizowanie określonej wersji na podstawie używanej wersji platformy .NET.

Teraz możesz dodać funkcję punktu końcowego HTTP.

Dodawanie funkcji punktu końcowego HTTP

W bibliotece klas języka C# powiązania używane przez funkcję są definiowane przez zastosowanie atrybutów w kodzie. Aby utworzyć funkcję z wyzwalaczem HTTP:

W Eksplorator rozwiązań kliknij prawym przyciskiem myszy węzeł projektu i wybierz polecenie Dodaj>nową funkcję platformy Azure.
Wprowadź Turbine.cs dla klasy, a następnie wybierz pozycję Dodaj.
Wybierz szablon wyzwalacza Http, ustaw poziom autoryzacji na Wartość Funkcja, a następnie wybierz pozycję Dodaj. Plik kodu Turbine.cs jest dodawany do projektu, który definiuje nowy punkt końcowy funkcji z wyzwalaczem HTTP.

Teraz możesz zastąpić kod szablonu wyzwalacza HTTP kodem implementujący punkt końcowy funkcji Turbina wraz z atrybutami, które używają interfejsu OpenAPI do zdefiniowania punktu końcowego.

Aktualizacja kodu funkcji

Funkcja używa wyzwalacza HTTP, który przyjmuje dwa parametry:

Nazwa parametru	opis
hours	Szacowany czas naprawy turbiny do najbliższej godziny całkowitej.
pojemność	Pojemność turbiny w kilowatach.

Następnie funkcja oblicza, ile kosztuje naprawa i ile przychodów może zarobić turbina w okresie 24-godzinnym. Parametry są dostarczane w ciągu zapytania lub w ładunku żądania POST.

W pliku projektu Turbine.cs zastąp zawartość klasy wygenerowanej na podstawie szablonu wyzwalacza HTTP następującym kodem, który zależy od modelu procesu:

Model izolowanego procesu roboczego
Model w procesie

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

Ten kod funkcji zwraca komunikat Yes lub No wskazujący, czy naprawa awaryjne jest opłacalna. Zwraca również możliwość przychodu, którą reprezentuje turbina i koszt naprawy turbiny.

Uruchamianie i weryfikowanie interfejsu API lokalnie

Po uruchomieniu funkcji punkty końcowe interfejsu OpenAPI ułatwiają lokalne wypróbowanie funkcji przy użyciu wygenerowanej strony. Nie musisz udostępniać kluczy dostępu do funkcji podczas uruchamiania lokalnego.

Naciśnij F5, aby uruchomić projekt. Gdy środowisko uruchomieniowe usługi Functions jest uruchamiane lokalnie, zestaw punktów końcowych openAPI i Swagger jest wyświetlany w danych wyjściowych wraz z punktem końcowym funkcji.
W przeglądarce otwórz punkt końcowy RenderSwaggerUI, który powinien wyglądać następująco: http://localhost:7071/api/swagger/ui. Strona jest renderowana na podstawie definicji interfejsu OpenAPI.
Wybierz pozycję POST>Wypróbuj, wprowadź wartości i capacity hours jako parametry zapytania lub w treści żądania JSON, a następnie wybierz pozycję Wykonaj.
Po wprowadzeniu wartości całkowitych, takich jak 6 dla hours i 2500 dla capacity, otrzymasz odpowiedź JSON, która wygląda jak w poniższym przykładzie:

Funkcja określająca opłacalność naprawy awaryjnej jest już gotowa. Następnie opublikujesz projekt i definicje interfejsu API na platformie Azure.

Publikowanie projektu na platformie Azure

Przed opublikowaniem projektu musisz mieć aplikację funkcji w subskrypcji platformy Azure. Publikowanie w programie Visual Studio tworzy aplikację funkcji podczas pierwszego publikowania projektu. Może również utworzyć wystąpienie usługi API Management zintegrowane z aplikacją funkcji w celu uwidocznienia interfejsu API TurbineRepair.

W Eksplorator rozwiązań kliknij prawym przyciskiem myszy projekt, a następnie wybierz pozycję Publikuj i w polu Cel wybierz pozycję Azure, a następnie pozycję Dalej.
W polu Określony element docelowy wybierz pozycję Aplikacja funkcji platformy Azure (Windows), aby utworzyć aplikację funkcji działającą w systemie Windows, a następnie wybierz przycisk Dalej.
W obszarze Wystąpienie funkcji wybierz pozycję + Utwórz nową funkcję platformy Azure....

Utwórz nowe wystąpienie przy użyciu wartości określonych w poniższej tabeli:

Ustawienie	Wartość	Opis
Nazwa/nazwisko	Nazwa unikatowa w skali globalnej	Unikatowa nazwa identyfikująca nową aplikację funkcji. Zaakceptuj tę nazwę lub wprowadź nową nazwę. Prawidłowe znaki to: `a-z`, `0-9`i `-`.
Subskrypcja	Twoja subskrypcja	Subskrypcja platformy Azure, która ma być używana. Zaakceptuj tę subskrypcję lub wybierz nową z listy rozwijanej.
Grupa zasobów:	Nazwa grupy zasobów	Grupa zasobów, w której ma zostać utworzona aplikacja funkcji. Wybierz istniejącą grupę zasobów z listy rozwijanej lub wybierz pozycję Nowy , aby utworzyć nową grupę zasobów.
Typ planu	Zużycie	Podczas publikowania projektu w aplikacji funkcji uruchamianej w planie Zużycie płacisz tylko za wykonania aplikacji funkcji. Inne plany hostingu generują wyższe koszty.
Lokalizacja	Lokalizacja usługi	Wybierz lokalizację w regionie w pobliżu Ciebie lub innych usług, do których uzyskujesz dostęp do funkcji.
Azure Storage	Konto magazynu ogólnego przeznaczenia	Konto usługi Azure Storage jest wymagane przez środowisko uruchomieniowe usługi Functions. Wybierz pozycję Nowy , aby skonfigurować konto magazynu ogólnego przeznaczenia. Możesz również wybrać istniejące konto spełniające wymagania dotyczące konta magazynu.

Tworzenie nowej aplikacji funkcji na platformie Azure przy użyciu usługi Storage

Wybierz pozycję Utwórz , aby utworzyć aplikację funkcji i powiązane z nią zasoby na platformie Azure. Stan tworzenia zasobów jest wyświetlany w lewym dolnym rogu okna.
W wystąpieniu usługi Functions upewnij się, że zaznaczono polecenie Uruchom z pliku pakietu. Aplikacja funkcji jest wdrażana przy użyciu narzędzia Zip Deploy z włączonym trybem Uruchom z pakietu . Ta metoda wdrażania jest zalecana dla projektu funkcji, ponieważ zapewnia lepszą wydajność.
Wybierz pozycję Dalej, a następnie na stronie usługi API Management wybierz pozycję + Utwórz interfejs API usługi API Management.

Utwórz interfejs API w usłudze API Management przy użyciu wartości w poniższej tabeli:

Ustawienie	Wartość	Opis
Nazwa interfejsu API	TurbinaRepair	Nazwa interfejsu API.
Nazwa subskrypcji	Twoja subskrypcja	Subskrypcja platformy Azure, która ma być używana. Zaakceptuj tę subskrypcję lub wybierz nową z listy rozwijanej.
Grupa zasobów:	Nazwa grupy zasobów	Wybierz tę samą grupę zasobów co aplikacja funkcji z listy rozwijanej.
Usługa API Management	Nowe wystąpienie	Wybierz pozycję Nowy , aby utworzyć nowe wystąpienie usługi API Management w tej samej lokalizacji w warstwie bezserwerowej. Wybierz przycisk OK , aby utworzyć wystąpienie.

Tworzenie wystąpienia usługi API Management za pomocą interfejsu API

Wybierz pozycję Utwórz , aby utworzyć wystąpienie usługi API Management przy użyciu interfejsu API TurbineRepair z poziomu integracji funkcji.
Wybierz pozycję Zakończ , a po zakończeniu procesu tworzenia profilu publikowania wybierz pozycję Zamknij.
Sprawdź, czy na stronie Publikowanie jest teraz wyświetlany komunikat Gotowe do opublikowania, a następnie wybierz pozycję Publikuj , aby wdrożyć pakiet zawierający pliki projektu w nowej aplikacji funkcji na platformie Azure.

Po zakończeniu wdrażania główny adres URL aplikacji funkcji na platformie Azure jest wyświetlany na karcie Publikowanie .

Pobieranie klucza dostępu funkcji

Na karcie Publikowanie wybierz wielokropek (...) obok pozycji Hosting i wybierz pozycję Otwórz w witrynie Azure Portal. Utworzona aplikacja funkcji jest otwierana w witrynie Azure Portal w domyślnej przeglądarce.
W obszarze Funkcje na stronie Przegląd wybierz pozycję >Turbina, a następnie wybierz pozycję Klucze funkcji.
W obszarze Klucze funkcji wybierz ikonę kopiowania do schowka obok klucza domyślnego. Teraz możesz ustawić ten klucz skopiowany w usłudze API Management, aby mógł uzyskać dostęp do punktu końcowego funkcji.

Konfigurowanie usługi API Management

Na stronie aplikacji funkcji rozwiń węzeł API i wybierz pozycję API Management.
Jeśli aplikacja funkcji nie jest jeszcze połączona z nowym wystąpieniem usługi API Management, wybierz ją w obszarze API Management, wybierz pozycję Api OpenAPI Document on Azure Functions (Dokument Interfejs API>OpenAPI w usłudze Azure Functions), upewnij się, że zaznaczono pole wyboru Import functions (Importowanie funkcji ) i wybierz pozycję Połącz interfejs API. Upewnij się, że dla importu wybrano tylko pozycję TurbineRepair , a następnie wybierz pozycję Wybierz.
Wybierz pozycję Przejdź do usługi API Management w górnej części strony, a następnie w wystąpieniu usługi API Management rozwiń węzeł Interfejsy API.
W obszarze Interfejsy API Wszystkie interfejsy> API wybierz pozycję OpenAPI Document on Azure Functions POST Run (Uruchamianie post usługi Azure Functions>), a następnie w obszarze Przetwarzanie przychodzące wybierz pozycję Dodaj parametry zapytania Ustaw zasady.>
Poniżej pozycji Przetwarzanie przychodzące w obszarze Ustaw parametry zapytania, wpisz code wartość Nazwa, wybierz pozycję +Wartość, wklej skopiowany klucz funkcji i wybierz pozycję Zapisz. Usługa API Management zawiera klucz funkcji, gdy przekazuje wywołania do punktu końcowego funkcji.

Teraz, po ustawieniu klucza funkcji, możesz wywołać punkt końcowy interfejsu turbine API, aby sprawdzić, czy działa on w przypadku hostowania na platformie Azure.

Weryfikowanie interfejsu API na platformie Azure

W interfejsie API wybierz kartę Test, a następnie uruchom post, wprowadź następujący kod w treści>żądania Nieprzetworzone, a następnie wybierz pozycję Wyślij:
```
{
    "hours": "6",
    "capacity": "2500"
}
```
Tak jak wcześniej, można również podać te same wartości co parametry zapytania.
Wybierz pozycję Wyślij, a następnie wyświetl odpowiedź HTTP, aby sprawdzić, czy te same wyniki są zwracane z interfejsu API.

Pobieranie definicji interfejsu OpenAPI

Jeśli interfejs API działa zgodnie z oczekiwaniami, możesz pobrać definicję interfejsu OpenAPI dla nowych hostowanych interfejsów API z usługi API Management.

1. W obszarze Interfejsy API wybierz pozycję OpenAPI Document on Azure Functions (Dokument OpenAPI w usłudze Azure Functions), wybierz wielokropek (...) i wybierz pozycję Eksportuj.
Wybierz środki eksportu interfejsu API, w tym pliki OpenAPI w różnych formatach. Możesz również wyeksportować interfejsy API z usługi Azure API Management do platformy Power Platform.

Czyszczenie zasobów

W poprzednich krokach utworzono zasoby platformy Azure w grupie zasobów. Jeśli nie będziesz już potrzebować tych zasobów w przyszłości, możesz je usunąć przez usunięcie grupy zasobów.

W menu witryny Azure Portal lub na stronie głównej wybierz pozycję Grupy zasobów. Następnie na stronie Grupy zasobów wybierz utworzoną grupę.

Na stronie myResourceGroup upewnij się, że wymienione zasoby są tymi, które chcesz usunąć.

Wybierz pozycję Usuń grupę zasobów, wpisz nazwę grupy w polu tekstowym, aby potwierdzić, a następnie wybierz pozycję Usuń.

Następne kroki

Program Visual Studio 2022 został użyty do utworzenia funkcji, która jest dokumentowana samodzielnie z powodu rozszerzenia OpenAPI i zintegrowanego z usługą API Management. Teraz możesz uściślić definicję w usłudze API Management w portalu. Możesz również dowiedzieć się więcej o usłudze API Management.

Edytowanie definicji interfejsu OpenAPI w usłudze API Management

Udostępnij za pośrednictwem