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

Cikk
03/29/2024

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

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.

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 üzemeltetési platformon, opcionálisan egy olyan megoldással, mint a CDN a nagyobb rendelkezésre állás és teljesítmény érdekében
Üzemeltetési infrastruktúra karbantartása és kezelése
Manuális frissítések, beleértve a biztonsági javításokat is, amelyek szükségessé tehetik a kódütközések feloldását a kódbázis frissítésekor

Feljegyzé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:

EGY API Management-szolgáltatáspéldány. Ha nincs ilyenje, olvassa el az Azure API Management-példány létrehozása című rövid útmutatót.
Egy Azure Storage-fiók, amelyen engedélyezve van a statikus webhelyek funkció . Lásd: Tárfiók létrehozása.
Git a gépén. Telepítse ezt a Git-oktatóanyagot követve.
Node.js (LTS-verzió vagy v10.15.0 újabb) és npm a számítógépen. Lásd: Node.js és npm letöltése és telepítése.
Azure parancssori felület (CLI). Kövesse az Azure CLI telepítési lépéseit.

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

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

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

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

Nyissa meg az adattár helyi példányát:
```
cd api-management-developer-portal
```
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>
```
Telepítse az elérhető npm-csomagokat:
```
npm install
```

Tipp.

Mindig a legújabb portálkiadást használja, és tartsa naprakészen az elágazott portált. A szoftvermérnökök napi fejlesztési célokra használják 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

A fejlesztői portálhoz az API Management REST API szükséges a tartalom kezeléséhez.

config.design.json fájl

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

{
  "environment": "development",
  "managementApiUrl": "https://<service-name>.management.azure-api.net",
  "managementApiAccessToken": "SharedAccessSignature ...",
  "backendUrl": "https://<service-name>.developer.azure-api.net",
  "useHipCaptcha": false,
  "integration": {
      "googleFonts": {
          "apiKey": "..."
      }
  }
}

A fájl konfigurálása:

Az értékben managementApiUrl cserélje le <service-name> az API Management-példány nevét. Ha egyéni tartományt konfigurált, használja helyette (példáulhttps://management.contoso.com).
```
{
...
"managementApiUrl": "https://contoso-api.management.azure-api.net"
...
```
Manuálisan hozzon létre egy SAS-jogkivonatot , hogy engedélyezze a közvetlen REST API-hozzáférést az API Management-példányhoz.
Másolja ki a létrehozott jogkivonatot, és illessze be értékként managementApiAccessToken .
Az értékben backendUrl cserélje le <service-name> az API Management-példány nevét. Ha egyéni tartományt konfigurált, használja helyette (példáulhttps://portal.contoso.com).
```
{
...
"backendUrl": "https://contoso-api.developer.azure-api.net"
...
```
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.
Ebben integrationa szakaszban googleFontsigény szerint állítsa be apiKey a Google API-kulcsot, 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.

Ha még nem rendelkezik kulccsal, konfigurálhat egyet a Google Cloud-konzollal. Tegye a következők egyikét:
1. Nyissa meg a Google Cloud-konzolt.
2. Ellenőrizze, hogy engedélyezve van-e a Webes betűtípusok fejlesztői API . Ha nem, engedélyezze.
3. Válassza a Hitelesítő adatok>létrehozása API-kulcs lehetőséget.
4. A megnyitott párbeszédpanelen másolja ki a létrehozott kulcsot, és illessze be a fájl értékeként apiKeyconfig.design.json .
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 a Mentés lehetőséget.

config.publish.json fájl

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

{
  "environment": "publishing",
  "managementApiUrl": "https://<service-name>.management.azure-api.net",
  "managementApiAccessToken": "SharedAccessSignature...",
  "useHipCaptcha": false
}

A fájl konfigurálása:

Másolja és illessze be az managementApiUrlmanagementApiAccessToken előző konfigurációs fájl értékeit.
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.

config.runtime.json fájl

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

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

A fájl konfigurálása:

Másolja és illessze be az managementApiUrl előző konfigurációs fájl értékét.
Az értékben backendUrl cserélje le <service-name> az API Management-példány nevét. Ha egyéni tartományt konfigurált, használja helyette (például). https://portal.contoso.com
```
{
...
"backendUrl": "https://contoso-api.developer.azure-api.net"
...
```

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:

Nyissa meg a tárfiókot az Azure Portalon, és válassza a statikus webhelyet a bal oldali menüből.
A Statikus webhely lapon válassza az Engedélyezve lehetőséget.
Az Index dokumentumnév mezőjébe írja be a index.html.
A Hiba dokumentum elérési útja mezőbe írja be a 404/index.html.
Válassza a Mentés lehetőséget.

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

Konfigurálja a tárfiók forrásközi erőforrás-megosztási (CORS) beállításait:

Nyissa meg a tárfiókot az Azure Portalon, és válassza a CORS elemet a bal oldali menüből.
A Blob szolgáltatás lapján konfigurálja a következő szabályokat:

Szabály Érték

Engedélyezett eredetek *

Engedélyezett metódusok Jelölje ki az összes HTTP-parancsot.

Engedélyezett fejlécek *

Közzétett fejlécek *

Maximális életkor 0
Válassza a Mentés lehetőséget.

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

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 (a portál konfigurációs fájljaiban backendUrl van beállítva) számos funkció engedélyezéséhez, például:

CAPTCHA-ellenőrzés
OAuth 2.0-engedélyezés a tesztkonzolon
Felhasználói hitelesítés és termék-előfizetés delegálása

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

Nyissa meg az API Management-példányt az Azure Portalon, és válassza a fejlesztői portál>portáljának beállításait a bal oldali menüből.
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://www.contoso.com
- localhosthelyi fejlesztéshez (ha van), például http://localhost:8080https://localhost:8080
Válassza a Mentés lehetőséget.

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.

Futtassa az alábbi parancsot:

npm start

Rövid idő elteltével 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. A projekt kódbázisának módosításai újraépítést váltanak ki, és frissítik 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
Tartalom létrehozása
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: Helyi közzététel

A portál adatai erős típusú objektumok formájából származnak. Az alábbi parancs statikus fájlokká alakítja őket, és a kimenetet a ./dist/website könyvtárba helyezi:

npm run publish

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 elérhetik őket:

Nyissa meg a Windows parancssorát, a PowerShellt vagy más parancshéjat.
Futtassa a következő Azure CLI-parancsot.

Cserélje le <account-connection-string> a tárfiók kapcsolati sztring. A tárfiók Hozzáférési kulcsok szakaszából szerezheti be.
```
az storage blob upload-batch --source dist/website \
    --destination '$web' \
    --connection-string <account-connection-string>
```

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

A webhelye mostantól az Azure Storage-tulajdonságokban (statikus webhelyek elsődleges végpontja) megadott gazdagépnév alatt él.

8. lépés: 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 a saját üzemeltetésű portálra mutasson. 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:

Feljegyzé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>

Az összes 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 az üzleti követelmények változhatnak. 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 rugalmas 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 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 egy 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. Lásd az oktatóanyagot: Az SAS URL-cím lekérésére vonatkozó utasításokért tekintse meg a Linux rendszerű virtuális gépek rendszer által hozzárendelt identitását az Azure Storage sas-hitelesítő adatokon keresztüli eléréséhez.

Tipp.

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.

Következő lépések

További információ az önkiszolgáló üzemeltetés alternatív megközelítéseiről

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

Előfeltételek

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

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

config.design.json fájl

config.publish.json fájl

config.runtime.json fájl

A statikus webhely konfigurálása

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

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

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

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

5. lépés: Helyi közzététel

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

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

8. lépés: Az API Management értesítési sablonjainak módosítása

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

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

Felhasználó meghívása

Új előfizetés aktiválva

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

Az összes sablon

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

Áttűnési folyamat

Következő lépések

További források