Kiszolgáló nélküli API-k létrehozása a Visual Studióban az Azure Functions és az API Management integrációjával

A REST API-kat gyakran openAPI-definíciós (korábbi nevén Swagger-) fájllal írják le. Ez a fájl információkat tartalmaz az API műveleteiről, valamint az API kérési és válaszadatainak strukturálásáról.

Ebben az oktatóanyagban az alábbiakkal fog megismerkedni:

• Kódprojekt létrehozása a Visual Studióban
• Az OpenAPI-bővítmény telepítése
• HTTP-eseményindító végpont hozzáadása, amely OpenAPI-definíciókat is tartalmaz
• Függvény API-k helyi tesztelése beépített OpenAPI-funkciókkal
• Projekt közzététele függvényalkalmazásban az Azure-ban
• API Management-integráció engedélyezése
• Az OpenAPI definíciós fájljának letöltése

A létrehozott kiszolgáló nélküli függvény egy API-t biztosít, amely lehetővé teszi annak megállapítását, hogy a szélturbina vészhelyreállítása költséghatékony-e. Mivel a függvényalkalmazást és az API Management-példányt is használatszinten hozza létre, az oktatóanyag elvégzéséhez szükséges költségek minimálisak.

Előfeltételek

• Visual Studio 2022. Győződjön meg arról, hogy a telepítés során kiválasztja az Azure fejlesztési számítási feladatát.

• Az aktív Azure-előfizetés megkezdése előtt hozzon létre egy ingyenes fiókot .

A kódprojekt létrehozása

A Visual Studio Azure Functions-projektsablonja létrehoz egy projektet, amelyet közzétehet egy függvényalkalmazásban az Azure-ban. Egy HTTP-aktivált függvényt is létrehoz egy olyan sablonból, amely támogatja az OpenAPI definíciós fájl (korábbi nevén Swagger-fájl) létrehozását.

1. A Visual Studio menüjében válassza az Új>projekt fájlja>lehetőséget.

2. Új projekt létrehozásakor írja be a függvényeket a keresőmezőbe, válassza ki az Azure Functions-sablont, majd válassza a Tovább gombot.

3. Az új projekt konfigurálásához írja be a projekt nevét a következőhöz hasonló módonTurbineRepair, majd válassza a Létrehozás lehetőséget.

4. Az új Azure Functions-alkalmazásbeállítások létrehozásához válassza ki a Functions-feldolgozó alábbi beállításait, ahol a választott beállítás a választott folyamatmodelltől függ:

   Izolált feldolgozói modell

   .NET 8.0 Izolált (hosszú távú támogatás): A C# függvények az izolált feldolgozó modellben futnak, ami ajánlott. További információkért tekintse meg az izolált feldolgozómodell-útmutatót.

   Folyamatban

   Fontos

   A folyamaton belüli modell támogatása 2026. november 10-én megszűnik. Erősen javasoljuk, hogy az alkalmazásokat az elkülönített feldolgozói modellbe migrálja a teljes támogatás érdekében.

   .NET 8.0 (hosszú távú támogatás): A C# függvények a folyamaton belüli modellben futnak, amelyet a rendszer kivon. További információkért tekintse meg a folyamaton belüli modell útmutatót.

5. A többi lehetőséghez használja az alábbi táblázatban szereplő értékeket:

   Beállítás	Érték	Leírás
   Függvénysablon	Üres	Ez egy eseményindító nélküli projektet hoz létre, amely nagyobb mértékben szabályozza a HTTP által aktivált függvény nevét, amikor később hozzáadja.
   Az Azurite használata futtatókörnyezeti tárfiókhoz (AzureWebJobsStorage)	Kiválasztott	Az emulátort a HTTP-triggerfüggvények helyi fejlesztéséhez használhatja. Mivel az Azure-ban egy függvényalkalmazáshoz tárfiókra van szükség, a rendszer hozzárendel vagy létrehoz egyet, amikor közzéteszi a projektet az Azure-ban.
   Engedélyszint	Függvény	Az Azure-ban való futtatáskor az ügyfeleknek meg kell adniuk egy kulcsot a végpont elérésekor. További információ: Engedélyezési szint.

6. A függvényprojekt létrehozásához válassza a Létrehozás lehetőséget.

Ezután frissítse a projektet az Azure Functions OpenAPI-bővítményének telepítésével, amely lehetővé teszi az API-végpontok felderítését az alkalmazásban.

