Az API Management fejlesztői portál önálló üzemeltetése

A KÖVETKEZŐKRE VONATKOZIK: Fejlesztő | Alapcsomag | Alapcsomag v2 | Standard | Standard v2 | Prémium | Prémium v2

Ez az oktatóanyag az API Management fejlesztői portáljának önkiszolgáló üzemeltetését ismerteti. Az önkiszolgáló üzemeltetés a fejlesztői portál funkcióinak bővítésére vonatkozó számos lehetőség egyike. Az API Management-példányhoz például több portált is üzemeltethet, különböző funkciókkal. Amikor önkiszolgáló portált üzemeltet, ön lesz a fenntartója, és ön felel a frissítéséért. A fejlesztői portálhoz az API Management REST API szükséges a tartalom kezeléséhez.

Fontos

Fontolja meg a fejlesztői portál önkiszolgáló üzemeltetését, ha módosítania kell a fejlesztői portál kódbázisának magját. Ez a beállítás speciális konfigurációt igényel, beleértve a következőket:

  • Üzembe helyezés egy üzemeltetési platformon, opcionálisan a nagyobb rendelkezésre állás és teljesítmény érdekében egy megoldás, például egy CDN (tartalomkézbesítési hálózat) alkalmazásával.
  • Az üzemeltetési infrastruktúra karbantartása és kezelése.
  • Manuális frissítések, beleértve a biztonsági javításokat is, amelyekhez szükség lehet a kódütközések feloldására a kódbázis frissítésekor.

Megjegyzés:

A saját üzemeltetésű portál nem támogatja a felügyelt fejlesztői portálon elérhető láthatósági és hozzáférési vezérlőket.

Ha már feltöltött vagy módosított médiafájlokat a felügyelt portálon, olvassa el a cikk későbbi, felügyeltről saját üzemeltetésűre történő áthelyezését ismertető cikket.

Előfeltételek

Helyi fejlesztési környezet beállításához a következőkre van szükség:

1. lépés: Helyi környezet beállítása

A helyi környezet beállításához klónozza az adattárat, váltson a fejlesztői portál legújabb kiadására, és telepítse az npm-csomagokat.

  1. Klónozza az api-management-developer-portal adattárat a GitHubról:

    git clone https://github.com/Azure/api-management-developer-portal.git

  2. Nyissa meg az adattár helyi példányát:

    cd api-management-developer-portal

  3. Tekintse meg a portál legújabb kiadását.

    A következő kód futtatása előtt ellenőrizze az adattár Kiadások szakaszában található aktuális kiadási címkét, és cserélje le <current-release-tag> az értéket a legújabb kiadási címkére.

    git checkout <current-release-tag>

  4. Telepítse az elérhető npm-csomagokat:

    npm install

Jótanács

Mindig a legújabb portálkiadást használja, és tartsa az elágazott portált up-tonaprakészen. Az API Management fejlesztői csapata napi fejlesztési célokra használja az master adattár ágát. A szoftver instabil verzióival rendelkezik.

2. lépés: JSON-fájlok, statikus webhely és CORS-beállítások konfigurálása

config.design.json fájl

Nyissa meg a src mappát, és nyissa meg a config.design.json fájlt.

{
    "environment": "development",
    "subscriptionId": "< subscription ID >",
    "resourceGroupName": "< resource group name >",
    "serviceName": "< API Management service name >"
}

A subscriptionId, resourceGroupName és serviceName mezőkbe írja be az API Management-példány előfizetésének, erőforráscsoportjának és szolgáltatásnevének értékeit. I

Választható beállítások a config.design.json

