Share via

A fejlesztői portál kiterjesztése egyéni widgetekkel

  • Cikk

A KÖVETKEZŐKRE VONATKOZIK: Fejlesztő | Alapszintű | Standard | Prémium

Az API Management fejlesztői portál vizualizációszerkesztővel és beépített widgetekkel rendelkezik, így testre szabhatja és stílusba állíthatja a portál megjelenését. Előfordulhat azonban, hogy egyéni funkciókkal tovább kell szabnia a fejlesztői portált. Előfordulhat például, hogy a fejlesztői portált egy olyan támogatási rendszerrel szeretné integrálni, amely egy egyéni felület hozzáadását foglalja magában. Ez a cikk bemutatja, hogyan adhat hozzá egyéni funkciókat, például egyéni widgeteket az API Management fejlesztői portálhoz.

Az alábbi táblázat két lehetőséget foglal össze, és további részletekre mutató hivatkozásokat tartalmaz.

Metódus Leírás
Egyéni HTML-kód widget – Egyszerű megoldás az API-közzétevők számára az egyéni logika alapszintű használati esetekhez való hozzáadásához

– Egyéni HTML-kód másolása és beillesztése egy űrlapba, és a fejlesztői portál iframe-ben jeleníti meg
Egyéni widget létrehozása és feltöltése - Fejlesztői megoldás fejlettebb widget-használati esetekhez

– Helyi implementációt igényel a Reactben, a Vue-ban vagy az egyszerű TypeScriptben

- Widget-állványok és eszközök, amelyek segítenek a fejlesztőknek widgetet létrehozni és feltölteni a fejlesztői portálra

– A widgetek létrehozása, tesztelése és üzembe helyezése szkriptelhető nyílt forráskód React Component Toolkit használatával

– Támogatja a forrásvezérlési, verziószámozási és kód-újrafelhasználási munkafolyamatokat

Feljegyzés

A fejlesztői portál önkiszolgáló üzemeltetése bővíthetőségi lehetőség azoknak az ügyfeleknek, akiknek testre kell szabni a teljes portálmag forráskódját. Teljes rugalmasságot biztosít a portál élményének testreszabásához, de speciális konfigurációt igényel. Az önkiszolgáló üzemeltetéssel ön felelős a kód teljes életciklusának kezeléséért: elágazásos kódbázis, fejlesztés, üzembe helyezés, gazdagép, javítás és frissítés.

Egyéni HTML-kód widget használata

A felügyelt fejlesztői portál tartalmaz egy egyéni HTML-kód widgetet, ahová HTML-kódot szúrhat be a kis portál testreszabásához. Például egyéni HTML-kód használatával ágyazhat be egy videót vagy adhat hozzá egy űrlapot. A portál beágyazott keretben (iframe) jeleníti meg az egyéni widgetet.

  1. A fejlesztői portál felügyeleti felületén lépjen arra a lapra vagy szakaszra, ahová be szeretné szúrni a widgetet.

  2. Jelölje ki a szürke "plusz" (+) ikont, amely akkor jelenik meg, amikor az egérmutatót az oldal fölé viszi.

  3. A Widget hozzáadása ablakban válassza az Egyéni HTML-kód lehetőséget.

    Képernyőkép arról, hogyan vehet fel widgetet egyéni HTML-kódhoz a fejlesztői portálon.

  4. Válassza a "ceruza" ikont a widget testreszabásához.

  5. Adja meg a widget szélességét és magasságát (képpontban).

  6. Ha stílusokat szeretne örökölni a fejlesztői portálról (ajánlott), válassza a Fejlesztői portál stílusának alkalmazása lehetőséget.

    Feljegyzés

    Ha ez a beállítás nincs kiválasztva, a beágyazott elemek egyszerű HTML-vezérlők lesznek, a fejlesztői portál stílusai nélkül.

    Képernyőkép, amely bemutatja, hogyan konfigurálhat egyéni HTML-kódot a fejlesztői portálon.

  7. Cserélje le a minta HTML-kódot az egyéni tartalomra.

  8. Ha a konfiguráció befejeződött, zárja be az ablakot.

  9. Mentse a módosításokat, és tegye közzé újra a portált.

