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

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. Portál pro vývojáře vyžaduje rozhraní REST API služby API management pro správu obsahu.

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 hostingovou platformu, volitelně s řešením, jako je síť pro doručování obsahu (CDN), pro zvýšení 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.

Pokud jste instanci vytvořili na úrovni služby v2, nejprve povolte portál pro vývojáře.
1. V nabídce bočního panelu v části Portál pro vývojáře vyberte nastavení portálu.
2. V okně nastavení portálu vyberte Povoleno. Vyberte Uložit. Povolení portálu pro vývojáře může trvat několik minut.
Účet služby Azure Blob Storage, který použijete k povolení funkce 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 dlouhodobé podpory (LTS) v10.15.0 nebo novější) a npm na vašem počítači. Viz Stažení a instalace Node.js a npm.
Azure CLI. Postupujte podle kroků instalace Azure CLI.
Oprávnění k vytvoření registrace aplikace Microsoft Entra

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

Pokud chcete nastavit místní prostředí, naklonujte úložiště, přepněte na nejnovější verzi portálu pro vývojáře a nainstalujte 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
```

Návod

Vždy používejte nejnovější verzi portálu a uchovávejte forkovaný portál up-to-date. Vývojový tým služby API Management používá 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

config.design.json soubor

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

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

Do subscriptionId, resourceGroupName a serviceName zadejte hodnoty pro předplatné, skupinu prostředků a název služby vaší instance API Management. I

Volitelná nastavení v config.design.json

Volitelně můžete v config.design.json souboru nakonfigurovat následující nastavení:

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.
```
{
    ...
    "useHipCaptcha": true
    ...
}
```
V integration části, v části googleFonts, volitelně nastavte apiKey na hodnotu klíče 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.
```
{
    ...
    "integration": {
        "googleFonts": {
            "apiKey": "< your Google API key >"
        }
    }
    ...
}
```
Pokud ještě klíč nemáte, můžete ho nakonfigurovat pomocí konzoly Google Cloud. Postupujte takto:
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 možnost Vytvořit přihlašovací údaje>klíč rozhraní API.
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. Vyberte Uložit.

config.publish.json soubor

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

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

Zkopírujte a vložte hodnoty subscriptionId, resourceGroupName a serviceName z předchozího konfiguračního souboru.

config.runtime.json soubor

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

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

Nahraďte < service name > názvem vaší instance služby API Management použitou v předchozích konfiguračních souborech.

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:

V Azure portálu přejděte ke svému účtu úložiště.
V nabídce bočního panelu vyberte Správa dat>Statický web.
Na stránce Statický web vyberte Povoleno.
Do pole Název dokumentu rejstříku zadejte index.html.
Do pole Cesta dokumentu chyby zadejte 404/index.html.
Vyberte Uložit.

Poznamenejte si adresu URL primárního koncového bodu . Později ho nakonfigurujete pro přístup k místnímu portálu.

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

Chcete-li konfigurovat nastavení sdílení prostředků mezi různými zdroji (CORS) pro váš účet úložiště:

Přejděte ke svému účtu úložiště na webu Azure Portal.
V nabídce bočního panelu v části Nastavení vyberte Sdílení prostředků (CORS).
Na kartě Blob Service nakonfigurujte následující pravidla:

Pravidlo Hodnota

Povolené původy *

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

Povolené hlavičky *

Zveřejněné hlavičky *

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

Pravidlo	Hodnota
Povolené původy	*
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 souboru portálu config.runtime.json ) 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.
V nabídce bočního panelu vyberteNastavení> Pro vývojáře.
Na kartě Konfigurace místního portálu přidejte jednu nebo více hodnot domény Origin . Například:
- Doména, kde je hostovaný místní portál, například https://contoso.developer.azure-api.net
- localhost pro místní rozvoj (pokud je to možné), například http://localhost:8080 nebo https://localhost:8080
Vyberte 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 run start
```
Zobrazí se výzva k ověření v prohlížeči. Pokračujte výběrem svých přihlašovacích údajů Microsoftu.
Po nějaké době se výchozí prohlížeč automaticky otevře s vaší 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ý. Když provedete změny základu kódu projektu, aktivuje opětovné sestavení a aktualizuje 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
Autorský obsah
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í portálu

Spusťte npm run publish. Zobrazí se výzva k ověření v prohlížeči. Pokračujte výběrem svých přihlašovacích údajů Microsoftu.
Po nějaké době se obsah publikuje do dist/website složky.

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í az storage blog upload-batch příkaz. Nahraďte <connection-string> připojovacím řetězcem vašeho účtu úložiště. Můžete ho získat v části Zabezpečení a síťové přístupové>klíče vašeho účtu úložiště.
```
az storage blob upload-batch --source dist/website \
    --account-name <your-storage-account-name> \
    --destination '$web' \
    --connection-string "<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. V nabídce bočního panelu přejděte na Správa dat>statický web. Název hostitele je hodnota primárního koncového bodu.

Hostování editoru webů

Při provádění změn v kódu webu možná budete muset aktualizovat kód editoru webů, aby bylo možné správně podporovat úpravy upravených widgetů. V takovém případě můžete kromě hostování portálu také chtít hostovat aplikaci editoru. K tomu je potřeba ho sestavit a nakonfigurovat pro přístup ke službě API Management.

K tomu potřebujete ve svém tenantovi aplikaci Microsoft Entra ID:

Zaregistrujte aplikaci v tenantovi Microsoft Entra ID. Poznamenejte si ID aplikace (klienta) a ID adresáře (tenanta). Nakonfigurujete je v pozdějším kroku.
Nakonfigurujte identifikátor URI přesměrování webu (adresa URL odpovědi) v této aplikaci tak, aby odkazoval na koncový bod webové aplikace, kde je návrhář hostován. Obvykle se jedná o umístění webu založeného na úložišti Blob. Příklad: https://<your-storage-account-name>z13.web.core.windows.net/.
Pokud chcete portál publikovat v kanálech (GitHub Actions), vytvořte pro tuto aplikaci také tajný klíč klienta. Poznamenejte si vygenerovanou hodnotu tajného kódu a uložte ji do bezpečného umístění.

Pak pomocí následujícího postupu hostujte editor webu:

Přidejte clientId a tenantId pole do souboru config.design.json.

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

Spuštěním npm run build-designer příkazu sestavte návrháře.

Přejděte do vygenerované /dist/designer složky, která obsahuje soubor config.json s následujícím obsahem:

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

Potvrďte konfiguraci subscriptionId, resourceGroupName a serviceName, které jsou potřebné pro připojení ke službě API Management pomocí rozhraní API Azure Resource Manager.

Publikování portálu v pipelinech (GitHub Actions)

Portál s vlastním hostováním můžete publikovat v procesu, jako je GitHub Actions.

Pipeline také potřebuje přihlašovací údaje aplikace Entra ID ke spuštění publikování pomocí pipeline. Můžete použít stejnou aplikaci Entra ID popsanou v předchozích krocích. , tenantIdclientIda zejména clientSecret musí být uložen v příslušném úložišti klíčů. Další podrobnosti najdete v tématu Používání tajných kódů v GitHub Actions .

Příklad kanálu GitHub Actions YAML:


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

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 odkazovala na váš samostatně hostovaný 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>

aktualizované

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

aktualizované

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

aktualizované

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

aktualizované

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

aktualizované

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>

aktualizované

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

aktualizované

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

aktualizované

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

aktualizované

<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 spravované verze nabízí verze portálu v místním prostředí 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.v3 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 je 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.

Návod

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

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

Váš názor

Byla tato stránka užitečná?

Last updated on 2025-10-30

Sdílet prostřednictvím

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

Volitelná nastavení v config.design.json

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í portálu

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

Krok 7: Přechod na web

Hostování editoru webů

Publikování portálu v pipelinech (GitHub Actions)

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

Související obsah

Váš názor

Další materiály