Igény szerint konfigurálja a következő beállításokat a config.design.json fájlban:

  1. Ha engedélyezni szeretné a CAPTCHA-t a fejlesztői portálon, állítsa be a következőt "useHipCaptcha": true: Konfigurálja a CORS-beállításokat a fejlesztői portál háttérrendszeréhez.

    {
    ...
    "useHipCaptcha": true
    ...
}

  2. Az integration menü alatt googleFonts a Google API-kulcsot opcionálisan állítsa be apiKey, amely lehetővé teszi a Webes betűtípusok fejlesztői API-hoz való hozzáférést. Ez a kulcs csak akkor szükséges, ha Google-betűtípusokat szeretne hozzáadni a fejlesztői portál szerkesztőjének Stílusok szakaszához.

    {
    ...
    "integration": {
        "googleFonts": {
            "apiKey": "< your Google API key >"
        }
    }
    ...
}

  3. Ha még nem rendelkezik kulccsal, konfigurálhat egyet a Google Cloud-konzollal. Kövesse az alábbi lépéseket:

    1. Nyissa meg a Google Cloud-konzolt.
    2. Ellenőrizze, hogy engedélyezve van-e a Webes betűtípusok fejlesztői API . Ha az nincs engedélyezve, engedélyezze.
    3. Válassza a Hitelesítő adatok> létrehozásaAPI-kulcs lehetőséget.
    4. A megnyitott párbeszédpanelen másolja ki a létrehozott kulcsot, és illessze be a apiKey fájlban a config.design.json értékeként.
    5. Válassza az API-kulcs szerkesztése lehetőséget a kulcsszerkesztő megnyitásához.
    6. A szerkesztőBEN az API-korlátozások alatt válassza a Kulcs korlátozása lehetőséget. A legördülő menüben válassza a Webes betűtípusok fejlesztői API-t.
    7. Válassza az Mentésgombot.

config.publish.json fájl

Nyissa meg a src mappát, és nyissa meg a config.publish.json fájlt.

{
    "environment": "publishing",
    "subscriptionId":"<service subscription>",
    "resourceGroupName":"<service resource group>",
    "serviceName":"<service name>"
}

Másolja és illessze be az subscriptionIdelőző konfigurációs fájlból származó , resourceGroupNameés serviceName értékeket.

config.runtime.json fájl

Nyissa meg a src mappát, és nyissa meg a config.runtime.json fájlt.

{
    "environment": "runtime",
    "backendUrl": "https://< service name >.developer.azure-api.net"
}

Cserélje ki a < service name >-t az előző konfigurációs fájlokban használt API Management példány nevére.

A statikus webhely konfigurálása

Konfigurálja a statikus webhely funkciót a tárfiókban az indexhez és a hibalapokhoz vezető útvonalak megadásával:

  1. Az Azure Portalon nyissa meg a tárfiókját.

  2. Az oldalsáv menüjében válassza az Adatkezelési>statikus webhely lehetőséget.

  3. A Statikus webhely lapon válassza az Engedélyezve lehetőséget.

  4. Az Index dokumentumnév mezőjébe írja be a index.html.

  5. A Hiba dokumentum elérési útja mezőben adja meg a 404/index.htmlértéket.

  6. Válassza az Mentésgombot.

Jegyezze fel az elsődleges végpont URL-címét. Később konfigurálja a saját üzemeltetésű portál eléréséhez.

A TÁRfiók CORS-beállításainak konfigurálása

A tárfiók forrásközi erőforrás-megosztási (CORS) beállításainak konfigurálása:

  1. Az Azure Portalon menjen a tárfiókjához.

  2. Az oldalsáv menü Beállítások területén válassza az Erőforrás-megosztás (CORS) lehetőséget.

  3. A Blob szolgáltatás lapján konfigurálja a következő szabályokat:

    Szabály Érték
    Engedélyezett források *
    Engedélyezett metódusok Jelölje ki az összes HTTP-parancsot.
    Engedélyezett fejlécek *
    Közzétett fejlécek *
    Maximális életkor 0

  4. Válassza az Mentésgombot.

CORS-beállítások konfigurálása a fejlesztői portál háttérrendszeréhez

Konfigurálja a CORS-beállításokat a fejlesztői portál háttérrendszeréhez, hogy engedélyezze a saját üzemeltetésű fejlesztői portálon keresztül érkező kéréseket. A saját üzemeltetésű fejlesztői portál a fejlesztői portál háttérbeli végpontjára támaszkodik (amely a portálfájlban backendUrlconfig.runtime.json van beállítva) számos funkció engedélyezéséhez, például:

CORS-beállítások hozzáadása:

  1. Nyissa meg az API Management-példányt az Azure Portalon.
  2. Az oldalsáv menüjében válassza a Fejlesztői portál>beállításai lehetőséget.
  3. A saját üzemeltetésű portál konfigurációs lapján adjon hozzá egy vagy több Origin tartományértéket. Például:
    • A tartomány, ahol a saját üzemeltetésű portált üzemeltetik, például https://contoso.developer.azure-api.net
    • localhosthelyi fejlesztéshez (ha van), például http://localhost:8080https://localhost:8080
  4. Válassza az Mentésgombot.

