De API Management-ontwikkelaarsportal zelf hosten

VAN TOEPASSING OP: Ontwikkelaar | Basic | Basic v2 | Standaard | Standard v2 | Premium | Premium v2

In deze zelfstudie wordt beschreven hoe u de API Management-ontwikkelaarsportal zelf host. Selfhosting is een van de verschillende opties om de functionaliteit van de ontwikkelaarsportal uit te breiden. U kunt bijvoorbeeld meerdere portals voor uw API Management-exemplaar zelf hosten, met verschillende functies. Wanneer u een portal zelf host, wordt u de onderhouder en bent u verantwoordelijk voor de upgrades. Voor de ontwikkelaarsportal is de REST API van API Management vereist om de inhoud te beheren.

Als u al mediabestanden hebt geüpload of gewijzigd in de beheerde portal, raadpleegt u Overstappen van beheerd naar zelf-hostend, verderop in dit artikel.

Vereiste voorwaarden

Als u een lokale ontwikkelomgeving wilt instellen, hebt u het volgende nodig:

• Een API Management-service-exemplaar. Als u nog geen exemplaar hebt, raadpleegt u quickstart: een Azure API Management-exemplaar maken.

  Als u uw exemplaar in een v2-servicelaag hebt gemaakt, schakelt u eerst de ontwikkelaarsportal in.

  1. Selecteer portalinstellingen in het zijbalkmenu onder Ontwikkelaarsportal.
  2. Selecteer Ingeschakeld in het venster Portalinstellingen. Selecteer Opslaan. Het kan enkele minuten duren voordat de ontwikkelaarsportal is ingeschakeld.

• Een Azure Blob Storage-account dat u gebruikt om de functie statische websites in te schakelen. Zie Een opslagaccount maken.

• Git op uw computer. Installeer deze door deze Git-zelfstudie te volgen.

• Node.js (LTS-versie v10.15.0 (Long Term Support) of hoger) en npm op uw computer. Zie Node.js en npm downloaden en installeren.

• Azure CLI. Volg de azure CLI-installatiestappen.

• Machtigingen voor het maken van een Microsoft Entra-app-registratie.

Stap 1: lokale omgeving instellen

Als u uw lokale omgeving wilt instellen, kloont u de opslagplaats, schakelt u over naar de nieuwste versie van de ontwikkelaarsportal en installeert u npm-pakketten.

1. Kloon de opslagplaats api-management-developer-portal vanuit GitHub:

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

2. Ga naar je lokale kopie van de repository.

   cd api-management-developer-portal
   

3. Bekijk de nieuwste versie van de portal.

   Voordat u de volgende code uitvoert, controleert u de huidige releasetag in de sectie Releases van de opslagplaats en vervangt u de waarde door <current-release-tag> de meest recente releasetag.

   git checkout <current-release-tag>
   

4. Installeer alle beschikbare npm-pakketten:

   npm install
   

Stap 2: JSON-bestanden, statische website en CORS-instellingen configureren

config.design.json-bestand

Ga naar de src map en open het config.design.json bestand.

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

Voer waarden in voor subscriptionId, resourceGroupName, en serviceName voor het abonnement, de resourcegroep en de servicenaam van uw API-beheerexemplaar. I

Optionele instellingen in config.design.json

Configureer eventueel de volgende instellingen in het config.design.json bestand:

1. Als u CAPTCHA wilt inschakelen in uw ontwikkelaarsportal, stelt u deze in "useHipCaptcha": true. Zorg ervoor dat u CORS-instellingen configureert voor de back-end van de ontwikkelaarsportal.

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

2. Stel binnen integration onder googleFontsapiKey optioneel in op een Google API-sleutel die toegang biedt tot de Web Fonts Developer-API. Deze sleutel is alleen nodig als u Google-lettertypen wilt toevoegen in de sectie Stijlen van de editor voor de ontwikkelaarsportal.

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

