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

Interfejsy API REST są często opisywane przy użyciu definicji interfejsu OpenAPI. Ten plik zawiera informacje o operacjach w interfejsie API oraz o tym, jak powinny być ustrukturyzowane dane żądania i odpowiedzi dla interfejsu API.

Ten samouczek zawiera informacje na temat wykonywania następujących czynności:

  • Tworzenie projektu funkcji bezserwerowej w programie Visual Studio
  • Interfejsy API funkcji testowania lokalnie przy użyciu wbudowanych funkcji interfejsu OpenAPI
  • Publikowanie projektu w aplikacji funkcji na platformie Azure przy użyciu integracji API Management
  • Pobierz klucz dostępu dla funkcji i ustaw go w 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ż zarówno aplikacja funkcji, jak i wystąpienie API Management, które tworzysz, korzystają z planów zużycia, koszt ukończenia tego samouczka jest minimalny.

Uwaga

Integracja interfejsu OpenAPI i API Management przedstawiona w tym artykule jest obecnie obsługiwana tylko w przypadku funkcji biblioteki klas w procesie języka C#. Proces izolowanego procesu roboczego Funkcje biblioteki klas języka C# i wszystkie inne środowiska uruchomieniowe języka powinny zamiast tego korzystać z integracji usługi Azure API Management z portalu.

Wymagania wstępne

Tworzenie projektu usługi Functions

Szablon projektu 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, która obsługuje generowanie pliku definicji interfejsu OpenAPI (dawniej pliku Struktury Swagger).

  1. W menu programu Visual Studio wybierz pozycję Plik>nowy>projekt.

  2. W obszarze Tworzenie nowego projektu wprowadź funkcje w polu wyszukiwania, wybierz szablon Azure Functions, a następnie wybierz przycisk Dalej.

  3. W obszarze Konfigurowanie nowego projektu wprowadź nazwę projektu, na przykład TurbineRepair, a następnie wybierz pozycję Utwórz.

  4. W obszarze Tworzenie nowych ustawień aplikacji Azure Functions użyj wartości w poniższej tabeli:

    Ustawienie Wartość Opis
    Proces roboczy funkcji .NET 6 Ta wartość tworzy projekt funkcji, który jest uruchamiany w procesie w wersji 4.x środowiska uruchomieniowego Azure Functions, który jest wymagany do generowania plików OpenAPI.
    Szablon funkcji Wyzwalacz HTTP z interfejsem OpenAPI Ta wartość tworzy funkcję wyzwalaną przez żądanie HTTP z możliwością wygenerowania pliku definicji interfejsu OpenAPI.
    Używanie usługi Azurite na potrzeby konta magazynu środowiska uruchomieniowego (AzureWebJobsStorage) Wybrane Możesz użyć emulatora do lokalnego opracowywania funkcji wyzwalacza HTTP. Ponieważ aplikacja funkcji na platformie Azure wymaga konta magazynu, jest on przypisany lub tworzony podczas publikowania projektu na platformie Azure.
    Poziom autoryzacji Funkcja Podczas uruchamiania na platformie Azure klienci muszą podać klucz podczas uzyskiwania dostępu do punktu końcowego. Aby uzyskać więcej informacji na temat kluczy i autoryzacji, zobacz klucze dostępu do funkcji.

    ustawienia projektu Azure Functions

  5. Wybierz pozycję Utwórz , aby utworzyć projekt funkcji i funkcję wyzwalacza HTTP z obsługą interfejsu OpenAPI.

Program Visual Studio tworzy projekt i klasę o nazwie Function1 , która zawiera kod kociołowy dla typu funkcji wyzwalacza HTTP. Następnie zastąp ten kod szablonu funkcji własnym dostosowanym kodem.

Aktualizacja kodu funkcji

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

Nazwa parametru Opis
Godzin 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 Function1.cs zastąp zawartość wygenerowanego kodu biblioteki klas następującym kodem:

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

