Vytváření bezserverových rozhraní API v sadě Visual Studio s využitím integrace Azure Functions a API Management

Článek
06/01/2023

Rozhraní REST API se často popisují pomocí definice OpenAPI. Tento soubor obsahuje informace o operacích v rozhraní API a o tom, jak by data požadavků a odpovědí pro rozhraní API měla být strukturovaná.

V tomto kurzu se naučíte:

Vytvoření projektu bezserverové funkce v sadě Visual Studio
Místní testování rozhraní API funkcí pomocí integrovaných funkcí OpenAPI
Publikování projektu do aplikace funkcí v Azure s využitím integrace API Management
Získejte přístupový klíč pro funkci a nastavte ho v API Management
Stažení definičního souboru OpenAPI

Bezserverová funkce, kterou vytvoříte, poskytuje rozhraní API, které vám umožní určit, jestli je nouzová oprava větrné turbíny nákladově efektivní. Vzhledem k tomu, že aplikace funkcí i API Management instance, kterou vytvoříte, používají plány Consumption, jsou náklady na dokončení tohoto kurzu minimální.

Poznámka

Integrace OpenAPI a API Management, která je uvedena v tomto článku, se v současné době podporuje pouze pro procesní funkce knihovny tříd jazyka C#. Izolovaný pracovní proces Funkce knihovny tříd jazyka C# a všechny ostatní moduly runtime jazyka by místo toho měly používat integraci Azure API Management z portálu.

Požadavky

Visual Studio 2022. Ujistěte se, že jste během instalace vybrali úlohu Vývoj pro Azure .
Aktivní předplatné Azure– než začnete, vytvořte si bezplatný účet .

Vytvoření projektu Functions

Šablona projektu Azure Functions v sadě Visual Studio vytvoří projekt, který můžete publikovat do aplikace funkcí v Azure. Vytvoříte také funkci aktivovanou protokolem HTTP, která podporuje generování definičního souboru OpenAPI (dříve soubor Swagger).

V nabídce sady Visual Studio vyberte Soubor>nový>projekt.
V části Vytvořit nový projekt zadejte do vyhledávacího pole funkce, zvolte šablonu Azure Functions a pak vyberte Další.
V části Konfigurace nového projektu zadejte název projektu , například TurbineRepair, a pak vyberte Vytvořit.

Pro nastavení Vytvořit nový Azure Functions aplikace použijte hodnoty v následující tabulce:

Nastavení	Hodnota	Popis
Pracovní proces Functions	.NET 6	Tato hodnota vytvoří projekt funkce, který běží v procesu ve verzi 4.x modulu runtime Azure Functions, který se vyžaduje pro generování souborů OpenAPI.
Šablona funkce	Trigger HTTP s OpenAPI	Tato hodnota vytvoří funkci aktivovanou požadavkem HTTP s možností vygenerovat definiční soubor OpenAPI.
Použití Azurite pro účet úložiště runtime (AzureWebJobsStorage)	Vybráno	Emulátor můžete použít k místnímu vývoji funkcí triggeru HTTP. Vzhledem k tomu, že aplikace funkcí v Azure vyžaduje účet úložiště, přiřadí se nebo vytvoří při publikování projektu do Azure.
Úroveň autorizace	Funkce	Při spuštění v Azure musí klienti při přístupu ke koncovému bodu poskytnout klíč. Další informace o klíčích a autorizaci najdete v tématu přístupové klíče k funkcím.

Azure Functions nastavení projektu

Vyberte Vytvořit a vytvořte projekt funkce a funkci triggeru HTTP s podporou OpenAPI.

Visual Studio vytvoří projekt a třídu s názvem Function1 , která obsahuje často používaný kód pro typ funkce triggeru HTTP. Dále tento kód šablony funkce nahradíte vlastním přizpůsobeným kódem.

Aktualizace kódu funkce

Funkce používá trigger HTTP, který přijímá dva parametry:

Název parametru	Description
Hodin	Odhadovaný čas provedení opravy turbíny, a to až do nejbližší celé hodiny.
Kapacita	Kapacita turbíny v kilowattech.

Funkce pak vypočítá, kolik oprava stojí a kolik výnosů by turbína mohla za 24 hodin vydělat. Parametry se zadají buď v řetězci dotazu, nebo v datové části požadavku POST.

V souboru projektu Function1.cs nahraďte obsah vygenerovaného kódu knihovny tříd následujícím kódem:

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