3. Als u nog geen sleutel hebt, kunt u er een configureren met behulp van de Google Cloud-console. Volg deze stappen:

   1. Open de Google Cloud-console.
   2. Controleer of de Ontwikkelaars-API voor weblettertypen is ingeschakeld. Als dat niet het geval is, zet het aan.
   3. Selecteer Referenties aanmaken>API-sleutel.
   4. Kopieer in het geopende dialoogvenster de gegenereerde sleutel en plak deze als de waarde in apiKey het config.design.json bestand.
   5. Selecteer API-sleutel bewerken om de sleuteleditor te openen.
   6. Selecteer in de editor onder API-beperkingen de optie Sleutel beperken. Selecteer in de vervolgkeuzelijst De Ontwikkelaars-API voor weblettertypen.
   7. Selecteer Opslaan.

config.publish.json-bestand

Ga naar de src map en open het config.publish.json bestand.

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

Kopieer en plak de subscriptionId, resourceGroupNameen serviceName waarden uit het vorige configuratiebestand.

config.runtime.json-bestand

Ga naar de src map en open het config.runtime.json bestand.

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

Vervang < service name > door de naam van uw API Management-exemplaar dat u in de vorige configuratiebestanden heeft gebruikt.

De statische website configureren

Configureer de functie Statische website in uw opslagaccount door routes naar de index- en foutpagina's op te geven:

1. Ga in Azure Portal naar uw opslagaccount in Azure Portal.

2. Selecteer in het zijbalkmenu de statischewebsite>.

3. Selecteer Ingeschakeld op de pagina Statische website.

4. Voer in het veld Indexdocumentnaamindex.htmlin.

5. Voer in het veld Foutdocument-pad404/index.html in.

6. Selecteer Opslaan.

Noteer de URL van het primaire eindpunt . U configureert deze later voor toegang tot uw zelf-hostende portal.

CORS-instellingen configureren voor opslagaccount

De CORS-instellingen (Cross-Origin Resource Sharing) voor het opslagaccount configureren:

1. Ga naar uw opslagaccount in de Azure Portal.

2. Selecteer in het zijbalkmenu onder Instellingen de optie Resource delen (CORS).

3. Configureer op het tabblad Blob Service de volgende regels:

   Regel	Waarde
   Toegestane oorsprongen	*
   Toegestane methoden	Selecteer alle HTTP-woorden.
   Toegestane kopteksten	*
   Blootgelegde headers	*
   Maximale leeftijd	0

4. Selecteer Opslaan.

CORS-instellingen configureren voor de back-end van de ontwikkelaarsportal

Configureer CORS-instellingen voor de back-end van de ontwikkelaarsportal om aanvragen toe te staan die afkomstig zijn van uw zelf-hostende ontwikkelaarsportal. De zelfgehoste ontwikkelaarsportal is afhankelijk van het back-end-eindpunt van de ontwikkelaarsportal (ingesteld in backendUrl portalbestand config.runtime.json) om verschillende functies in te schakelen, waaronder:

• CAPTCHA-verificatie
• OAuth 2.0-autorisatie in de testconsole
• Overdracht van gebruikersverificatie en productabonnement

CORS-instellingen toevoegen:

1. Ga naar uw API Management-exemplaar in Azure Portal.
2. SelecteerInstellingen> in het zijbalkmenu.
3. Voeg op het tabblad Zelf-hostende portalconfiguratie een of meer origin-domeinwaarden toe. Bijvoorbeeld:
   • Het domein waar de zelf-gehoste portal wordt gehost, zoals https://contoso.developer.azure-api.net
   • localhost voor lokale ontwikkeling (indien van toepassing), zoals http://localhost:8080 of https://localhost:8080
4. Selecteer Opslaan.

Stap 3: De portal uitvoeren

Nu kunt u een lokaal portalexemplaar bouwen en runnen in de ontwikkelingsmodus. In de ontwikkelingsmodus worden alle optimalisaties uitgeschakeld en worden de bronkaarten ingeschakeld.

1. Voer de volgende opdracht uit:

   npm run start
   

2. U wordt gevraagd om te verifiëren via uw browser. Selecteer uw Microsoft-referenties om door te gaan.

