Vytváření bezserverových rozhraní API v sadě Visual Studio pomocí azure Functions a integrace služby API Management

Rozhraní REST API se často popisují pomocí souboru OpenAPI definice (dříve označovaného jako Swagger). Tento soubor obsahuje informace o operacích v rozhraní API a o tom, jak by měla být strukturovaná data požadavků a odpovědí pro rozhraní API.

V tomto kurzu se naučíte:

• Vytvoření projektu kódu v sadě Visual Studio
• Instalace rozšíření OpenAPI
• Přidání koncového bodu triggeru HTTP, který obsahuje definice OpenAPI
• Místní testování rozhraní API funkcí pomocí integrovaných funkcí OpenAPI
• Publikování projektu do aplikace funkcí v Azure
• Povolení integrace služby API Management
• Stažení definičního souboru OpenAPI

Funkce bez serveru, kterou vytvoříte, poskytuje rozhraní API, které umožňuje určit, jestli je tísňová oprava větrné turbíny nákladově efektivní. Vzhledem k tomu, že vytvoříte aplikaci funkcí i instanci služby API Management ve vrstvě Consumption, jsou vaše náklady na dokončení tohoto kurzu minimální.

Požadavky

• Visual Studio 2022. Ujistěte se, že jste během instalace vybrali úlohu vývoje pro Azure.

• Než začnete, vytvořte si aktivní předplatné Azure a vytvořte si bezplatný účet .

Vytvoření projektu kódu

Š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 ze šablony, která podporuje generování definičního souboru OpenAPI (dříve Swagger file).

1. V nabídce sady Visual Studio vyberte Soubor>nový>projekt.

2. V části Vytvořit nový projekt zadejte do vyhledávacího pole funkce , zvolte šablonu Azure Functions a pak vyberte Další.

3. V části Konfigurovat nový projekt zadejte název projektu, například TurbineRepair, a pak vyberte Vytvořit.

4. V části Vytvořit nové nastavení aplikace Azure Functions vyberte jednu z těchto možností pro pracovní proces Functions, kde vybraná možnost závisí na zvoleném modelu procesu:

   Izolovaný model pracovního procesu

   Izolované prostředí .NET 8.0 (dlouhodobá podpora):: Funkce jazyka C# běží v izolovaném pracovním modelu, který se doporučuje. Další informace najdete v průvodci izolovaným modelem pracovního procesu.

   Probíhá proces

   Důležité

   Podpora modelu v procesu skončí 10. listopadu 2026. Důrazně doporučujeme migrovat aplikace do izolovaného modelu pracovního procesu pro plnou podporu.

   .NET 8.0 (dlouhodobá podpora):: Funkce jazyka C# běží v modelu v procesu, které budou vyřazeny. Další informace najdete v průvodci modelem v procesu.

5. Pro zbývající možnosti použijte hodnoty v následující tabulce:

   Nastavení	Hodnota	Popis
   Šablona funkce	Prázdný	Tím se vytvoří projekt bez triggeru, který vám dává větší kontrolu nad názvem funkce aktivované protokolem HTTP, když ji později přidáte.
   Použití Azurite pro účet úložiště runtime (AzureWebJobsStorage)	Vybraný	Emulátor můžete použít pro místní vývoj 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 najdete v tématu Úroveň autorizace.

6. Výběrem možnosti Vytvořit vytvořte projekt funkce.

Dále projekt aktualizujete instalací rozšíření OpenAPI pro Azure Functions, které umožňuje zjistitelnost koncových bodů rozhraní API ve vaší aplikaci.

Instalace rozšíření OpenAPI

Instalace rozšíření OpenAPI:

1. V nabídce Nástroje vyberte Správce balíčků> NuGet Správce balíčků Konzola.

2. V konzole spusťte následující příkaz Install-Package pro instalaci rozšíření OpenAPI:

   Izolovaný model pracovního procesu

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

   Možná budete muset aktualizovat konkrétní verzi na základě vaší verze .NET.

   Model v procesu

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

   Možná budete muset aktualizovat konkrétní verzi na základě vaší verze .NET.

Teď můžete přidat funkci koncového bodu HTTP.

Přidání funkce koncového bodu HTTP

V knihovně tříd jazyka C# jsou vazby používané funkcí definovány použitím atributů v kódu. Vytvoření funkce s triggerem HTTP:

1. V Průzkumník řešení klikněte pravým tlačítkem na uzel projektu a vyberte Přidat>novou funkci Azure Functions.

2. Zadejte Turbine.cs pro třídu a pak vyberte Přidat.

3. Zvolte šablonu triggeru HTTP, nastavte úroveň autorizace na funkci a pak vyberte Přidat. Do projektu se přidá soubor kódu Turbine.cs, který definuje nový koncový bod funkce s triggerem HTTP.

Teď můžete kód šablony triggeru HTTP nahradit kódem, který implementuje koncový bod funkce turbíny, spolu s atributy, které k definování koncového bodu používají OpenAPI.

Aktualizace kódu funkce

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

Název parametru	Popis
hours	Odhadovaná doba opravy turbíny až do nejbližší celé hodiny.
kapacita	Kapacita turbíny v kilowattech.

Funkce pak vypočítá, kolik nákladů na opravu a kolik výnosů by turbína mohla provést v 24hodinovém období. Parametry se zadají buď v řetězci dotazu, nebo v datové části požadavku POST.

V souboru projektu Turbine.cs nahraďte obsah třídy vygenerované ze šablony triggeru HTTP následujícím kódem, který závisí na vašem modelu procesu:

Izolovaný model pracovního procesu

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

Model v procesu

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

Tento kód funkce vrátí zprávu Yes nebo No označuje, jestli je tísňová oprava nákladově efektivní. Vrátí také prodejní příležitost, kterou 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 funkcí.

1. Stisknutím klávesy F5 spusťte projekt. Když se modul runtime Functions spustí místně, zobrazí se ve výstupu společně s koncovým bodem funkce sada koncových bodů OpenAPI a Swagger.

2. V prohlížeči otevřete koncový bod RenderSwaggerUI, který by měl vypadat nějak http://localhost:7071/api/swagger/uitakto. Stránka se vykreslí na základě definic OpenAPI.

3. Vyberte POST>Try it out, zadejte hodnoty pro hours capacity parametry dotazu nebo do textu požadavku JSON a vyberte Spustit.

   

4. Když zadáte celočíselné hodnoty jako 6 pro hours a 2500 pro capacity, získáte 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 své definice projektu a rozhraní API do Azure.

Publikování projektu do Azure

Než budete moct projekt publikovat, musíte mít v předplatném Azure aplikaci funkcí. Publikování sady Visual Studio vytvoří aplikaci funkcí při prvním publikování projektu. Může také vytvořit instanci služby API Management, která se integruje s vaší aplikací funkcí a zpřístupňuje rozhraní TurbineRepair API.

1. V Průzkumník řešení klikněte pravým tlačítkem myši na projekt a vyberte Publikovat a v cíli vyberte Azure a pak Další.

2. Pro konkrétní cíl zvolte Aplikaci funkcí Azure (Windows) a vytvořte aplikaci funkcí, která běží ve Windows, a pak vyberte Další.

3. V instanci funkce zvolte + Vytvořit novou funkci Azure...

   

4. Vytvořte novou instanci pomocí hodnot zadaných v následující tabulce:

   Nastavení	Hodnota	Popis
   Jméno	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-9a -.
   Předplatné	Vaše předplatné	Předplatné Azure, které se má použít. Přijměte toto předplatné nebo v rozevíracím seznamu vyberte nové.
   Skupina prostředků	Název vaší skupiny prostředků	Skupina prostředků, ve které chcete vytvořit aplikaci funkcí. V rozevíracím seznamu vyberte existující skupinu prostředků nebo zvolte Možnost Nový a vytvořte novou skupinu prostředků.
   Typ plánu	Využití	Když projekt publikujete do aplikace funkcí, která běží v plánu Consumption, platíte jenom za provádění aplikace funkcí. Jiné plány hostování účtují vyšší náklady.
   Místo	Umístění služby	Zvolte umístění v oblasti blízko vás nebo jiné služby, ke kterým vaše funkce přistupují.
   Azure Storage	Účet úložiště pro obecné účely	Modul runtime Functions vyžaduje účet Azure Storage. Výběrem možnosti Nový 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ě.

   