Feljegyzés

A Microsoft nem támogatja az egyéni HTML-kód widgetben hozzáadott HTML-kódot.

Egyéni widget létrehozása és feltöltése

Speciálisabb használati esetek esetén létrehozhat és feltölthet egy egyéni widgetet a fejlesztői portálra. Az API Management egy kódállványt biztosít a fejlesztők számára, hogy egyéni widgeteket hozzanak létre a Reactben, a Vue-ban vagy az egyszerű TypeScriptben. Az állványzat olyan eszközöket tartalmaz, amelyekkel fejlesztheti és helyezheti üzembe a widgetet a fejlesztői portálon.

Előfeltételek

  • Node.JS futtatókörnyezet helyi telepítése
  • Programozás és webfejlesztés alapszintű ismerete

Widget létrehozása

Figyelmeztetés

Az egyéni widget kódját az API Management-példányhoz társított nyilvános Azure Blob Storage tárolja. Amikor egyéni widgetet ad hozzá a fejlesztői portálhoz, a rendszer egy olyan végponton keresztül olvassa be a kódot a tárolóból, amely nem igényel hitelesítést, még akkor is, ha a fejlesztői portál vagy az egyéni widgetet tartalmazó lap csak hitelesített felhasználók számára érhető el. Ne tartalmazzon bizalmas információkat vagy titkos kulcsokat az egyéni widgetkódban.

  1. A fejlesztői portál felügyeleti felületén válassza az Egyéni widgetek>Új egyéni widget létrehozása lehetőséget.

  2. Adjon meg egy widgetnevet, és válasszon egy technológiát. További információkért tekintse meg a cikk későbbi részében található widgetsablonokat.

  3. Válassza a Vezérlő létrehozása lehetőséget.

  4. Nyisson meg egy terminált, keresse meg azt a helyet, ahová menteni szeretné a widgetkódot, és futtassa a következő parancsot a kódállvány letöltéséhez:

    npx @azure/api-management-custom-widgets-scaffolder

  5. Lépjen az újonnan létrehozott mappára, amely tartalmazza a widget kódállványát.

    cd <name-of-widget>

  6. Nyissa meg a mappát a választott kódszerkesztőben, például a VS Code-ban.

  7. Telepítse a függőségeket, és indítsa el a projektet:

    npm install 
npm start

    A böngészőnek meg kell nyitnia egy új lapot, amelyen a fejlesztői portál fejlesztői módban csatlakozik a widgethez.

    Feljegyzés

    Ha a lap nem nyílik meg, tegye a következőket:

    1. Győződjön meg arról, hogy a fejlesztői kiszolgáló elindult. Ehhez ellenőrizze a kimenetet azon a konzolon, ahol az előző lépésben elindította a kiszolgálót. Meg kell jelenítenie azt a portot, http://127.0.0.1:3001amelyen a kiszolgáló fut (például).
    2. Nyissa meg az API Management szolgáltatást az Azure Portalon, és nyissa meg a fejlesztői portált a felügyeleti felülettel.
    3. Fűzze hozzá az /?MS_APIM_CW_localhost_port=3001 elérés utat az URL-címhez. Módosítsa a portszámot, ha a kiszolgáló egy másik porton fut.

  8. Implementálja a widget kódját, és tesztelje helyileg. A widget kódja a src mappában található, az alábbi almappákban:

    • app – Annak a widget-összetevőnek a kódja, amelyet a közzétett fejlesztői portál látogatói látnak és használnak
    • editor - A widget-összetevő kódja, amelyet a fejlesztői portál felügyeleti felületén használ a widgetbeállítások szerkesztéséhez

    A values.ts fájl tartalmazza a widget szerkesztéshez engedélyezhető egyéni tulajdonságainak alapértelmezett értékeit és típusait.

    Képernyőkép az egyéni tulajdonságok lapjáról a fejlesztői portálon.

    Az egyéni tulajdonságok lehetővé teszik az egyéni widget példányának értékeinek módosítását a fejlesztői portál felügyeleti felhasználói felületéről anélkül, hogy módosítaná a kódot, vagy újra üzembe helyezi az egyéni widgetet. Ezt az objektumot át kell adni a widgetek néhány segédfüggvényének.

