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

Cikk
06/01/2023

A REST API-kat gyakran OpenAPI-definícióval írják le. Ez a fájl információkat tartalmaz az API műveleteiről, valamint az API kérés- és válaszadatainak strukturálásáról.

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

Kiszolgáló nélküli függvényprojekt létrehozása a Visual Studióban
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óval
Kérje le a függvény hozzáférési kulcsát, és állítsa be API Management
Az OpenAPI-definíciós fájl letöltése

A létrehozott kiszolgáló nélküli függvény egy API-t biztosít, amellyel megállapíthatja, hogy a szélturbinán történő vészjavítás költséghatékony-e. Mivel a függvényalkalmazás és API Management létrehozott példány is használatalapú csomagokat használ, az oktatóanyag elvégzéséhez szükséges költségek minimálisak.

Megjegyzés

A jelen cikkben bemutatott OpenAPI- és API Management-integráció jelenleg csak a C#-osztálykódtár folyamaton belüli függvényeihez támogatott. Izolált feldolgozói folyamat A C#-osztálytár függvényeinek és minden más nyelvi futtatókörnyezetnek ehelyett az Azure API Management portálról történő integrációját kell használnia.

Előfeltételek

Visual Studio 2022. A telepítés során győződjön meg arról, hogy az Azure fejlesztési számítási feladatát választja.
Az aktív Azure-előfizetés megkezdése előtt hozzon létre egy ingyenes fiókot .

Functions-projekt 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 által aktivált függvényt is létre fog hozni, amely támogatja az OpenAPI-definíciós fájl (korábbi nevén Swagger-fájl) létrehozását.

A Visual Studio menüjében válassza azÚj>projektfájlja> lehetőséget.
Az Új projekt létrehozása területen írja be a függvények kifejezést a keresőmezőbe, válassza ki a Azure Functions sablont, majd válassza a Tovább gombot.
Az Új projekt konfigurálása területen adja meg a projekt projektnevét (például TurbineRepair), majd válassza a Létrehozás lehetőséget.

Az Új Azure Functions alkalmazás létrehozása beállításnál használja az alábbi táblázatban szereplő értékeket:

Beállítás	Érték	Leírás
Függvényfeldolgozó	.NET 6	Ez az érték létrehoz egy függvényprojektet, amely folyamatban fut a Azure Functions futtatókörnyezet 4.x verzióján, amely az OpenAPI-fájllétrehozáshoz szükséges.
Függvénysablon	HTTP-eseményindító OpenAPI-val	Ez az érték létrehoz egy HTTP-kérés által aktivált függvényt, amely openAPI-definíciós fájl létrehozására képes.
Az Azurite használata futtatókörnyezeti tárfiókhoz (AzureWebJobsStorage)	Bejelölve	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. A kulcsokkal és az engedélyezéssel kapcsolatos további információkért lásd: függvényhozzáférési kulcsok.

projektbeállítások Azure Functions

Válassza a Létrehozás lehetőséget a függvényprojekt és a HTTP-eseményindító függvény létrehozásához az OpenAPI támogatásával.

A Visual Studio létrehoz egy nevű Function1 projektet és osztályt, amely sablonkódot tartalmaz a HTTP-eseményindító függvénytípushoz. Ezután lecseréli ezt a függvénysablon-kódot a saját testre szabott kódjával.

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 vesz igénybe:

Paraméter neve	Leírás
Óra	A turbina javításának becsült ideje a legközelebbi egész órában.
capacity	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 hozhat 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 Function1.cs projektfájlban cserélje le a létrehozott osztálykódtár kódját a következő kódra:

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

Ez a függvénykód egy vagy No egy üzenetet Yes ad vissza, amely jelzi, hogy egy vészhelyzeti javí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ása egy létrehozott oldal használatával. Helyi futtatáskor nem kell megadnia a függvény-hozzáférési kulcsokat.

Nyomja le az F5 billentyűt a projekt elindításához. Amikor a Functions-futtatókörnyezet helyileg elindul, a kimenetben openAPI- és Swagger-végpontok halmaza jelenik meg a függvényvégponttal együtt.
A böngészőben nyissa meg a RenderSwaggerUI végpontot, amelynek így kell kinéznie http://localhost:7071/api/swagger/ui: . A program megjelenít egy lapot az OpenAPI-definíciók alapján.
Válassza a POST>Próbálja ki lehetőséget, adja meg a és capacity az értékét hours lekérdezési paraméterekként vagy a JSON-kérelem törzsében, majd válassza a Végrehajtás lehetőséget.
Amikor olyan egész számértékeket ad meg, mint a 6 hours és a 2500 capacityérték, egy 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 projektet és az 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 publishing függvényalkalmazást hoz létre a projekt első közzétételekor. Emellett 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.

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.
Az Adott cél mezőben válassza az Azure-függvényalkalmazás (Windows) lehetőséget egy Windowson futó függvényalkalmazás létrehozásához, majd válassza a Tovább gombot.
A Függvénypéldány területen válassza a + Új Azure-függvény létrehozása... lehetőséget.

