De API Management-ontwikkelaarsportal zelf hosten

  • Artikel

VAN TOEPASSING OP: Ontwikkelaar | Basic | Standaard | Premium

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.

Belangrijk

Overweeg om de ontwikkelaarsportal alleen zelf te hosten wanneer u de kern van de codebasis van de ontwikkelaarsportal moet wijzigen. Voor deze optie is geavanceerde configuratie vereist, waaronder:

  • Implementatie naar een hostingplatform, optioneel uitgevoerd door een oplossing zoals CDN voor betere beschikbaarheid en prestaties
  • Hostinginfrastructuur onderhouden en beheren
  • Handmatige updates, waaronder voor beveiligingspatches, waarvoor u mogelijk codeconflicten moet oplossen bij het upgraden van de codebasis

Notitie

De zelf-hostende portal biedt geen ondersteuning voor zichtbaarheid en toegangsbeheer die beschikbaar zijn in de beheerde ontwikkelaarsportal.

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

Vereisten

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

Stap 1: lokale omgeving instellen

Als u uw lokale omgeving wilt instellen, moet u de opslagplaats klonen, overschakelen naar de nieuwste versie van de ontwikkelaarsportal en npm-pakketten installeren.

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

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

  2. Ga naar uw lokale kopie van de opslagplaats:

    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

Tip

Gebruik altijd de nieuwste portalrelease en houd uw geforkte portal up-to-date. De softwaretechnici gebruiken de master vertakking van deze opslagplaats voor dagelijkse ontwikkelingsdoeleinden. Het heeft instabiele versies van de software.

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

Voor de ontwikkelaarsportal is de REST API van API Management vereist om de inhoud te beheren.

config.design.json bestand

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

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

Configureer het bestand:

  1. Vervang in de managementApiUrl waarde door <service-name> de naam van uw API Management-exemplaar. Als u een aangepast domein hebt geconfigureerd, gebruikt u dit in plaats daarvan (bijvoorbeeld https://management.contoso.com).

    {
...
"managementApiUrl": "https://contoso-api.management.azure-api.net"
...

  2. Maak handmatig een SAS-token om de directe REST API-toegang tot uw API Management-exemplaar in te schakelen.

  3. Kopieer het gegenereerde token en plak het als de managementApiAccessToken waarde.

  4. Vervang in de backendUrl waarde door <service-name> de naam van uw API Management-exemplaar. Als u een aangepast domein hebt geconfigureerd, gebruikt u dit in plaats daarvan (bijvoorbeeld https://portal.contoso.com).

    {
...
"backendUrl": "https://contoso-api.developer.azure-api.net"
...

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

  6. Stel integrationonder googleFonts,optioneel in apiKey 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.

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

    1. Open de Google Cloud-console.
    2. Controleer of de Ontwikkelaars-API voor weblettertypen is ingeschakeld. Als dit niet het is, schakelt u deze in.
    3. Selecteer Api-sleutel voor referenties>maken.
    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",
  "managementApiUrl": "https://<service-name>.management.azure-api.net",
  "managementApiAccessToken": "SharedAccessSignature...",
  "useHipCaptcha": false
}

Configureer het bestand:

  1. Kopieer en plak de managementApiUrl waarden managementApiAccessToken uit het vorige configuratiebestand.

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

config.runtime.json-bestand

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

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

Configureer het bestand:

  1. Kopieer en plak de managementApiUrl waarde uit het vorige configuratiebestand.

  2. Vervang in de backendUrl waarde door <service-name> de naam van uw API Management-exemplaar. Als u een aangepast domein hebt geconfigureerd, gebruikt u dit in plaats daarvan (bijvoorbeeld). https://portal.contoso.com

    {
...
"backendUrl": "https://contoso-api.developer.azure-api.net"
...

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 naar uw opslagaccount in Azure Portal en selecteer statische website in het menu aan de linkerkant.

  2. Selecteer Ingeschakeld op de pagina Statische website.

  3. Voer in het veld Indexdocumentnaam index.html in.

  4. Voer 404/index.html in het veld Foutdocumentpad in.

  5. Selecteer Opslaan.

CORS-instellingen configureren voor opslagaccount

Configureer de CORS-instellingen (Cross-Origin Resource Sharing) voor het opslagaccount:

  1. Ga naar uw opslagaccount in Azure Portal en selecteer CORS in het menu aan de linkerkant.

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

    Regel Weergegeven als
    Toegestane oorsprongen *
    Toegestane methoden Selecteer alle HTTP-woorden.
    Toegestane headers *
    Weergegeven headers *
    Maximale leeftijd 0

  3. 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 zelf-hostende ontwikkelaarsportal is afhankelijk van het back-endeindpunt van de ontwikkelaarsportal (ingesteld in backendUrl de configuratiebestanden van de portal) om verschillende functies in te schakelen, waaronder:

CORS-instellingen toevoegen:

  1. Ga naar uw API Management-exemplaar in Azure Portal en selecteer instellingen voor de ontwikkelaarsportal>in het menu aan de linkerkant.
  2. Voeg op het tabblad Zelf-hostende portalconfiguratie een of meer origin-domeinwaarden toe. Bijvoorbeeld:
    • Het domein waar de zelf-hostende portal wordt gehost, zoals https://www.contoso.com
    • localhost voor lokale ontwikkeling (indien van toepassing), zoals http://localhost:8080 of https://localhost:8080
  3. Selecteer Opslaan.

Stap 3: De portal uitvoeren

U kunt nu een lokaal portalexemplaren bouwen en uitvoeren in de ontwikkelingsmodus. In de ontwikkelingsmodus worden alle optimalisaties uitgeschakeld en worden de bronkaarten ingeschakeld.

Voer de volgende opdracht uit:

npm start

Na korte 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. Wijzigingen in de codebasis van het project activeren een herbouwen en vernieuwen van het browservenster.

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
  • Gestileerd zijn 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: Lokaal publiceren

De portalgegevens zijn afkomstig uit de vorm van sterk getypte objecten. Met de volgende opdracht worden ze omgezet in statische bestanden en wordt de uitvoer in de ./dist/website map opgeslagen:

npm run publish

Stap 6: Statische bestanden uploaden naar een blob

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

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

  2. Voer de volgende Azure CLI-opdracht uit.

    Vervang <account-connection-string> door de verbindingsreeks van uw opslagaccount. U kunt deze ophalen uit de sectie Toegangssleutels van uw opslagaccount.

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

Stap 7: Ga naar uw website

Uw website is nu live onder de hostnaam die is opgegeven in uw Azure Storage-eigenschappen (primair eindpunt op statische websites).

Stap 8: Api Management-meldingssjablonen wijzigen

Vervang de URL van de ontwikkelaarsportal in de API Management-meldingssjablonen om te verwijzen 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:

Notitie

Bij de waarden in de volgende bijgewerkte secties wordt ervan uitgegaan dat u de portal host op https://portal.contoso.com/.

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. Met een nieuwe vereiste kunt u bijvoorbeeld een aangepaste widget maken 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-hostende versie binnen hetzelfde EXEMPLAAR van de API Management-service. Het proces behoudt de wijzigingen die u hebt uitgevoerd in de beheerde versie van de portal. Zorg ervoor dat u vooraf een back-up maakt van de inhoud van de portal. U vindt het back-upscript in de scripts 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.

Tip

U wordt aangeraden een afzonderlijk opslagaccount in het config.publish.json bestand te gebruiken. Deze aanpak biedt u meer controle en vereenvoudigt het beheer van de hostingservice van uw portal.

Volgende stappen