3. lépés: A portál futtatása

Most már létrehozhat és futtathat egy helyi portálpéldányt fejlesztési módban. Fejlesztési módban az összes optimalizálás ki van kapcsolva, és a forrástérképek be vannak kapcsolva.

  1. Futtassa a következő parancsot:

    npm run start

  2. A rendszer a böngészőn keresztüli hitelesítést kéri. A folytatáshoz válassza ki a Microsoft hitelesítő adatait.

  3. Egy idő után az alapértelmezett böngésző automatikusan megnyílik a helyi fejlesztői portál példányával. Az alapértelmezett cím, http://localhost:8080de a port változhat, ha 8080 már foglalt. Amikor módosítja a projekt kódbázisát, az újraépítést indít el, és frissíti a böngészőablakot.

4. lépés: Szerkesztés a vizualizációszerkesztőn keresztül

A vizualizációszerkesztő használatával hajtsa végre a következő feladatokat:

  • A portál testreszabása
  • Szerzői tartalom
  • A webhely struktúrájának rendszerezése
  • Megjelenésének stilizálása

Lásd : Oktatóanyag: A fejlesztői portál elérése és testreszabása. Ismerteti a felügyeleti felhasználói felület alapjait, és felsorolja az alapértelmezett tartalom javasolt módosításait. Mentse az összes módosítást a helyi környezetben, és zárja be a Ctrl+C billentyűkombinációt .

5. lépés: A portál helyi közzététele

  1. Futtassa a npm run publish programot. A rendszer a böngészőn keresztüli hitelesítést kéri. A folytatáshoz válassza ki a Microsoft hitelesítő adatait.

  2. Egy idő után a tartalom közzé lesz téve a dist/website mappában.

6. lépés: Statikus fájlok feltöltése blobba

Az Azure CLI használatával töltse fel a helyileg létrehozott statikus fájlokat egy blobba, és győződjön meg arról, hogy a látogatók hozzáférhetnek hozzájuk:

  1. Nyissa meg a Windows parancssorát, a PowerShellt vagy más parancshéjat.

  2. Futtassa a következő az storage blog upload-batch parancsot. Cserélje le <connection-string> a tárfiók kapcsolati sztringjével. A tárfiók Biztonsági és hálózati>hozzáférési kulcsok szakaszából szerezheti be.

    az storage blob upload-batch --source dist/website \
    --account-name <your-storage-account-name> \
    --destination '$web' \
    --connection-string "<connection-string>"

7. lépés: Ugrás a webhelyre

A webhelye mostantól elérhető az Azure Storage tulajdonságaiban megadott gazdagépnév alatt. Az oldalsáv menüjében lépjen az Adatkezelési>statikus webhelyre. A hosztnév az elsődleges végpont értéke.

A webhelyszerkesztő üzemeltetése

A webhelykód módosításakor előfordulhat, hogy frissítenie kell a webhelyszerkesztő kódját, és megfelelően támogatnia kell a módosított widgetek szerkesztését. Ebben az esetben a portál üzemeltetése mellett a szerkesztőalkalmazást is érdemes üzemeltetni. Ehhez el kell készítenie és konfigurálnia kell, hogy hozzáférhessen az API Management szolgáltatáshoz.

Ehhez szüksége lesz egy Microsoft Entra-azonosító alkalmazásra a bérlőben:

  1. Regisztráljon egy alkalmazást a Microsoft Entra ID-bérlőben. Jegyezze fel az alkalmazás (ügyfél) azonosítóját és a címtár (bérlő) azonosítóját. Ezeket egy későbbi lépésben konfigurálhatja.
  2. Konfiguráljon egy webes átirányítási URI-t (válasz URL-címet) az alkalmazásban, hogy a tervezőt futtató webalkalmazás végpontjára mutasson. Ez általában a blobtároló-alapú webhely helye. Példa: https://<your-storage-account-name>z13.web.core.windows.net/.
  3. Ha a portált folyamatokban (GitHub Actions) szeretné közzétenni, hozzon létre egy ügyfélkulcsot is ehhez az alkalmazáshoz. Jegyezze fel a létrehozott titkos kulcsot, és tárolja biztonságos helyen.

