De API Management-ontwikkelaarsportal zelf hosten

  • Artikel
  • 9 minuten om te lezen

In deze zelfstudie wordt beschreven hoe u de API Management ontwikkelaarsportal zelf host. Selfhosting biedt u flexibiliteit om de ontwikkelaarsportal uit te breiden met aangepaste logica en widgets die pagina's dynamisch aanpassen tijdens runtime. U kunt meerdere portals voor uw API Management exemplaar zelf hosten, met verschillende functies. Wanneer u zelf een portal host, wordt u de onderhouder en bent u verantwoordelijk voor de upgrades.

In de volgende stappen ziet u hoe u uw lokale ontwikkelomgeving instelt, wijzigingen in de ontwikkelaarsportal uitvoert en deze publiceert en implementeert in een Azure-opslagaccount.

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

Beschikbaarheid

Belangrijk

Deze functie is beschikbaar in de Premium-, Standard-, Basic- en Developer-lagen van API Management.

Vereisten

Als u een lokale ontwikkelomgeving wilt instellen, moet u het volgende hebben:

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 <current-release-tag> de waarde door 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 gevorkte 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 API Management REST API vereist om de inhoud te beheren.

bestand config.design.json

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
}

Het bestand configureren:

  1. Vervang <service-name> in de managementApiUrl waarde door 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 <service-name> in de backendUrl waarde door 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 in "useHipCaptcha": true. Zorg ervoor dat u CORS-instellingen configureert voor de back-end van de ontwikkelaarsportal.

bestand config.publish.json

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
}

Het bestand configureren:

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

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

bestand config.runtime.json

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

Het bestand configureren:

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

  2. Vervang <service-name> in de backendUrl waarde door 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 de 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 Indexdocumentnaamindex.htmlin.

  4. Voer in het veld Foutdocumentpad404/index.htmlin.

  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 de Azure Portal en selecteer CORS in het menu aan de linkerkant.

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

    Regel Waarde
    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 de Azure Portal en selecteer instellingen voor de portal voor> ontwikkelaars 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 exemplaar van de ontwikkelaarsportal. Het standaardadres is http://localhost:8080, maar de poort kan veranderen als 8080 deze al bezet is. Als u wijzigingen aan de codebasis van het project wijzigt, wordt het browservenster opnieuw opgebouwd en vernieuwd.

Stap 4: Bewerken via de visuele editor

Gebruik de visual-editor om deze taken uit te voeren:

  • Uw portal aanpassen
  • Inhoud ontwerpen
  • De structuur van de website organiseren
  • Het uiterlijk ervan stiliseren

Zie zelfstudie: De ontwikkelaarsportal openen en aanpassen. Het behandelt de basisbeginselen van de gebruikersinterface met beheerdersrechten en bevat aanbevolen wijzigingen in de standaardinhoud. Sla alle wijzigingen in de lokale omgeving op 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 map opgeslagen ./dist/website :

npm run publish

Stap 6: statische bestanden Upload 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 Windows opdrachtprompt, PowerShell of andere opdrachtshell.

  2. Voer de volgende Azure CLI-opdracht uit.

    Vervang door <account-connection-string> de connection string 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 in 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 bevestigingssjabloon 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 nieuw 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 bevestigingssjabloon 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 bedrijfsvereisten 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-hostende versie binnen hetzelfde API Management service-exemplaar. 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 API Management ontwikkelaarsportal GitHub opslagplaats.

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