5. Výběrem možnosti Vytvořit vytvoříte aplikaci funkcí a související prostředky v Azure. Stav vytváření prostředků se zobrazí v levém dolním rohu okna.

6. Vraťte se do instance služby Functions a ujistěte se, že je zaškrtnuté políčko Spustit ze souboru balíčku. Aplikace funkcí se nasadí pomocí příkazu Zip Deploy s povoleným režimem Spustit z balíčku . Tato metoda nasazení se doporučuje pro váš projekt funkcí, protože vede k lepšímu výkonu.

7. Vyberte Další a na stránce API Management také zvolte + Vytvořit rozhraní API služby API Management.

8. Vytvořte rozhraní API ve službě 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 v rozevíracím seznamu vyberte nové.
   Skupina prostředků	Název vaší skupiny prostředků	V rozevíracím seznamu vyberte stejnou skupinu prostředků jako vaše aplikace funkcí.
   Služba API Management	Nová instance	Výběrem možnosti Nový vytvoříte novou instanci služby API Management ve stejném umístění v bezserverové úrovni. Vyberte OK a vytvořte instanci.

   

9. Výběrem možnosti Vytvořit vytvořte instanci služby API Management s rozhraním API TurbineRepair z integrace funkce.

10. Vyberte Dokončit a po dokončení procesu vytváření profilu publikování vyberte Zavřít.

11. Ověřte, že stránka Publikovat je teď připravená k publikování, a pak výběrem možnosti Publikovat 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

1. Na kartě Publikovat vyberte tři tečky (...) vedle položky Hostování a vyberte Otevřít na webu Azure Portal. Aplikace funkcí, kterou jste vytvořili, se otevře na webu Azure Portal ve výchozím prohlížeči.

2. V části Funkce na stránce Přehled vyberte> Turbína a pak vyberte Funkční klíče.

   

3. V části Funkční klávesy vyberte ikonu kopírovat do schránky vedle výchozího klíče. Teď můžete tento klíč zkopírovaný ve službě API Management nastavit tak, aby mohl přistupovat ke koncovému bodu funkce.

Nakonfigurovat službu API Management

1. Na stránce aplikace funkcí rozbalte rozhraní API a vyberte API Management.

2. Pokud aplikace funkcí ještě není připojená k nové instanci služby API Management, vyberte ji v části API Management, vyberte dokument API>OpenAPI ve službě Azure Functions, zkontrolujte, jestli jsou zaškrtnuté funkce Import a vyberte Propojit rozhraní API. Ujistěte se, že je pro import vybrána pouze turbínaRepair , a pak vyberte.

3. V horní části stránky vyberte Přejít do služby API Management a v instanci SLUŽBY API Management rozbalte rozhraní API.

4. V části Rozhraní>API všechna rozhraní API vyberte Dokument OpenAPI ve službě Azure Functions>POST Run a pak v části Příchozí zpracování vyberte Přidat parametry dotazu Set zásad.>

5. Pod příchozím zpracováním v části Nastavit parametry dotazu zadejte code název, vyberte +Hodnota, vložte zkopírovaný funkční klíč a vyberte Uložit. Služba API Management zahrnuje klíč funkce při průchodu volání do koncového bodu funkce.

   

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

Ověření rozhraní API v Azure

1. V rozhraní API vyberte kartu Test a pak POST Run, do textu> požadavku 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.

2. Vyberte Odeslat a pak zobrazte odpověď HTTP, abyste ověřili, že se z rozhraní API vrátí 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 pro nová hostovaná rozhraní API ze služby API Management.

1. 1. V části Rozhraní API vyberte Dokument OpenAPI ve službě Azure Functions, vyberte tři tečky (...) a vyberte Exportovat.

   

2. Zvolte způsob exportu rozhraní API, včetně souborů OpenAPI v různých formátech. Rozhraní API můžete také exportovat ze služby Azure API Management do power platformy.

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 webu 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ů, do textového pole zadejte název skupiny, abyste ji potvrdili, a pak vyberte Odstranit.

Další kroky

Pomocí sady Visual Studio 2022 jste vytvořili funkci, která je samodokumentovaná kvůli rozšíření OpenAPI a integrované se službou API Management. Definici teď můžete upřesnit ve službě API Management na portálu. Další informace o službě API Management najdete také.

Úprava definice OpenAPI ve službě API Management