Az OpenAPI-bővítmény telepítése

Az OpenAPI-bővítmény telepítése:

1. Az Eszközök menüben válassza a NuGet Csomagkezelő> Csomagkezelő Konzol lehetőséget.

2. A konzolon futtassa a következő Install-Package parancsot az OpenAPI-bővítmény telepítéséhez:

   Izolált feldolgozói modell

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

   Előfordulhat, hogy frissítenie kell az adott verziót a .NET-verzió alapján.

   Folyamaton belüli modell

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

   Előfordulhat, hogy frissítenie kell az adott verziót a .NET-verzió alapján.

Most hozzáadhatja a HTTP-végpontfüggvényt.

HTTP-végpontfüggvény hozzáadása

Egy C#-osztálytárban a függvény által használt kötések a kód attribútumainak alkalmazásával vannak definiálva. Függvény létrehozása HTTP-eseményindítóval:

1. A Megoldáskezelő kattintson a jobb gombbal a projektcsomópontra, és válassza az Új Azure-függvény hozzáadása>lehetőséget.

2. Adja meg az osztályhoz tartozó Turbine.cs, majd válassza a Hozzáadás lehetőséget.

3. Válassza ki a Http-eseményindító sablont, állítsa be az engedélyezési szintet függvényre, majd válassza a Hozzáadás lehetőséget. A program hozzáad egy Turbine.cs kódfájlt a projekthez, amely egy új függvényvégpontot határoz meg HTTP-eseményindítóval.

Most lecserélheti a HTTP-eseményindító sablonkódot a Turbine függvény végpontját megvalósító kódra, valamint az OpenAPI-t használó attribútumokra a végpont definiálásához.

A függvénykód módosítása

A függvény egy HTTP-eseményindítót használ, amely két paramétert használ:

Paraméter neve	Leírás
hours	A turbina javításának becsült ideje, akár a legközelebbi egész órában.
kapacitás	A turbina kapacitása kilowattban.

A függvény ezután kiszámítja, hogy mennyi javítási költséget és mennyi bevételt érhet el a turbina egy 24 órás időszakban. A paraméterek a lekérdezési sztringben vagy a POST-kérés hasznos adataiban vannak megadva.

A Turbine.cs projektfájlban cserélje le a HTTP-eseményindító sablonból létrehozott osztály tartalmát a következő kódra, amely a folyamatmodelltől függ:

Izolált feldolgozói modell

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

Folyamaton belüli modell

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

Ez a függvénykód egy üzenetet Yes ad vissza, vagy No jelzi, hogy a vészhelyreállítás költséghatékony-e. A turbina által képviselt bevételi lehetőséget és a turbina javításának költségeit is visszaadja.

Az API helyi futtatása és ellenőrzése

A függvény futtatásakor az OpenAPI-végpontok megkönnyítik a függvény helyi kipróbálást egy létrehozott lap használatával. Helyi futtatáskor nem kell függvényelérési kulcsokat megadnia.

1. Nyomja le az F5 billentyűt a projekt elindításához. Amikor a Functions-futtatókörnyezet helyileg indul el, a kimenetben OpenAPI- és Swagger-végpontok halmaza jelenik meg a függvényvégponttal együtt.

2. A böngészőben nyissa meg a RenderSwaggerUI végpontot, amelynek így kell kinéznie http://localhost:7071/api/swagger/ui. A lap az OpenAPI-definíciók alapján jelenik meg.

3. Válassza a POST>Kipróbálás lehetőséget, adja meg a lekérdezési paraméterek vagy a JSON-kérelem törzsének értékeit capacity hours, majd válassza a Végrehajtás lehetőséget.

   

4. Ha olyan egész számértékeket ad meg, mint például a 6 és hours a 2500 capacity, jSON-választ kap, amely az alábbi példához hasonlóan néz ki:

   

Most már van egy olyan függvénye, amely megállapítja a sürgősségi javítások költséghatékonyságát. Ezután közzéteheti a projekt- és API-definíciókat az Azure-ban.

A projekt közzététele az Azure-ban

A projekt közzététele előtt rendelkeznie kell egy függvényalkalmazással az Azure-előfizetésében. A Visual Studio közzétételével a projekt első közzétételekor létrehoz egy függvényalkalmazást. Létrehozhat egy API Management-példányt is, amely integrálható a függvényalkalmazással a TurbineRepair API közzététele érdekében.

1. A Megoldáskezelő kattintson a jobb gombbal a projektre, és válassza a Közzététel lehetőséget, majd a Cél területen válassza az Azure, majd a Tovább lehetőséget.

2. Az Adott célhoz válassza az Azure Function App (Windows) lehetőséget a Windowson futó függvényalkalmazás létrehozásához, majd válassza a Tovább gombot.

3. A függvénypéldányban válassza a + Új Azure-függvény létrehozása... lehetőséget.

   

4. Hozzon létre egy új példányt az alábbi táblázatban megadott értékekkel:

   Beállítás	Érték	Leírás
   Név	Globálisan egyedi név	Az új függvényalkalmazást azonosító egyedi név. Fogadja el ezt a nevet, vagy adjon meg egy új nevet. Az érvényes karakterek a következők: a-z, 0-9és -.
   Előfizetés	Az Ön előfizetése	A használandó előfizetés. Fogadja el ezt az előfizetést, vagy válasszon egy újat a legördülő listából.
   Erőforráscsoport	Az erőforráscsoport neve	Az az erőforráscsoport, amelyben létre kívánja hozni a függvényalkalmazást. Válasszon ki egy meglévő erőforráscsoportot a legördülő listából, vagy válassza az Új lehetőséget egy új erőforráscsoport létrehozásához.
   Csomag típusa	Felhasználás	Ha a projektet egy használatalapú tervben futó függvényalkalmazásban teszi közzé, csak a függvényalkalmazás végrehajtásáért kell fizetnie. Más üzemeltetési tervek magasabb költségekkel járnak.
   Helyen	A szolgáltatás helye	Válasszon egy helyet egy Önhöz közeli régióban vagy más szolgáltatásokban, amelyekhez a függvények hozzáférnek.
   Azure Storage	Általános célú tárfiók	A Functions-futtatókörnyezet egy Azure Storage-fiókot igényel. Általános célú tárfiók konfigurálásához válassza az Új lehetőséget. Választhat olyan meglévő fiókot is, amely megfelel a tárfiók követelményeinek.

   

5. A Létrehozás gombra kattintva létrehozhat egy függvényalkalmazást és annak kapcsolódó erőforrásait az Azure-ban. Az erőforrás-létrehozás állapota az ablak bal alsó részén jelenik meg.

6. A Functions-példányban ellenőrizze, hogy a Csomagfájlból futtatás jelölőnégyzet be van-e jelölve. A függvényalkalmazás üzembe helyezése a Zip Deploy használatával történik, és engedélyezve van a csomagalapú futtatás mód. Ez az üzembe helyezési módszer a függvényprojekthez ajánlott, mivel jobb teljesítményt eredményez.

7. Válassza a Tovább lehetőséget, és az API Management lapon válassza az + API Management API létrehozása lehetőséget is.

8. Hozzon létre egy API-t az API Managementben az alábbi táblázat értékeinek használatával:

   Beállítás	Érték	Leírás
   API-név	TurbineRepair	Az API neve.
   Előfizetés neve	Az Ön előfizetése	A használandó előfizetés. Fogadja el ezt az előfizetést, vagy válasszon egy újat a legördülő listából.
   Erőforráscsoport	Az erőforráscsoport neve	Válassza ki ugyanazt az erőforráscsoportot, mint a függvényalkalmazás a legördülő listából.
   API Management szolgáltatás	Új példány	Az Új lehetőséget választva hozzon létre egy új API Management-példányt a kiszolgáló nélküli réteg ugyanazon helyén. Kattintson az OK gombra a példány létrehozásához.

   

9. A Létrehozás lehetőséget választva hozza létre az API Management-példányt a TurbineRepair API-val a függvényintegrációból.

10. Válassza a Befejezés lehetőséget , és miután a közzétételi profil létrehozási folyamata befejeződött, válassza a Bezárás lehetőséget.

11. Ellenőrizze, hogy a Közzététel lap most már a közzétételre kész állapotban van-e, majd válassza a Közzététel lehetőséget a projektfájlokat tartalmazó csomag üzembe helyezéséhez az Új függvényalkalmazásban az Azure-ban.

    Az üzembe helyezés befejezése után az Azure-ban a függvényalkalmazás gyökér URL-címe megjelenik a Közzététel lapon.

A függvény hozzáférési kulcsának lekérése

1. A Közzététel lapon válassza az Üzemeltetés melletti három pontot (...), majd a Megnyitás az Azure Portalon lehetőséget. A létrehozott függvényalkalmazás megnyílik az Azure Portalon az alapértelmezett böngészőben.

2. Az Áttekintés lap Függvények területén válassza >a Turbina lehetőséget, majd válassza a Függvénykulcsok lehetőséget.

   

3. A Függvénykulcsok területen válassza ki a vágólapra másolás ikont az alapértelmezett kulcs mellett. Most már beállíthatja ezt a kulcsot, amelyet az API Managementben másolt, hogy hozzáférhessen a függvényvégponthoz.

Az API Management konfigurálása

1. A függvényalkalmazás lapján bontsa ki az API-t, és válassza az API Management lehetőséget.

2. Ha a függvényalkalmazás még nincs csatlakoztatva az új API Management-példányhoz, jelölje ki az API Management területen, válassza az API>OpenAPI-dokumentumot az Azure Functionsben, győződjön meg arról, hogy a Függvények importálása jelölőnégyzet be van jelölve, és válassza a Link API lehetőséget. Győződjön meg arról, hogy csak a TurbineRepair van kiválasztva importálásra, majd válassza ki.

3. Válassza a lap tetején az API Management megnyitása lehetőséget, majd az API Management-példányban bontsa ki az API-kat.

4. Az API-k minden API-jában> válassza az OpenAPI-dokumentumot az Azure Functions>POST-futtatáson, majd a Bejövő feldolgozás területen válassza a Szabályzatkészlet>lekérdezési paramétereinek hozzáadása lehetőséget.

5. A bejövő feldolgozás alatt a Lekérdezési paraméterek beállítása területen írja be code a Név kifejezést, válassza az +Érték lehetőséget, illessze be a másolt függvénykulcsot, és válassza a Mentés lehetőséget. Az API Management tartalmazza a függvénykulcsot, amikor a függvényvégpont felé továbbítja a hívásokat.

   

Most, hogy a függvénykulcs be van állítva, meghívhatja az turbine API-végpontot annak ellenőrzéséhez, hogy működik-e az Azure-ban üzemeltetve.

Az API ellenőrzése az Azure-ban

1. Az API-ban válassza a Teszt lapot, majd a POST-futtatás lehetőséget, írja be a következő kódot a Nyers kérelem törzsbe>, és válassza a Küldés lehetőséget:

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

   

   A korábbiakhoz hasonlóan ugyanazokat az értékeket is megadhatja, mint a lekérdezési paraméterek.

2. Válassza a Küldés lehetőséget, majd tekintse meg a HTTP-választ annak ellenőrzéséhez, hogy ugyanazok az eredmények jelennek-e meg az API-ból.

Az OpenAPI-definíció letöltése

Ha az API a várt módon működik, letöltheti az új üzemeltetett API-k OpenAPI-definícióját az API Managementből.

1. 1. Az API-k alatt válassza az OpenAPI-dokumentumot az Azure Functionsben, jelölje ki a három pontot (...), és válassza az Exportálás lehetőséget.

   

2. Válassza ki az API-exportálás módját, beleértve az OpenAPI-fájlokat is különböző formátumokban. Az API-kat az Azure API Managementből a Power Platformba is exportálhatja.

Az erőforrások eltávolítása

Az előző lépésekben Azure-erőforrásokat hozott létre egy erőforráscsoportban. Ha várhatóan nincs szüksége ezekre az erőforrásokra a későbbiekben, az erőforráscsoport eltávolításával törölheti őket.

Az Azure Portal menüjében vagy kezdőlapján válassza az Erőforráscsoportok lehetőséget. Ezután az Erőforráscsoportok lapon válassza ki a létrehozott csoportot.

A myResourceGroup lapon győződjön meg arról, hogy a felsorolt erőforrásokat törölni szeretné.

Válassza az Erőforráscsoport törlése lehetőséget, írja be a csoport nevét a megerősítéshez a szövegmezőbe, majd válassza a Törlés lehetőséget.

Következő lépések

A Visual Studio 2022-vel létrehozott egy önaláírt függvényt az OpenAPI-bővítmény miatt, és integrálva az API Managementtel. Mostantól pontosíthatja a definíciót az API Managementben a portálon. Az API Managementről további információt is megtudhat.

Az OpenAPI-definíció szerkesztése az API Managementben