Samoobslužné hostování portálu pro vývojáře služby API Management

Článek
03/29/2024

PLATÍ PRO: Vývojář | Základní | Standardní | Premium

Tento kurz popisuje, jak samostatně hostovat portál pro vývojáře služby API Management. Samoobslužné hostování je jednou z několika možností rozšíření funkcí portálu pro vývojáře. Můžete například hostovat několik portálů pro instanci služby API Management s různými funkcemi. Když sami hostujete portál, stanete se jeho správcem a zodpovídáte za jeho upgrady.

Důležité

Zvažte možnost vlastního hostování portálu pro vývojáře pouze v případě, že potřebujete upravit jádro základu kódu portálu pro vývojáře. Tato možnost vyžaduje pokročilou konfiguraci, včetně:

Nasazení na hostující platformu, volitelně předsunutá řešením, jako je CDN pro zajištění vyšší dostupnosti a výkonu
Údržba a správa hostitelské infrastruktury
Ruční aktualizace, včetně oprav zabezpečení, které můžou vyžadovat řešení konfliktů kódu při upgradu základu kódu

Poznámka:

Portál v místním prostředí nepodporuje viditelnost a řízení přístupu, které jsou k dispozici na spravovaném portálu pro vývojáře.

Pokud jste už na spravovaném portálu nahráli nebo upravili multimediální soubory, přečtěte si část Přechod ze spravovaného do místního prostředí dále v tomto článku.

Požadavky

Pokud chcete nastavit místní vývojové prostředí, musíte mít:

Instance služby API Management. Pokud ho nemáte, přečtěte si článek Rychlý start – Vytvoření instance služby Azure API Management.
Účet úložiště Azure s povolenou funkcí statických webů. Viz Vytvoření účtu úložiště.
Git na vašem počítači. Nainstalujte ho podle tohoto kurzu Gitu.
Node.js (verze v10.15.0 LTS nebo novější) a npm na vašem počítači. Viz Stažení a instalace Node.js a npm.
Rozhraní příkazového řádku Azure. Postupujte podle kroků instalace Azure CLI.

Krok 1: Nastavení místního prostředí

Pokud chcete nastavit místní prostředí, budete muset naklonovat úložiště, přepnout na nejnovější verzi portálu pro vývojáře a nainstalovat balíčky npm.

Naklonujte úložiště api-management-developer-portal z GitHubu:

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

Přejděte do místní kopie úložiště:
```
cd api-management-developer-portal
```
Podívejte se na nejnovější verzi portálu.

Před spuštěním následujícího kódu zkontrolujte aktuální značku vydané verze v části Vydané verze úložiště a nahraďte <current-release-tag> hodnotu značkou nejnovější verze.
```
git checkout <current-release-tag>
```
Nainstalujte všechny dostupné balíčky npm:
```
npm install
```

Tip

Vždy používejte nejnovější verzi portálu a udržujte forkovaný portál aktuální. Softwaroví inženýři používají master větev tohoto úložiště pro každodenní účely vývoje. Má nestabilní verze softwaru.

Krok 2: Konfigurace souborů JSON, statického webu a nastavení CORS

Portál pro vývojáře vyžaduje, aby rozhraní REST API služby API management spravuje obsah.

config.design.json soubor

Přejděte do src složky a otevřete config.design.json soubor.

{
  "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": "..."
      }
  }
}

Nakonfigurujte soubor:

V hodnotě managementApiUrl nahraďte <service-name> názvem vaší instance služby API Management. Pokud jste nakonfigurovali vlastní doménu, použijte ji (například https://management.contoso.com).
```
{
...
"managementApiUrl": "https://contoso-api.management.azure-api.net"
...
```
Ručním vytvořením tokenu SAS povolte přímý přístup rozhraní REST API k vaší instanci služby API Management.
Zkopírujte vygenerovaný token a vložte ho managementApiAccessToken jako hodnotu.
V hodnotě backendUrl nahraďte <service-name> názvem vaší instance služby API Management. Pokud jste nakonfigurovali vlastní doménu, použijte ji (například https://portal.contoso.com).
```
{
...
"backendUrl": "https://contoso-api.developer.azure-api.net"
...
```
Pokud chcete povolit CAPTCHA na portálu pro vývojáře, nastavte "useHipCaptcha": true. Nezapomeňte nakonfigurovat nastavení CORS pro back-end portálu pro vývojáře.
V integrationčásti , v části googleFontsvolitelné nastavit apiKey na klíč rozhraní Google API, který umožňuje přístup k rozhraní WEB Fonts Developer API. Tento klíč je potřeba jenom v případě, že chcete přidat písma Google v části Styly editoru portálu pro vývojáře.

Pokud ještě klíč nemáte, můžete ho nakonfigurovat pomocí konzoly Google Cloud. Postupujte následovně:
1. Otevřete konzolu Google Cloud.
2. Zkontrolujte, jestli je povolené rozhraní API pro vývojáře webových písem. Pokud není, povolte ho.
3. Vyberte Vytvořit klíč rozhraní API pro přihlašovací údaje>.
4. V otevřeném dialogovém okně zkopírujte vygenerovaný klíč a vložte ho apiKey jako hodnotu v config.design.json souboru.
5. Výběrem možnosti Upravit klíč rozhraní API otevřete editor klíčů.
6. V editoru v části Omezení rozhraní API vyberte Omezit klíč. V rozevíracím seznamu vyberte rozhraní API pro vývojáře webových písem.
7. Zvolte Uložit.

config.publish.json soubor

Přejděte do src složky a otevřete config.publish.json soubor.

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

Nakonfigurujte soubor:

Zkopírujte a vložte managementApiUrl hodnoty managementApiAccessToken z předchozího konfiguračního souboru.
Pokud chcete povolit CAPTCHA na portálu pro vývojáře, nastavte "useHipCaptcha": true. Nezapomeňte nakonfigurovat nastavení CORS pro back-end portálu pro vývojáře.

config.runtime.json soubor

Přejděte do src složky a otevřete config.runtime.json soubor.

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

Nakonfigurujte soubor:

Zkopírujte a vložte managementApiUrl hodnotu z předchozího konfiguračního souboru.
V hodnotě backendUrl nahraďte <service-name> názvem vaší instance služby API Management. Pokud jste nakonfigurovali vlastní doménu, použijte ji (například). https://portal.contoso.com
```
{
...
"backendUrl": "https://contoso-api.developer.azure-api.net"
...
```

Konfigurace statického webu

Nakonfigurujte funkci statického webu v účtu úložiště tím, že poskytnete trasy na indexové a chybové stránky:

Na webu Azure Portal přejděte ke svému účtu úložiště a v nabídce vlevo vyberte Statický web .
Na stránce Statický web vyberte Povoleno.
Do pole Název dokumentu rejstříku zadejte index.html.
Do pole Cesta k dokumentu chyba zadejte 404/index.html.
Zvolte Uložit.

Konfigurace nastavení CORS pro účet úložiště

Nakonfigurujte nastavení sdílení prostředků mezi zdroji (CORS) pro účet úložiště:

Na webu Azure Portal přejděte ke svému účtu úložiště a v nabídce vlevo vyberte CORS .
Na kartě Blob Service nakonfigurujte následující pravidla:

Pravidlo Hodnota

Povolené zdroje *

Povolené metody Vyberte všechny příkazy HTTP.

Povolené hlavičky *

Zveřejněné hlavičky *

Maximální věk 0
Zvolte Uložit.

Pravidlo	Hodnota
Povolené zdroje	*
Povolené metody	Vyberte všechny příkazy HTTP.
Povolené hlavičky	*
Zveřejněné hlavičky	*
Maximální věk	0

Konfigurace nastavení CORS pro back-end vývojářského portálu

Nakonfigurujte nastavení CORS pro back-end portálu pro vývojáře, abyste povolili požadavky pocházející z místního portálu pro vývojáře. Portál pro vývojáře v místním prostředí spoléhá na back-endový koncový bod portálu pro vývojáře (nastavený v backendUrl konfiguračních souborech portálu) a umožňuje několik funkcí, mezi které patří:

Ověření CAPTCHA
Autorizace OAuth 2.0 v testovací konzole
Delegování ověřování uživatelů a předplatného produktu

Přidání nastavení CORS:

Na webu Azure Portal přejděte do instance služby API Management a v nabídce na levé straně vyberte Nastavení portálu>pro vývojáře.
Na kartě Konfigurace místního portálu přidejte jednu nebo více hodnot domény Origin. Příklad:
- Doména, kde je hostovaný místní portál, například https://www.contoso.com
- localhost pro místní rozvoj (pokud je to možné), například http://localhost:8080 nebo https://localhost:8080
Zvolte Uložit.

Krok 3: Spuštění portálu

Teď můžete sestavit a spustit instanci místního portálu v režimu vývoje. Ve vývojovém režimu jsou všechny optimalizace vypnuté a zdrojové mapy jsou zapnuté.

Spusťte následující příkaz:

npm start

Po krátké době se výchozí prohlížeč automaticky otevře s místní instancí portálu pro vývojáře. Výchozí adresa je http://localhost:8080, ale port se může změnit, pokud 8080 už je obsazený. Všechny změny základu kódu projektu aktivují opětovné sestavení a aktualizují okno prohlížeče.

Krok 4: Úprava pomocí vizuálního editoru

Pomocí vizuálního editoru můžete provádět tyto úlohy:

Přizpůsobení portálu
Vytváření obsahu
Uspořádání struktury webu
Stylizace vzhledu

Viz kurz: Přístup k portálu pro vývojáře a jeho přizpůsobení. Popisuje základy uživatelského rozhraní pro správu a uvádí doporučené změny výchozího obsahu. Uložte všechny změny v místním prostředí a stisknutím kombinace kláves Ctrl+C ho zavřete.

Krok 5: Místní publikování

Data portálu pocházejí z podobě objektů se silnými typy. Následující příkaz je přeloží do statických souborů a umístí výstup do ./dist/website adresáře:

npm run publish

Krok 6: Nahrání statických souborů do objektu blob

Pomocí Azure CLI nahrajte místně generované statické soubory do objektu blob a ujistěte se, že se k nim návštěvníci dostanou:

Otevřete příkazový řádek Windows, PowerShell nebo jiné příkazové prostředí.
Spusťte následující příkaz Azure CLI.

Nahraďte <account-connection-string> připojovací řetězec vašeho účtu úložiště. Můžete ho získat v části Přístupové klíče vašeho účtu úložiště.
```
az storage blob upload-batch --source dist/website \
    --destination '$web' \
    --connection-string <account-connection-string>
```

Krok 7: Přechod na web

Váš web je teď aktivní pod názvem hostitele zadaným ve vlastnostech služby Azure Storage (primární koncový bod na statických webech).

Krok 8: Změna šablon oznámení služby API Management

Nahraďte adresu URL portálu pro vývojáře v šablonách oznámení služby API Management tak, aby odkazovat na váš místní portál. Viz Postup konfigurace oznámení a e-mailových šablon ve službě Azure API Management.

Zejména proveďte následující změny výchozích šablon:

Poznámka:

Hodnoty v následujících aktualizovaných částech předpokládají, že hostujete portál na adrese https://portal.contoso.com/.

Potvrzení změny e-mailu

Aktualizujte adresu URL portálu pro vývojáře v šabloně oznámení o potvrzení změny e-mailu:

Původní obsah

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

Aktualizováno

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

Potvrzení nového vývojářského účtu

Aktualizujte adresu URL portálu pro vývojáře v šabloně oznámení o potvrzení nového účtu pro vývojáře:

Původní obsah

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

Aktualizováno

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

Pozvat uživatele

Aktualizujte adresu URL portálu pro vývojáře v šabloně oznámení pozvat uživatele :

Původní obsah

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

Aktualizováno

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

Aktivované nové předplatné

Aktualizujte adresu URL portálu pro vývojáře v šabloně oznámení aktivované novým předplatným :

Původní obsah

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!

Aktualizováno

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!

Původní obsah

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

Aktualizováno

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

Původní obsah

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

Aktualizováno

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

Původní obsah

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

Aktualizováno

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

Potvrzení změny hesla

Aktualizujte adresu URL portálu pro vývojáře v šabloně oznámení o potvrzení změny hesla:

Původní obsah

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

Aktualizováno

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

Všechny šablony

Aktualizujte adresu URL portálu pro vývojáře v libovolné šabloně, která obsahuje odkaz v zápatí:

Původní obsah

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

Aktualizováno

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

Přechod ze spravovaného na portál pro vývojáře v místním prostředí

V průběhu času se můžou vaše obchodní požadavky změnit. Můžete skončit v situaci, kdy spravovaná verze portálu pro vývojáře služby API Management už nevyhovuje vašim potřebám. Nový požadavek může například vynutit vytvoření vlastního widgetu, který se integruje s poskytovatelem dat třetí strany. Na rozdíl od mangované verze nabízí samoobslužná verze portálu plnou flexibilitu a rozšiřitelnost.

Proces přechodu

Ze spravované verze můžete přejít na místní verzi ve stejné instanci služby API Management. Tento proces zachovává změny, které jste provedli ve spravované verzi portálu. Ujistěte se, že předem zálohujete obsah portálu. Záložní skript najdete ve scripts složce úložiště GitHub na portálu pro vývojáře služby API Management.

Proces převodu je téměř stejný jako nastavení obecného samoobslužného portálu, jak je znázorněno v předchozích krocích tohoto článku. V kroku konfigurace existuje jedna výjimka. Účet úložiště v config.design.json souboru musí být stejný jako účet úložiště spravované verze portálu. Viz kurz: Použití identity přiřazené systémem na virtuálním počítači s Linuxem pro přístup ke službě Azure Storage prostřednictvím přihlašovacích údajů SAS, kde najdete pokyny k načtení adresy URL SAS.

Tip

V souboru doporučujeme použít samostatný účet config.publish.json úložiště. Tento přístup vám dává větší kontrolu a zjednodušuje správu hostitelské služby vašeho portálu.

Další kroky

Další informace o alternativních přístupech k vlastnímu hostování

Samoobslužné hostování portálu pro vývojáře služby API Management

Požadavky

Krok 1: Nastavení místního prostředí

Krok 2: Konfigurace souborů JSON, statického webu a nastavení CORS

config.design.json soubor

config.publish.json soubor

config.runtime.json soubor

Konfigurace statického webu

Konfigurace nastavení CORS pro účet úložiště

Konfigurace nastavení CORS pro back-end vývojářského portálu

Krok 3: Spuštění portálu

Krok 4: Úprava pomocí vizuálního editoru

Krok 5: Místní publikování

Krok 6: Nahrání statických souborů do objektu blob

Krok 7: Přechod na web

Krok 8: Změna šablon oznámení služby API Management

Potvrzení změny e-mailu

Potvrzení nového vývojářského účtu

Pozvat uživatele

Aktivované nové předplatné

Potvrzení změny hesla

Všechny šablony

Přechod ze spravovaného na portál pro vývojáře v místním prostředí

Proces přechodu

Další kroky

Další materiály