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řte projekt 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. Ujistěte se, že jste během instalace vybrali úlohu vývoje pro Azure.

• Abyste mohli začít, je nutné mít aktivní předplatné Azure, nebo si vytvořte 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 Další.

4. U nastavení Další informace 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 in-process modelu, který bude vyřazen. 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žijte Azurite pro účet úložiště za běhu (AzureWebJobsStorage)	Vybraný	Emulátor můžete použít pro místní vývoj funkcí triggeru HTTP. Vzhledem k tomu, že funkční aplikace na Azure vyžaduje účet úložiště, je přiřazen nebo vytvořen při publikování projektu do Azure.

6. Vyberte Vytvořit pro vytvoření projektu 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>Konzolu Správce balíčků.

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 průběhu 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íku řešení klikněte pravým tlačítkem na uzel projektu a vyberte Přidat>Nová funkce Azure.

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
hodiny	Odhadovaná doba opravy turbíny až do nejbližší celé hodiny.
kapacita	Kapacita turbíny v kilowattech.

Funkce pak vypočítá, kolik stojí oprava a kolik by turbína mohla vydělat během 24 hodin. 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 průběhu 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 funkční kód vrací buď zprávu Yes nebo No která označuje, zda je nouzová 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 takto: http://localhost:7071/api/swagger/ui. Stránka se vykreslí na základě definic OpenAPI.

3. Vyberte POST>Try it out, zadejte hodnoty pro hourscapacity 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í pomocí sady Visual Studio vytvoří funkční aplikaci 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íku řešení klikněte pravým tlačítkem na projekt a vyberte Publikovat a v cíli. Vyberte Azure a pak Další.

2. V případě konkrétního cíle zvolte aplikaci Funkcí Azure a vytvořte aplikaci funkcí, která běží ve Windows. 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 funkční aplikaci. 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	Flexibilní Spotřeba	Když projekt publikujete do aplikace funkcí, která běží v plánu Flex 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 Služby Functions vyžaduje účet služby 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. Vaše aplikace funkcí je nasazena pomocí Zip Deploy s povoleným režimem Run-From-Package. 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 novouinstanci nebo Vytvořit novou instanci.

8. Vytvořte rozhraní API ve službě API Management pomocí hodnot v následující tabulce:

   Nastavení	Hodnota	Popis
   Název rozhraní API	TurbineRepair	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 funkční aplikace 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ávesy.

   

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 API dokument OpenAPI na Azure Functions>, zkontrolujte, jestli Import funkcí je zaškrtnuté, a vyberte Propojit API. Ujistěte se, že je pro import vybrána pouze TurbineRepair, a pak Vyberte.

3. V horní části stránky vyberte Přejít do správy API a v instanci správy API rozbalte API.

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

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 funkční klíč nastaven, můžete volat turbine API k ověření, že funguje, když je hostováno v Azure.

Ověření rozhraní API v Azure

1. V API vyberte kartu Test a poté spusťte POST. Do textu> požadavku zadejte následující kóda 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. V části Rozhraní API vyberte Dokument OpenAPI ve službě Azure Functions, vyberte trojtečku (...) 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 z Azure API Management do Power Platformy.

Uvolně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