Ten kod funkcji zwraca komunikat lub YesNo wskazuje, czy naprawa awaryjne jest opłacalna. Zwraca również szansę 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 dostarczać kluczy dostępu do funkcji podczas uruchamiania lokalnego.

  1. Naciśnij klawisz 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.

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

  3. Wybierz pozycję POST>Wypróbuj, wprowadź wartości dla hours i capacity jako parametry zapytania lub w treści żądania JSON, a następnie wybierz pozycję Wykonaj.

    Interfejs użytkownika struktury Swagger do testowania interfejsu API TurbineRepair

  4. Po wprowadzeniu wartości całkowitych, takich jak 6 dla hours i 2500 dla capacity, otrzymasz odpowiedź JSON, która wygląda następująco:

    Dane JSON odpowiedzi z funkcji TurbineRepair.

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 po raz pierwszy publikując projekt. Może również utworzyć wystąpienie API Management integrujące się z aplikacją funkcji w celu uwidocznienia interfejsu API TurbineRepair.

  1. W Eksplorator rozwiązań kliknij prawym przyciskiem myszy projekt, a następnie wybierz pozycję Publikuj i w obszarze Cel wybierz pozycję Azure, a następnie pozycję Dalej.

  2. 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 pozycję Dalej.

  3. W obszarze Wystąpienie funkcji wybierz pozycję + Utwórz nową funkcję platformy Azure....

    Tworzenie nowego wystąpienia aplikacji funkcji

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

    Ustawienie Wartość Opis
    Nazwa 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-9i -.
    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 Środowisko uruchomieniowe usługi Functions wymaga konta usługi Azure Storage. 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

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

  6. Po powrocie do wystąpienia usługi Functions upewnij się, że zaznaczono pozycję Uruchom z pliku pakietu . Aplikacja funkcji jest wdrażana przy użyciu narzędzia Zip Deploy z włączonym trybem Run-From-Package . Ta metoda wdrażania jest zalecana dla projektu funkcji, ponieważ skutkuje lepszą wydajnością.

  7. Wybierz pozycję Dalej, a na stronie API Management wybierz również pozycję + Utwórz interfejs API API Management.

  8. Utwórz interfejs API w API Management przy użyciu wartości w poniższej tabeli:

    Ustawienie Wartość Opis
    Nazwa interfejsu API TurbineRepair 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 API Management w warstwie bezserwerowej.

    Tworzenie wystąpienia API Management za pomocą interfejsu API

  9. Wybierz pozycję Utwórz, aby utworzyć wystąpienie API Management za pomocą interfejsu API TurbineRepair na podstawie integracji funkcji.

  10. wybierz pozycję Zakończ, sprawdź, czy na stronie Publikowanie jest 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

  1. Na karcie Publikowanie wybierz wielokropek (...) obok pozycji Hosting i wybierz pozycję Otwórz w Azure Portal. Utworzona aplikacja funkcji jest otwierana w Azure Portal w domyślnej przeglądarce.

  2. W obszarze Funkcje wybierz pozycję Functions>TurbineRepair , a następnie wybierz pozycję Klucze funkcji.

    Uzyskiwanie klucza dostępu dla funkcji TurbineRepair

  3. W obszarze Klucze funkcji wybierz pozycję domyślne i skopiuj wartość. Teraz możesz ustawić ten klucz w API Management, aby mógł uzyskać dostęp do punktu końcowego funkcji.

Konfigurowanie usługi API Management

  1. Na karcie Publikowanie wybierz wielokropek (...) obok pozycji Hosting i wybierz pozycję Otwórz interfejs API w Azure Portal. Utworzone wystąpienie API Management jest otwierane w Azure Portal w domyślnej przeglądarce. To wystąpienie API Management jest już połączone z aplikacją funkcji.

  2. W obszarze Interfejsy API wybierz pozycję OpenAPI Document on Azure FunctionsPOST Run (Uruchamianie protokołu > OpenAPI), a następnie w obszarze Przetwarzanie przychodzące wybierz pozycję Dodaj zasady.

    Dodawanie zasad ruchu przychodzącego do interfejsu API

  3. Poniżej pozycji Przetwarzanie przychodzące w obszarze Ustaw parametry zapytania wpisz codewartość Nazwa, wybierz pozycję +Wartość, wklej skopiowany klucz funkcji i wybierz pozycję Zapisz. API Management zawiera klucz funkcji, gdy przekazuje wywołania do punktu końcowego funkcji.

    Podawanie poświadczeń funkcji do reguły przetwarzania przychodzącego interfejsu API

Po ustawieniu klucza funkcji możesz wywołać interfejs API, aby sprawdzić, czy działa on podczas hostowania na platformie Azure.

Weryfikowanie interfejsu API na platformie Azure

  1. W interfejsie API wybierz kartę Test , a następnie pozycję URUCHOM POST, wprowadź następujący kod w treści żądania>Raw i wybierz pozycję Wyślij:

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

    Strona testu interfejsu OpenAPI w interfejsie API API Management

    Tak jak poprzednio, można również podać te same wartości co parametry zapytania.

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

    1. W obszarze Interfejsy API wybierz pozycję Dokument OpenAPI w Azure Functions, wybierz wielokropek (...), a następnie wybierz pozycję Eksportuj.

    Pobieranie definicji interfejsu OpenAPI

  1. 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 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 API Management. Teraz możesz uściślić definicję w API Management w portalu. Możesz również dowiedzieć się więcej o API Management.