Az egyéni widget üzembe helyezése a fejlesztői portálon

  1. Adja meg a következő értékeket a deploy.js projekt gyökerében található fájlban:

    • resourceId - Az API Management szolgáltatás erőforrás-azonosítója a következő formátumban: subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.ApiManagement/service/<api-management service-name>

    • managementApiEndpoint - Azure Management API-végpont (általában a környezetétől management.azure.comfügg)

    • apiVersion – Nem kötelező az alapértelmezett felügyeleti API-verzió felülbírálása

  2. Futtassa az alábbi parancsot:

    npm run deploy

    Ha a rendszer kéri, jelentkezzen be az Azure-fiókjába.

    Feljegyzés

    Amikor a rendszer kéri a bejelentkezést, a Microsoft Entra ID-bérlő egyik tagfiókját kell használnia, amely ahhoz az Azure-előfizetéshez van társítva, amelyben az API Management szolgáltatás található. A fiók nem lehet vendég vagy összevont fiók, és megfelelő engedéllyel kell rendelkeznie a portál felügyeleti felületének eléréséhez.

Az egyéni widget üzembe lett helyezve a fejlesztői portálon. A portál felügyeleti felületének használatával felveheti a fejlesztői portál lapjaira, és beállíthatja a widgetben konfigurált egyéni tulajdonságok értékeit.

A fejlesztői portál közzététele

Miután konfigurálta a widgetet a felügyeleti felületen, tegye közzé újra a portált , hogy éles környezetben is elérhetővé tegye a widgetet.

Feljegyzés

  • Ha egy későbbi időpontban telepíti a frissített widgetkódot, az éles környezetben használt widget nem frissül, amíg újra nem teszi közzé a fejlesztői portált.
  • A widget lefordított kódja egy adott portál változatához van társítva. Ha egy korábbi portálváltozatot aktuálissá tesz, a rendszer az adott változathoz társított egyéni widgetet használja.

Widgetsablonok

Sablonokat biztosítunk a widgethez használható alábbi technológiákhoz:

  • TypeScript (tiszta implementáció keretrendszer nélkül)
  • Reagálás
  • Vue

Minden sablon a TypeScript programozási nyelven alapul.

A React-sablon előkészített egyéni horgokat tartalmaz a hooks.ts fájlban, és létrehozott szolgáltatókat a környezet megosztásához az összetevőfán keresztül dedikált useSecrets, useValuesés useEditorValues horgokkal.

@azure/api-management-custom-widgets-tools A csomag használata

Ez az npm-csomag az alábbi funkciókat tartalmazza az egyéni widget fejlesztéséhez, és olyan funkciókat biztosít, mint a fejlesztői portál és a widget közötti kommunikáció:

Függvény Leírás
getValues A widgetszerkesztőben beállított értékeket tartalmazó JSON-objektumot ad vissza alapértelmezett értékekkel kombinálva
getEditorValues Olyan JSON-objektumot ad vissza, amely csak a widgetszerkesztőben beállított értékeket tartalmazza
buildOnChange TypeScript-típust fogad el, és visszaad egy függvényt a widget értékeinek frissítéséhez. A visszaadott függvény paraméterként egy frissített értékeket tartalmazó JSON-objektumot vesz fel, és nem ad vissza semmit.

Belsőleg használva a widgetszerkesztőben
askForSecrets JavaScript-ígéretet ad vissza, amely a felbontás után egy JSON-objektumot ad vissza, amely a háttérrendszerrel való kommunikációhoz szükséges.
deployNodeJs Widget üzembe helyezése a Blob Storage-ba
getWidgetData A fejlesztői portálról az egyéni widgetnek átadott összes adatot visszaadja