Hozzon létre egy új példányt a következő 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 írjon be 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 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	Használat	Amikor a projektet egy használatalapú csomagban futó függvényalkalmazásban teszi közzé, csak a függvényalkalmazás végrehajtásáért kell fizetnie. Más üzemeltetési csomagok magasabb költségekkel járnak.
Hely	A szolgáltatás helye	Válasszon egy Helyet az Önhöz közeli régióban vagy a függvények által elérhető egyéb szolgáltatások közül.
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.

Új függvényalkalmazás létrehozása az Azure-ban a Storage használatával

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ó sarkában látható.
A Functions-példányban ellenőrizze, hogy a Futtatás csomagfájlból jelölőnégyzet be van-e jelölve. A függvényalkalmazás a Zip Deploy használatával van üzembe helyezve, és engedélyezve van a Csomagból futtatás mód. Ez az üzembe helyezési módszer a függvényprojekthez ajánlott, mivel jobb teljesítményt eredményez.
Válassza a Tovább lehetőséget, majd API Management lapon válassza a + API Management API létrehozása lehetőséget is.

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

Beállítás	Érték	Leírás
API neve	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ást 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 szinten.

API Management-példány létrehozása API-val

Válassza a Létrehozás lehetőséget a API Management példány létrehozásához a TurbineRepair API-val a függvényintegrációból.
válassza a Befejezés lehetőséget, ellenőrizze, hogy a Közzététel lap 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-beli 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

A Közzététel lapon válassza a Három pont (...) elemet az Üzemeltetés elem mellett, majd válassza a Megnyitás Azure Portal elemet. A létrehozott függvényalkalmazás az alapértelmezett böngészőben található Azure Portal nyílik meg.
A Függvények területen válassza a Functions>TurbineRepair elemet, majd a Függvénykulcsok lehetőséget.
A Függvénykulcsok területen válassza az alapértelmezett lehetőséget, és másolja ki az értéket. Most már beállíthatja ezt a kulcsot API Management, hogy hozzáférhessen a függvényvégponthoz.

Az API Management konfigurálása

A Közzététel lapon válassza a Három pont (...) elemet a Hosting (Üzemeltetés) elem mellett, majd válassza az Api megnyitása Azure Portal lehetőséget. A létrehozott API Management példány az alapértelmezett böngészőben található Azure Portal nyílik meg. Ez a API Management példány már kapcsolódik a függvényalkalmazáshoz.
Az API-k területen válassza az OpenAPI-dokumentumot Azure Functions>POST-futtatáskor, majd a Bejövő feldolgozás területen válassza a Szabályzat hozzáadása lehetőséget.
A Bejövő feldolgozás alatt a Lekérdezési paraméterek beállítása mezőbe í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. API Management tartalmazza a függvénykulcsot, amikor a hívásokat a függvényvégpontra továbbítja.

Most, hogy a függvénykulcs be van állítva, meghívhatja az API-t annak ellenőrzéséhez, hogy működik-e az Azure-ban való üzemeltetéskor.

Az API ellenőrzése az Azure-ban

Az API-ban válassza a Teszt lapot, majd a POST-futtatás parancsot, írja be a következő kódot a Nyers kérelem törzsbe>, majd válassza a Küldés lehetőséget:
```
{
    "hours": "6",
    "capacity": "2500"
}
```
A korábbiakhoz hasonlóan a lekérdezési paraméterekkel megegyező értékeket is megadhat.
Válassza a Küldés lehetőséget, majd tekintse meg a HTTP-választ annak ellenőrzéséhez, hogy a rendszer ugyanazokat az eredményeket adja-e vissza 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 OpenAPI-definíciót.

1. Az API-k területen válassza az OpenAPI-dokumentumot Azure Functions, válassza a három pontot (...), majd az Exportálás lehetőséget.
Válassza ki az API-exportálás módját, beleértve a különböző formátumú OpenAPI-fájlokat is. Az API-kat az Azure API Management-bó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.

A Azure Portal menüben vagy a Kezdőlapon 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ások azok, amelyeket törölni szeretne.

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 olyan függvényt hoz létre, amely az OpenAPI-bővítmény miatt öndokumentumos, és integrálva van a API Management. Mostantól pontosíthatja a definíciót API Management a portálon. A API Management is megismerheti.

Az OpenAPI-definíció szerkesztése a API Management