Ezután kövesse az alábbi lépéseket a webhelyszerkesztő üzemeltetéséhez:

  1. Adja hozzá a clientId és tenantId mezőket a config.design.json fájlhoz.

    {
    ...
    "clientId": "< Entra ID app ID >",
    "tenantId": "< Entra ID tenant ID >"
    ...
}

  2. Futtassa a npm run build-designer parancsot a tervező megépítéséhez.

  3. Nyissa meg a létrehozott /dist/designer mappát, amely a következő tartalommal rendelkező fájlt config.json tartalmazza:

    {
    "subscriptionId": "< subscription ID >",
    "resourceGroupName": "< resource group name >",
    "serviceName": "< API Management service name >",
    "clientId": "< Entra ID client ID >",
    "tenantId": "< Entra ID tenant ID >"
}

  4. Erősítse meg az Azure Resource Manager API-k használatával az API Management szolgáltatásához való csatlakozáshoz szükséges subscriptionId, resourceGroupName és serviceName konfigurációkat.

Portál közzététele csővezetékekben (GitHub Actions)

A saját üzemeltetésű portált közzéteheti egy folyamatban, például a GitHub Actionsben.

A csővezetékek használatával végzett közzététel végrehajtásához a folyamatnak Entra ID alkalmazás hitelesítő adataira is szüksége van. Használhatja ugyanazt az Entra-azonosító alkalmazást, amelyet az előző lépésekben leírt. A tenantId, clientIdés különösen clientSecret a megfelelő kulcstárolóban kell tartani. További részletekért lásd: Titkos kódok használata a GitHub Actionsben .

Példa a GitHub Actions-folyamat YAML-jára:


name: Portal-Publishing-Pipeline

on:
  pull_request:
    branches:
      - master

jobs:
  publish:
    runs-on: ubuntu-latest
    env:
      AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }}
      AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}
      AZURE_CLIENT_SECRET: ${{ secrets.AZURE_CLIENT_SECRET }}
    steps:
      - name: Checkout code
        uses: actions/checkout@v5

      - name: Set up Node.js
        uses: actions/setup-node@v5
        with:
          node-version: '20.x'

      - name: Install dependencies
        run: npm install

      - name: Run publish command
        run: npm run publish

AZ API Management értesítési sablonjainak módosítása

Cserélje le a fejlesztői portál URL-címét az API Management értesítési sablonjaiban, hogy az a saját üzemeltetésű portálra mutatjon. Lásd : Értesítések és e-mail-sablonok konfigurálása az Azure API Managementben.

Végezze el különösen az alábbi módosításokat az alapértelmezett sablonokon:

Megjegyzés:

A következő frissített szakaszok értékei feltételezik, hogy a portált a következő helyen üzemelteti https://portal.contoso.com/: .

E-mail-módosítás megerősítése

Frissítse a fejlesztői portál URL-címét az e-mail-módosítást megerősítő értesítési sablonban:

Eredeti tartalom

<a id="confirmUrl" href="$ConfirmUrl" style="text-decoration:none">
  <strong>$ConfirmUrl</strong></a>

frissített

<a id="confirmUrl" href="https://portal.contoso.com/signup?$ConfirmQuery" style="text-decoration:none">
  <strong>https://portal.contoso.com/signup?$ConfirmQuery</strong></a>

Új fejlesztői fiók megerősítése

Frissítse a fejlesztői portál URL-címét az Új fejlesztői fiók megerősítő értesítési sablonjában:

Eredeti tartalom

<a id="confirmUrl" href="$ConfirmUrl" style="text-decoration:none">
  <strong>$ConfirmUrl</strong></a>

frissített

<a id="confirmUrl" href="https://portal.contoso.com/signup?$ConfirmQuery" style="text-decoration:none">
  <strong>https://portal.contoso.com/signup?$ConfirmQuery</strong></a>

Felhasználó meghívása

Frissítse a fejlesztői portál URL-címét a Felhasználói értesítés meghívása sablonban:

Eredeti tartalom

<a href="$ConfirmUrl">$ConfirmUrl</a>

frissített

<a href="https://portal.contoso.com/confirm-v2/identities/basic/invite?$ConfirmQuery">https://portal.contoso.com/confirm-v2/identities/basic/invite?$ConfirmQuery</a>

Új előfizetés aktiválva

Frissítse a fejlesztői portál URL-címét az Új előfizetés által aktivált értesítési sablonban:

Eredeti tartalom

Thank you for subscribing to the <a href="http://$DevPortalUrl/products/$ProdId"><strong>$ProdName</strong></a> and welcome to the $OrganizationName developer community. We are delighted to have you as part of the team and are looking forward to the amazing applications you will build using our API!