Tento kód funkce vrátí zprávu Yes nebo No , která označuje, jestli je nouzová oprava nákladově efektivní. Vrátí také výnosy, které turbína představuje, a náklady na opravu turbíny.

Místní spuštění a ověření rozhraní API

Když funkci spustíte, koncové body OpenAPI usnadňují místní vyzkoušení funkce pomocí vygenerované stránky. Při místním spuštění nemusíte zadávat přístupové klíče k funkcím.

Stisknutím klávesy F5 spusťte projekt. Když se modul runtime služby Functions spustí místně, ve výstupu se společně s koncovým bodem funkce zobrazí sada koncových bodů OpenAPI a Swagger.
V prohlížeči otevřete koncový bod RenderSwaggerUI, který by měl vypadat takto http://localhost:7071/api/swagger/ui: . Na základě definic OpenAPI se vykreslí stránka.
Vyberte POST>Vyzkoušet, zadejte hodnoty a hourscapacity buď jako parametry dotazu, nebo do textu požadavku JSON a vyberte Provést.
Když zadáte celočíselné hodnoty, například 6 pro hours a 2500 pro capacity, dostanete odpověď JSON, která vypadá jako v následujícím příkladu:

Nyní máte funkci, která určuje nákladovou efektivitu nouzových oprav. Dále publikujete definice projektu a rozhraní API do Azure.

Publikování projektu do Azure

Před publikováním projektu musíte mít v předplatném Azure aplikaci funkcí. Publikování v sadě Visual Studio vytvoří aplikaci funkcí při prvním publikování projektu. Může také vytvořit instanci API Management, která se integruje s vaší aplikací funkcí a zveřejní rozhraní API TurbineRepair.

V Průzkumník řešení klikněte pravým tlačítkem na projekt a vyberte Publikovat a v části Cíl vyberte Azure a pak Další.
Jako Konkrétní cíl zvolte Azure Function App (Windows) a vytvořte aplikaci funkcí, která běží ve Windows, a pak vyberte Další.
V části Instance funkce zvolte + Vytvořit novou funkci Azure Functions....

Vytvořte novou instanci s použitím hodnot uvedených v následující tabulce:

Nastavení	Hodnota	Popis
Název	Globálně jedinečný název	Název jednoznačně identifikující novou aplikaci funkcí. Přijměte tento název nebo zadejte nový název. Platné znaky jsou: `a-z`, `0-9`a `-`.
Předplatné	Vaše předplatné	Předplatné Azure, které se má použít. Přijměte toto předplatné nebo vyberte nové předplatné z rozevíracího seznamu.
Skupina prostředků	Název vaší skupiny prostředků	Skupina prostředků, ve které se má aplikace funkcí vytvořit. V rozevíracím seznamu vyberte existující skupinu prostředků nebo zvolte Nová a vytvořte novou skupinu prostředků.
Typ plánu	Využití	Při publikování projektu do aplikace funkcí, která běží v plánu Consumption, platíte jenom za spuštění aplikace funkcí. Jiné plány hostování účtují vyšší náklady.
Umístění	Umístění služby	Zvolte umístění v oblasti , která je blízko vás, nebo jiné služby, ke kterým vaše funkce mají přístup.
Azure Storage	Účet úložiště pro obecné účely	Modul runtime služby Functions vyžaduje účet služby Azure Storage. Vyberte Nový a nakonfigurujte účet úložiště pro obecné účely. Můžete také zvolit existující účet, který splňuje požadavky na účet úložiště.

Vytvoření nové aplikace funkcí v Azure se službou Storage

Vyberte Vytvořit a vytvořte aplikaci funkcí a její související prostředky v Azure. Stav vytvoření prostředku se zobrazuje v levém dolním rohu okna.
V instanci Functions se ujistěte, že je zaškrtnuté políčko Spustit ze souboru balíčku . Vaše aplikace funkcí se nasadí pomocí nasazení zipu s povoleným režimem Spustit z balíčku . Tato metoda nasazení se doporučuje pro váš projekt functions, protože vede k lepšímu výkonu.
Vyberte Další a na stránce API Management také + Vytvořit rozhraní API API Management.

Vytvořte rozhraní API v API Management pomocí hodnot v následující tabulce:

Nastavení	Hodnota	Popis
Název rozhraní API	TurbínaRepair	Název rozhraní API
Název předplatného	Vaše předplatné	Předplatné Azure, které se má použít. Přijměte toto předplatné nebo vyberte nové předplatné z rozevíracího seznamu.
Skupina prostředků	Název vaší skupiny prostředků	V rozevíracím seznamu vyberte stejnou skupinu prostředků jako vaše aplikace funkcí.
API Management služba	Nová instance	Vyberte Nový a vytvořte novou instanci API Management na bezserverové úrovni.

Vytvoření instance API Management pomocí rozhraní API

Výběrem možnosti Vytvořit vytvořte instanci API Management s rozhraním API TurbineRepair z integrace funkce.
Vyberte Dokončit, ověřte, že na stránce Publikovat je připraveno k publikování a pak vyberte Publikovat a nasaďte balíček obsahující soubory projektu do nové aplikace funkcí v Azure.

Po dokončení nasazení se na kartě Publikovat zobrazí kořenová adresa URL aplikace funkcí v Azure.

Získání přístupového klíče funkce

Na kartě Publikovat vyberte tři tečky (...) vedle hostování a vyberte Otevřít v Azure Portal. Aplikace funkcí, kterou jste vytvořili, se otevře v Azure Portal ve výchozím prohlížeči.
V části Funkce vyberte Functions>TurbineRepair a pak vyberte Klíče funkcí.
V části Klíče funkcí vyberte výchozí a zkopírujte hodnotu. Teď můžete tento klíč nastavit v API Management, aby mohl přistupovat ke koncovému bodu funkce.

Nakonfigurovat službu API Management

Na kartě Publikovat vyberte tři tečky (...) vedle položky Hostování a vyberte Otevřít rozhraní API v Azure Portal. Instance API Management, kterou jste vytvořili, se otevře v Azure Portal ve výchozím prohlížeči. Tato API Management instance je už propojená s vaší aplikací funkcí.
V části Rozhraní API vyberte Dokument OpenAPI na Azure Functions>POST Run a pak v části Zpracování příchozích dat vyberte Přidat zásadu.
V části Nastavit parametry dotazu v části Zpracování příchozích dat zadejte codenázev, vyberte +Hodnota, vložte zkopírovaný funkční klíč a vyberte Uložit. API Management obsahuje klíč funkce při průchodu volání koncovému bodu funkce.

Teď, když je klíč funkce nastavený, můžete volat rozhraní API a ověřit, že funguje, když je hostované v Azure.

Ověření rozhraní API v Azure

V rozhraní API vyberte kartu Test a pak po spuštění, do textu> požadavkuRaw zadejte následující kód a vyberte Odeslat:
```
{
    "hours": "6",
    "capacity": "2500"
}
```
Stejně jako předtím můžete zadat stejné hodnoty jako parametry dotazu.
Vyberte Odeslat a pak zobrazte odpověď HTTP a ověřte, že se z rozhraní API vrací stejné výsledky.

Stažení definice OpenAPI

Pokud vaše rozhraní API funguje podle očekávání, můžete si stáhnout definici OpenAPI.

1. V části Rozhraní API vyberte dokument OpenAPI na Azure Functions, vyberte tři tečky (...) a vyberte Exportovat.
Zvolte způsob exportu rozhraní API, včetně souborů OpenAPI v různých formátech. Rozhraní API můžete také exportovat z Azure API Management do Power Platform.

Vyčištění prostředků

V předchozích krocích jste vytvořili prostředky Azure ve skupině prostředků. Pokud předpokládáte, že už tyto prostředky nebudete potřebovat, můžete je odstranit tak, že odstraníte skupinu prostředků.

V nabídce Azure Portal nebo na domovské stránce vyberte Skupiny prostředků. Potom na stránce Skupiny prostředků vyberte skupinu, kterou jste vytvořili.

Na stránce myResourceGroup se ujistěte, že uvedené prostředky jsou ty, které chcete odstranit.

Vyberte Odstranit skupinu prostředků, zadejte název skupiny do textového pole, abyste to potvrdili, a pak vyberte Odstranit.

Další kroky

Pomocí sady Visual Studio 2022 jste vytvořili funkci, která se díky rozšíření OpenAPI sama dokumentuje a je integrovaná s API Management. Teď můžete definici upřesnit v API Management na portálu. Můžete si také přečíst další informace o API Management.

Úprava definice OpenAPI v API Management