Belsőleg használva sablonokban

@azure/api-management-custom-widgets-tools/getValues

A vezérlőszerkesztőben beállított értékeket és alapértelmezett értékeket tartalmazó JSON-objektumot argumentumként átadott függvény.

Import {getValues} from "@azure/api-management-custom-widgets-tools/getValues" 
import {valuesDefault} from "./values" 
const values = getValues(valuesDefault)

A vezérlő futásidejű (app) részében használható.

@azure/api-management-custom-widgets-tools/getEditorValues

A függvény ugyanúgy működik, mint getValuesa szerkesztőben, de csak a szerkesztőben beállított értékeket adja vissza.

A vezérlő szerkesztőjében használható, de futtatókörnyezetben is használható.

@azure/api-management-custom-widgets-tools/buildOnChange

Feljegyzés

Ez a függvény csak a widgetszerkesztőben használható.

TypeScript-típust fogad el, és visszaad egy függvényt a widget értékeinek frissítéséhez. A visszaadott függvény paraméterként egy frissített értékeket tartalmazó JSON-objektumot vesz fel, és nem ad vissza semmit.

import {Values} from "./values"
const onChange = buildOnChange<Values>()
onChange({fieldKey: 'newValue'})

@azure/api-management-custom-widgets-tools/askForSecrets

Ez a függvény egy JavaScript-ígéretet ad vissza, amely a feloldás után egy JSON-objektumot ad vissza, amely a háttérrendszerrel való kommunikációhoz szükséges. token szükséges a hitelesítéshez. userId felhasználóspecifikus erőforrások lekérdezéséhez szükséges. Előfordulhat, hogy ezek az értékek nem lesznek meghatározva, ha egy névtelen felhasználó megtekinti a portált. Az Secrets objektum tartalmazza managementApiUrla portál háttérrendszerének URL-címét is, és apiVersiona fejlesztői portál által jelenleg használt apiVersion-t.

Figyelemfelhívás

Gondosan kezelje és használja a jogkivonatot. Bárki, aki rendelkezik vele, hozzáférhet az API Management szolgáltatás adataihoz.

@azure/api-management-custom-widgets-tools/deployNodeJs

Ez a függvény üzembe helyezi a widgetet a blobtárolóban. Minden sablonban előre konfigurálva van a deploy.js fájlban.

Alapértelmezés szerint három argumentumot fogad el:

  • serviceInformation – Az Azure-szolgáltatással kapcsolatos információk:

    • resourceId - Az API Management szolgáltatás erőforrás-azonosítója a következő formátumban: subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.ApiManagement/service/<api-management service-name>

    • managementApiEndpoint - Azure management API-végpont (a környezettől függ, általában management.azure.com)

  • A widget azonosítója – A widget neve "PC-barát" formátumban (latin alfanumerikus kisbetűk és kötőjelek; Contoso widget lesznek contoso-widget). A kulcs alatt name találhatópackage.json.

  • fallbackConfigPath – A helyi config.msapim.json fájl elérési útja, például: ./static/config.msapim.json

@azure/api-management-custom-widgets-tools/getWidgetData

Feljegyzés

Ezt a függvényt belsőleg használják a sablonokban. A legtöbb implementációban máskülönben nem szükséges.

Ez a függvény a fejlesztői portálról az egyéni widgetnek átadott összes adatot visszaadja. Olyan egyéb adatokat tartalmaz, amelyek hasznosak lehetnek a hibakeresésben vagy a speciálisabb helyzetekben. Ez az API várhatóan megváltozik a lehetséges kompatibilitástörő változásokkal. A következő kulcsokat tartalmazó JSON-objektumot ad vissza:

  • values - A szerkesztőben beállított összes érték, ugyanaz az objektum, amelyet a rendszer visszaad getEditorData
  • instanceId - A widget példányának azonosítója