frissített

Thank you for subscribing to the <a href="https://portal.contoso.com/product#product=$ProdId"><strong>$ProdName</strong></a> and welcome to the $OrganizationName developer community. We are delighted to have you as part of the team and are looking forward to the amazing applications you will build using our API!

Eredeti tartalom

Visit the developer <a href="http://$DevPortalUrl/developer">profile area</a> to manage your subscription and subscription keys

frissített

Visit the developer <a href="https://portal.contoso.com/profile">profile area</a> to manage your subscription and subscription keys

Eredeti tartalom

<a href="http://$DevPortalUrl/docs/services?product=$ProdId">Learn about the API</a>

frissített

<a href="https://portal.contoso.com/product#product=$ProdId">Learn about the API</a>

Eredeti tartalom

<p style="font-size:12pt;font-family:'Segoe UI'">
  <strong>
    <a href="http://$DevPortalUrl/applications">Feature your app in the app gallery</a>
  </strong>
</p>
<p style="font-size:12pt;font-family:'Segoe UI'">You can publish your application on our gallery for increased visibility to potential new users.</p>
<p style="font-size:12pt;font-family:'Segoe UI'">
  <strong>
    <a href="http://$DevPortalUrl/issues">Stay in touch</a>
  </strong>
</p>
<p style="font-size:12pt;font-family:'Segoe UI'">
      If you have an issue, a question, a suggestion, a request, or if you just want to tell us something, go to the <a href="http://$DevPortalUrl/issues">Issues</a> page on the developer portal and create a new topic.
</p>

frissített

<!--Remove the entire block of HTML code above.-->

Jelszómódosítás megerősítése

Frissítse a fejlesztői portál URL-címét a Jelszómódosítás megerősítését megerősítő értesítési sablonban:

Eredeti tartalom

<a href="$DevPortalUrl">$DevPortalUrl</a>

frissített

<a href="https://portal.contoso.com/confirm-password?$ConfirmQuery">https://portal.contoso.com/confirm-password?$ConfirmQuery</a>

Minden sablon

Frissítse a fejlesztői portál URL-címét minden olyan sablonban, amely az élőlábban található hivatkozással rendelkezik:

Eredeti tartalom

<a href="$DevPortalUrl">$DevPortalUrl</a>

frissített

<a href="https://portal.contoso.com/">https://portal.contoso.com/</a>

Váltás felügyeltről saját üzemeltetésű fejlesztői portálra

Idővel előfordulhat, hogy az üzleti követelmények megváltoznak. Előfordulhat, hogy az API Management fejlesztői portál felügyelt verziója már nem felel meg az igényeinek. Egy új követelmény például arra kényszerítheti, hogy egy külső adatszolgáltatóval integrálható egyéni widgetet hozzon létre. A felügyelt verziótól eltérően a portál saját üzemeltetésű verziója teljes rugalmasságot és bővíthetőséget biztosít.

Áttűnési folyamat

A felügyelt verzióról áttérhet egy saját üzemeltetésű verzióra ugyanazon AZ API Management szolgáltatáspéldányon belül. A folyamat megőrzi a portál felügyelt verziójában végrehajtott módosításokat. Győződjön meg arról, hogy előzetesen biztonsági másolatot készít a portál tartalmáról. A biztonsági mentési szkriptet az scripts.v3 API Management fejlesztői portál GitHub-adattár mappájában találja.

A konvertálási folyamat szinte teljesen megegyezik egy általános, saját üzemeltetésű portál beállításával, ahogyan az ebben a cikkben ismertetett korábbi lépésekben is látható. A konfigurációs lépésben egyetlen kivétel van. A fájlban lévő config.design.json tárfióknak meg kell egyeznie a portál felügyelt verziójának tárfiókával. Kérjük, tekintse meg a Linux VM rendszer által hozzárendelt identitás használata az Azure Storage SAS-hitelesítő adatokon keresztüli eléréshez oktatóanyagot, hogy megtudja, hogyan kérheti le a SAS URL-címet.

Jótanács

Javasoljuk, hogy használjon külön tárfiókot a config.publish.json fájlban. Ez a megközelítés nagyobb ellenőrzést biztosít, és leegyszerűsíti a portál üzemeltetési szolgáltatásának kezelését.

Kapcsolódó tartalom

  • Last updated on