3. Na enige tijd wordt de standaardbrowser automatisch geopend met uw lokale instantie van de ontwikkelaarsportal. Het standaardadres is http://localhost:8080, maar de poort kan veranderen als 8080 deze al bezet is. Wanneer u wijzigingen aanbrengt in de codebasis van het project, wordt het browservenster opnieuw opgebouwd en vernieuwd.

Stap 4: Bewerken via de visuele editor

Gebruik de visuele editor om deze taken uit te voeren:

• Uw portal aanpassen
• Inhoud schrijven
• De structuur van de website organiseren
• Stijl het uiterlijk

Zie Zelfstudie: De ontwikkelaarsportal openen en aanpassen. Hierin worden de basisbeginselen van de gebruikersinterface met beheerdersrechten beschreven en worden aanbevolen wijzigingen in de standaardinhoud vermeld. Sla alle wijzigingen op in de lokale omgeving en druk op Ctrl+C om deze te sluiten.

Stap 5: De portal lokaal publiceren

1. Voer npm run publishuit. U wordt gevraagd om te verifiëren via uw browser. Selecteer uw Microsoft-referenties om door te gaan.

2. Na enige tijd wordt de inhoud gepubliceerd naar de dist/website map.

Stap 6: Statische bestanden uploaden naar een blob

Gebruik de Azure CLI om de lokaal gegenereerde statische bestanden te uploaden naar een blob en zorg ervoor dat uw bezoekers ze kunnen bereiken:

1. Open de Windows-opdrachtprompt, PowerShell of een andere opdrachtshell.

2. Voer de volgende az storage blog upload-batch opdracht uit. Vervang <connection-string> door een verbindingsreeks voor uw opslagaccount. U kunt deze ophalen in de sectie Beveiligings- en> van uw opslagaccount.

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

Stap 7: Ga naar uw website

Uw website is nu live onder de hostnaam die is opgegeven in uw Azure Storage-eigenschappen. Ga in het zijbalkmenu naar Gegevensbeheer>Statische website. De hostnaam is de waarde van het primaire eindpunt.

De website-editor hosten

Wanneer u wijzigingen aanbrengt in de websitecode, moet u mogelijk ook de code van de website-editor bijwerken om het bewerken van gewijzigde widgets goed te kunnen ondersteunen. In dit geval kunt u, naast het hosten van de portal, ook de editortoepassing hosten. Hiervoor moet u deze bouwen en configureren voor toegang tot uw API Management-service.

Hiervoor hebt u een Microsoft Entra ID-toepassing in uw tenant nodig:

1. Registreer een toepassing in uw Microsoft Entra ID-tenant. Noteer de Applicatie (client) ID en de Directory (tenant) ID. U configureert ze in een latere stap.
2. Configureer een webomleidings-URI (antwoord-URL ) in deze toepassing om te verwijzen naar het eindpunt van de web-app waarop de ontwerper wordt gehost. Dit is doorgaans de locatie van de website op basis van blob-opslag. Voorbeeld: https://<your-storage-account-name>z13.web.core.windows.net/.
3. Als u de portal wilt publiceren in pipelines (GitHub Actions), maakt u ook een clientsleutel voor deze toepassing. Noteer de gegenereerde geheime waarde en sla deze op een veilige locatie op.

Volg vervolgens deze stappen om de website-editor te hosten:

1. Voeg de velden clientId en tenantId toe aan het config.design.json bestand.

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

2. Voer de npm run build-designer opdracht uit om designer te bouwen.

3. Ga naar de gegenereerde /dist/designer map, die een bestand config.json bevat met de volgende inhoud:

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

4. Bevestig de configuratie van subscriptionIden resourceGroupNameserviceName, die nodig zijn om verbinding te maken met uw API Management-service met behulp van Azure Resource Manager-API's.

Portal publiceren in pijplijnen (GitHub Actions)

U kunt de zelfgehoste portal publiceren in een pijplijn, bijvoorbeeld GitHub Actions.

De pijplijn heeft ook entra-id-toepassingsreferenties nodig om publicatie uit te voeren met behulp van pijplijnen. U kunt dezelfde Entra ID-toepassing gebruiken die in de vorige stappen is beschreven. De tenantId, clientId en vooral clientSecret moeten worden bewaard in de respectieve sleutelopslag. Zie Geheimen gebruiken in GitHub Actions voor meer informatie.

Voorbeeld van YAML voor GitHub Actions-pijplijn:

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

API Management-meldingssjablonen wijzigen

Vervang de URL van de ontwikkelaarsportal in de API Management-meldingssjablonen, zodat deze verwijst naar uw zelf-hostende portal. Zie Meldingen en e-mailsjablonen configureren in Azure API Management.

Voer met name de volgende wijzigingen uit in de standaardsjablonen:

Bevestiging van e-mailwijziging

Werk de URL van de ontwikkelaarsportal bij in de bevestigingsmeldingssjabloon voor e-mailwijzigingen :

Oorspronkelijke inhoud

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

bijgewerkt

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

Bevestiging van nieuwe ontwikkelaarsaccount

Werk de URL van de ontwikkelaarsportal bij in de bevestigingsmeldingssjabloon voor het nieuwe ontwikkelaarsaccount :

Oorspronkelijke inhoud

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

bijgewerkt

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

Gebruiker uitnodigen

Werk de URL van de ontwikkelaarsportal bij in de sjabloon Gebruikersmelding uitnodigen :

Oorspronkelijke inhoud

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

bijgewerkt

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

Nieuw abonnement geactiveerd

Werk de URL van de ontwikkelaarsportal bij in de meldingssjabloon Nieuw abonnement geactiveerd :

Oorspronkelijke inhoud

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!

bijgewerkt

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!

Oorspronkelijke inhoud

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

bijgewerkt

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

Oorspronkelijke inhoud

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

bijgewerkt

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

Oorspronkelijke inhoud

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

bijgewerkt

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

Bevestiging van wachtwoordwijziging

Werk de URL van de ontwikkelaarsportal bij in de bevestigingsmeldingssjabloon voor wachtwoordwijzigingen :

Oorspronkelijke inhoud

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

bijgewerkt

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

Alle sjablonen

Werk de URL van de ontwikkelaarsportal bij in een sjabloon met een koppeling in de voettekst:

Oorspronkelijke inhoud

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

bijgewerkt

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

Overstappen van beheerde naar zelf-hostende ontwikkelaarsportal

Na verloop van tijd kunnen uw zakelijke vereisten veranderen. U kunt terechtkomen in een situatie waarin de beheerde versie van de API Management-ontwikkelaarsportal niet meer aan uw behoeften voldoet. Een nieuwe vereiste kan u bijvoorbeeld dwingen om een aangepaste widget te bouwen die kan worden geïntegreerd met een externe gegevensprovider. In tegenstelling tot de beheerde versie biedt de zelf-hostende versie van de portal u volledige flexibiliteit en uitbreidbaarheid.

Overgangsproces

U kunt overstappen van de beheerde versie naar een zelf-gehoste versie binnen hetzelfde exemplaar van de API Management-service. Het proces behoudt de wijzigingen die u in de beheerde versie van de portal hebt uitgevoerd. Zorg ervoor dat u vooraf een back-up maakt van de inhoud van de portal. U vindt het back-upscript in de scripts.v3 map van de GitHub-opslagplaats van de API Management-ontwikkelaarsportal.

Het conversieproces is bijna identiek aan het instellen van een algemene zelf-hostende portal, zoals wordt weergegeven in de vorige stappen in dit artikel. Er is één uitzondering in de configuratiestap. Het opslagaccount in het config.design.json bestand moet hetzelfde zijn als het opslagaccount van de beheerde versie van de portal. Zie zelfstudie: Een door het Linux-VM-systeem toegewezen identiteit gebruiken voor toegang tot Azure Storage via een SAS-referentie voor instructies over het ophalen van de SAS-URL.

Verwante inhoud

• Meer informatie over alternatieve benaderingen voor zelfhosting