Egyéni tulajdonságok hozzáadása vagy eltávolítása

Az egyéni tulajdonságok lehetővé teszik az egyéni widget kódjának értékeinek módosítását a fejlesztői portál felügyeleti felhasználói felületéről anélkül, hogy módosítaná a kódot, vagy újra üzembe helyezi az egyéni widgetet. Alapértelmezés szerint négy egyéni tulajdonság beviteli mezői vannak definiálva. Szükség szerint hozzáadhat vagy eltávolíthat más egyéni tulajdonságokat.

Figyelmeztetés

Ne tárolja a titkos vagy bizalmas értékeket az egyéni tulajdonságokban.

Egyéni tulajdonság hozzáadása:

  1. A fájlban src/values.tsadja hozzá a Values típushoz a menteni kívánt tulajdonság nevét és típusát.
  2. Ugyanabban a fájlban adjon hozzá egy alapértelmezett értéket.
  3. Navigáljon a fájlhoz vagy editor/index a editor.html fájlhoz (a pontos hely a kiválasztott keretrendszertől függ), és duplikáljon egy meglévő bemenetet, vagy adjon hozzá egyet.
  4. Győződjön meg arról, hogy a beviteli mező a módosított értéket a onChange függvényre jelenti, amelyből lekérheti a függvényt buildOnChange.

(Nem kötelező) Másik keretrendszer használata

Ha egy másik JavaScript felhasználói felületi keretrendszerrel és kódtárakkal szeretné implementálni a widgetet, a projektet az alábbi irányelvekkel kell beállítania:

  • A legtöbb esetben azt javasoljuk, hogy kezdje a TypeScript-sablonnal.
  • Telepítse a függőségeket, mint bármely más npm-projektben.
  • Ha a választott keretrendszer nem kompatibilis a Vite buildelési eszközével, konfigurálja úgy, hogy lefordított fájlokat állítson ki a ./dist mappába. Szükség esetén újradefiniálta a lefordított fájlok helyét úgy, hogy a függvény negyedik argumentumaként deployNodeJs relatív elérési utat ad meg.
  • Helyi fejlesztés esetén a config.msapim.json fájlnak elérhetőnek kell lennie az URL-címen localhost:<port>/config.msapim.json , amikor a kiszolgáló fut.

Egyéni widgetek létrehozása nyílt forráskód React Component Toolkit használatával

A nyílt forráskód React Component Toolkit npm-csomagszkripteket tartalmaz, amelyekkel a React-alkalmazásokat átalakíthatja az egyéni widget-keretrendszerre, tesztelheti és üzembe helyezheti az egyéni widgetet a fejlesztői portálon. Ha rendelkezik hozzáféréssel egy Azure OpenAI-szolgáltatáshoz, az eszközkészlet az Ön által megadott szöveges leírásból is létrehozhat widgetet.

Jelenleg az eszközkészletet kétféleképpen használhatja egyéni widgetek üzembe helyezéséhez:

  • Manuálisan, az eszközkészlet telepítésével és az npm-csomag szkriptjeinek helyi futtatásával. A szkripteket egymás után futtatva hozhat létre, tesztelhet és helyezhet üzembe egy React-összetevőt egyéni widgetként a fejlesztői portálon.
  • Azure Developer CLI-sablon (azd) használata a végpontok közötti üzembe helyezéshez. A azd sablon üzembe helyez egy Azure API Management-példányt és egy Azure OpenAI-példányt. Az erőforrások kiépítése után egy interaktív szkript segít egyéni widgetek létrehozásában, tesztelésében és üzembe helyezésében a fejlesztői portálon egy ön által megadott leírás alapján.

Feljegyzés

A React Component Toolkit és az Azure Developer CLI mintasablon nyílt forráskód projektek. A támogatás csak a gitHub-problémákon keresztül érhető el az adott adattárakban.

Kapcsolódó tartalom

További információ a fejlesztői portálról: