De API Management-ontwikkelaarsportal aanpassen in WordPress

VAN TOEPASSING OP: Ontwikkelaar | Basic | Standaard | Premie

In dit artikel wordt beschreven hoe u een opensource-invoegtoepassing voor ontwikkelaarsportal (preview) configureert om de API Management-ontwikkelaarsportal op WordPress aan te passen. Met de invoegtoepassing kunt u elke WordPress-site omzetten in een ontwikkelaarsportal. Profiteer van sitemogelijkheden in WordPress om functies aan uw ontwikkelaarsportal aan te passen en toe te voegen, waaronder lokalisatie, samenvouwbare en uitvouwbare menu's, aangepaste opmaakmodellen, bestandsdownloads en meer.

In dit artikel maakt u een WordPress-site op Azure-app Service en configureert u de invoegtoepassing voor de ontwikkelaarsportal op de WordPress-site. Microsoft Entra-id is geconfigureerd voor verificatie bij de WordPress-site en de ontwikkelaarsportal.

Vereisten

  • Maak een API Management-exemplaar.

    Notitie

    Momenteel wordt de invoegtoepassing niet ondersteund in de API Management v2-lagen.

  • De ontwikkelaarsportal inschakelen en publiceren. Zie de zelfstudie Toegang krijgen tot en aanpassen van het ontwikkelaarsportaal voor stappen.
  • Machtigingen voor het maken van een app-registratie in een Microsoft Entra-tenant die is gekoppeld aan uw Azure-abonnement.
  • Installatiebestanden voor de WordPress-plugin voor de ontwikkelaarsportal en het aangepaste WordPress-thema vanuit de plugin-repo. Download de volgende zip-bestanden uit de dist-map in de repository:
    • Invoegtoepassingsbestand: apim-devportal.zip
    • Themabestand: twentytwentyfour.zip

Stap 1: WordPress maken in App Service

Voor dit scenario maakt u een beheerde WordPress-site die wordt gehost op Azure-app Service. Hier volgen korte stappen:

  1. Navigeer in Azure Portal naar https://portal.azure.com/#create/WordPress.WordPress.

  2. Voer op de pagina WordPress maken in App Service op het tabblad Basisbeginselen de projectgegevens, web-app-details en wordPress-instellingen in.

    Sla de gebruikersnaam en het wachtwoord van de WordPress-beheerder op een veilige plaats op. Deze inloggegevens zijn vereist om u in te loggen bij de WordPress-beheeromgeving en de plug-in in een latere stap te installeren.

    Let op

    Vermijd het gebruik van de standaard WordPress-gebruikersnaam admin en maak een sterk wachtwoord. Zie best practices voor WordPress-wachtwoorden voor meer informatie.

  3. Op het tabblad Invoegtoepassingen :

    1. Selecteer de aanbevolen standaardwaarden voor e-mail met Azure Communication Services, Azure Front Door en Azure Blob Storage.
    2. Selecteer of maak een nieuw AFD-profiel.
    3. Selecteer in virtueel netwerk de nieuwe waarde of een bestaand virtueel netwerk.

  4. Laat op het tabblad Implementatie de instelling Staging-slot toevoegen uitgeschakeld.

  5. Selecteer Beoordelen en maken om de uiteindelijke validatie uit te voeren.

  6. Selecteer Maken om de implementatie van de App Service te voltooien.

Het kan enkele minuten duren voordat de App Service is geïmplementeerd.

Stap 2: Een nieuwe Microsoft Entra-app-registratie maken

In deze stap maakt u een nieuwe Microsoft Entra-app. In latere stappen configureert u deze app als id-provider voor verificatie bij uw app-service en naar de ontwikkelaarsportal in uw API Management-exemplaar.

  1. Navigeer in Azure Portal naar App-registraties en selecteer vervolgens + Nieuwe registratie.

  2. Geef de naam van de nieuwe app op en selecteer alleen één tenant in Ondersteunde accounttypen. Selecteer Registreren.

  3. Kopieer en sla de toepassings-id (client) en map-id (tenant) veilig op de pagina Overzicht op. U hebt deze waarden in latere stappen nodig om verificatie te configureren voor uw API Management-exemplaar en app-service. Schermopname van de pagina Overzicht van app-registratie in de portal.

  4. Selecteer in het zijbalkmenu onder BeherenAuthenticatie>+ Een platform toevoegen. Als u deze instelling niet ziet, selecteert u de optie om over te schakelen naar de oude ervaring.

  5. Selecteer Web op de pagina Platformen configureren.

  6. Voer op de Configureer Web pagina de volgende omleidings-URI in, vervang de naam van uw app-service, en selecteer vervolgens Configureren:

    https://app-service-name>.azurewebsites.net/.auth/login/aad/callback

  7. Selecteer + Een platform opnieuw toevoegen. Selecteer toepassing met één pagina.

  8. Voer op de pagina Toepassing met één pagina configureren de volgende omleidings-URI in, vervang de naam van uw API Management-exemplaar en selecteer Configureer.

    https://<apim-instance-name>.developer.azure-api.net/signin

  9. Selecteer + Een platform opnieuw toevoegen. Selecteer de toepassing met één pagina opnieuw.

  10. Voer op de Configureer enkele-pagina toepassing pagina de volgende omleidings-URI in, waarbij u de naam van uw API Management-exemplaar vervangt en selecteer Configureer:

    https://<management-instance-name>.developer.azure-api.net/

  11. Selecteer in het zijbalkmenu onder Beherende optie Tokenconfiguratie>+ Optionele claim toevoegen.

  12. Selecteer op de pagina Optionele claim toevoegen de id en selecteer vervolgens de volgende claims: e-mail, family_name, given_name, onprem_sid, preferred_username, upn. Selecteer Toevoegen.

  13. Wanneer u hierom wordt gevraagd, selecteert u Microsoft Graph-e-mail, profielmachtiging inschakelen. Selecteer Toevoegen.

  14. Selecteer API-machtigingen beheren in het zijbalkmenu en controleer of de volgende Microsoft Graph-machtigingen aanwezig zijn: e-mail, profiel, User.Read.

    Schermopname van API-machtigingen in de portal.

  15. Selecteer in het zijbalkmenu onder Beheren de optie Certificaten en geheimen>+ Nieuw clientgeheim.

  16. Configureer instellingen voor het geheim en selecteer Toevoegen. Kopieer en sla de waarde van het geheim veilig op direct nadat het is gegenereerd. U hebt deze waarde in latere stappen nodig om de toepassing toe te voegen aan uw API Management-exemplaar en app-service voor verificatie.

  17. Selecteer een API beschikbaar maken in het zijbalkmenu onder Beheren. Noteer de standaard Application ID URI. Voeg desgewenst aangepaste uitbreidingen toe.

Stap 3: Verificatie inschakelen voor de app-service

In deze stap voegt u de registratie van de Microsoft Entra-app toe als id-provider voor verificatie aan de WordPress-app-service.

  1. Navigeer in de portal naar de WordPress-app-service.

  2. Selecteer in het zijbalkmenu onder Instellingen de optie Authenticatie>Identiteitsprovider toevoegen.

  3. Selecteer Microsoft op het tabblad Basisinformatie in id-provider.

  4. Selecteer onder App-registratie de optie Geef de details van een bestaande app-registratie op.

    1. Voer de toepassings-id (client) en het clientgeheim in van de app-registratie die u in de vorige stap hebt gemaakt.
    2. Voer in de URL van de uitgever een van de volgende waarden in voor het verificatie-eindpunt: https://login.microsoftonline.com/<tenant-id> of https://sts.windows.net/<tenantid>. Vervang <tenant-id> door de directory-id (tenant) van de app-registratie.

      Belangrijk

      Gebruik het eindpunt van versie 2.0 niet voor de URL van de verlener (eindigend op /v2.0URL).

  5. In toegestane tokendoelgroepen, voer de Application ID URI in vanuit de applicatieregistratie. Voorbeeld: api://<app-id>.

  6. Selecteer onder Aanvullende controles de waarden die geschikt zijn voor uw omgeving of gebruik de standaardwaarden.

  7. Configureer de gewenste waarden voor de resterende instellingen of gebruik de standaardwaarden. Selecteer Toevoegen.

    Notitie

    Als u gastgebruikers en aangemelde gebruikers toegang wilt geven tot de ontwikkelaarsportal op WordPress, kunt u niet-geverifieerde toegang inschakelen. Selecteer bij Toegang beperken de optie Niet-geverifieerde toegang toestaan. Zie Autorisatiegedrag voor meer informatie.

De id-provider wordt toegevoegd aan de app-service.

Stap 4: Verificatie inschakelen voor de API Management-ontwikkelaarsportal

Configureer dezelfde Microsoft Entra-app-registratie als een id-provider voor de API Management-ontwikkelaarsportal.

  1. Navigeer in de portal naar uw API Management-exemplaar.

  2. Selecteer In het zijbalkmenu onder De ontwikkelaarsportalde optie Identities>+ Add.

  3. Selecteer Microsoft Entra ID op de pagina Id-provider toevoegen.

  4. Voer de waarden voor de client-id, het clientgeheim en de signin-tenant in uit de app-registratie die u in een vorige stap hebt gemaakt. De Signin-tenant is de directory-ID (tenant) van de app-registratie.

  5. Selecteer de clientbibliotheek en kies MSAL.

  6. Accepteer standaardwaarden voor de overige instellingen en selecteer Toevoegen.

  7. Publiceer de ontwikkelaarsportal opnieuw om de wijzigingen toe te passen.

  8. Test de verificatie door u aan te melden bij de ontwikkelaarsportal op de volgende URL, waarbij u de naam van uw API Management-exemplaar vervangt: https://<management-instance-name>.developer.azure-api.net/signin Selecteer de knop Microsoft Entra ID onderaan om u aan te melden.

    Wanneer u het voor het eerst opent, wordt u mogelijk gevraagd om toestemming te geven voor specifieke machtigingen.

Stap 5: Instellingen voor de ontwikkelaarsportal configureren in API Management

Werk de instellingen van de ontwikkelaarsportal in het API Management-exemplaar bij om CORS in te schakelen en de app-servicesite op te nemen als oorsprong van de portal.

  1. Blader in Azure Portal naar uw API Management-exemplaar.

  2. Selecteer in het zijbalkmenu onder De ontwikkelaarsportalde optie Portaloverzicht.

  3. Selecteer Inschakelen CORS op het tabblad Portal overzicht.

  4. Selecteer portalinstellingen in het zijbalkmenu onder Ontwikkelaarsportal.

  5. Voer op het tabblad Zelf-hostende portalconfiguratie de hostnaam van uw WordPress op App Service-site in als portal-oorsprong, waarbij u de naam van uw app-service vervangt door de volgende URL: https://<yourapp-service-name>.azurewebsites.net

  6. Publiceer de ontwikkelaarsportal opnieuw om de wijzigingen toe te passen.

Werk ook de cors beleidsconfiguratie in het API Management-exemplaar bij om de App Service-site toe te voegen als een toegestane oorsprong. Deze waarde is nodig om aanroepen vanuit de testconsole van de ontwikkelaarsportal op de WordPress-site toe te staan.

Voeg de volgende origin waarde toe in uw cors beleidsconfiguratie:

<cors ...>
    <allowed-origins>
        [...]
        <origin>https://<yourapp-service-name>.azurewebsites.net</origin>
    </allowed-origins>
</cors>

Meer informatie over het instellen of bewerken van beleidsregels.

Stap 6: Navigeer naar de WordPress-beheersite en upload het aangepaste thema

In deze stap uploadt u het aangepaste thema voor de API Management-ontwikkelaarsportal naar de WordPress-beheersite.

Belangrijk

U wordt aangeraden het thema te uploaden dat is opgegeven in de opslagplaats van de invoegtoepassing. Het thema is gebaseerd op het Twenty Twenty Four-thema en is aangepast om de functionaliteit van de ontwikkelaarsportaal in WordPress te ondersteunen. Als u ervoor kiest om een ander thema te gebruiken, werkt bepaalde functionaliteit mogelijk niet zoals verwacht of is extra aanpassing vereist.

  1. Open de wordPress-beheerwebsite op de volgende URL, waarbij u de naam van uw app-service vervangt: http://<app-service-name>.azurewebsites.net/wp-admin

    Wanneer u het voor het eerst opent, wordt u mogelijk gevraagd om toestemming te geven voor specifieke machtigingen.

  2. Meld u aan bij de WordPress-beheersite met de gebruikersnaam en het wachtwoord die u hebt ingevoerd tijdens het maken van WordPress in App Service.

  3. Selecteer In het zijbalkmenu de optieVormgevingsthema's> en voeg vervolgens Nieuw thema toe.

  4. Selecteer Thema uploaden. Selecteer Bestand kiezen om het themabestand voor de ontwikkelaarsportal van API Management dat u eerder hebt gedownload, in de vorm van een zip-bestand te uploaden. Selecteer Installeren Nu.

  5. Selecteer in het volgende scherm De optie Actief vervangen door geüpload.

  6. Als u hierom wordt gevraagd, selecteert u Activeren.

Notitie

Als uw WordPress-site een caching-plug-in bevat, wis de cache nadat u het thema hebt geactiveerd, zodat de wijzigingen effect hebben.

Stap 7: De invoegtoepassing voor de ontwikkelaarsportal installeren

  1. Selecteer in het zijbalkmenu op de WordPress-beheersite de optie Plugins>Add New Plugin.

  2. Selecteer Plug-in uploaden. Selecteer Bestand kiezen om het ZIP-bestand van de API Management-ontwikkelaarsportal (apim-devportal.zip) te uploaden dat u eerder hebt gedownload. Selecteer Nu installeren.

  3. Nadat de installatie is voltooid, selecteert u De invoegtoepassing activeren.

  4. Selecteer azure API Management Developer Portal in het zijbalkmenu.

  5. Voer op de pagina APIM-instellingen de volgende instellingen in en selecteer Wijzigingen opslaan:

    • ApiM-servicenaam - Naam van uw API Management-exemplaar
    • Maak standaardpagina's inschakelen en navigatiemenu aanmaken

Stap 8: Een aangepast opmaakmodel toevoegen

Voeg een aangepast opmaakmodel toe voor de API Management-ontwikkelaarsportal.

  1. Selecteer in de WordPress-beheersite in het zijbalkmenu Vormgeving>Thema's.

  2. Selecteer Aanpassen en navigeer vervolgens naar Stijlen.

  3. Selecteer het potloodpictogram (Stijlen bewerken).

  4. In het Stijlen-paneel, selecteer Meer (drie puntjes) >Extra CSS.

  5. Voer in Aanvullende CSS de volgende CSS in:

    .apim-table {
  width: 100%;
  border: 1px solid #D1D1D1;
  border-radius: 4px;
  border-spacing: 0;
}

.apim-table th {
  background: #E6E6E6;
  font-weight: bold;
  text-align: left;
}

.apim-table th,
.apim-table td {
  padding: .7em 1em;
}

.apim-table td {
  border-top: #E6E6E6 solid 1px;
}

.apim-input,
.apim-button,
.apim-nav-link-btn {
    border-radius: .33rem;
    padding: 0.6rem 1rem;
}

.apim-button,
.apim-nav-link-btn {
    background-color: var(--wp--preset--color--contrast);
    border-color: var(--wp--preset--color--contrast);
    border-width: 0;
    color: var(--wp--preset--color--base);
    font-size: var(--wp--preset--font-size--small);
    font-weight: 500;
    text-decoration: none;
    cursor: pointer;
    transition: all .25s ease;
}

.apim-nav-link-btn:hover {
    background: var(--wp--preset--color--base);
    color: var(--wp--preset--color--contrast);
}

.apim-button:hover {
    background: var(--wp--preset--color--vivid-cyan-blue);
}

.apim-button:disabled {
    background: var(--wp--preset--color--contrast-2);
    cursor: not-allowed;
}

.apim-label {
    display: block;
    margin-bottom: 0.5rem;
}

.apim-input {
    border: solid 1px var(--wp--preset--color--contrast);
}

.apim-grid {
    display: grid;
    grid-template-columns: 11em max-content;
}

.apim-link,
.apim-nav-link {
    text-align: inherit;
    font-size: inherit;
    padding: 0;
    background: none;
    border: none;
    font-weight: inherit;
    cursor: pointer;
    text-decoration: none;
    color: var(--wp--preset--color--vivid-cyan-blue);
}

.apim-nav-link {
    font-weight: 500;
}

.apim-link:hover,
.apim-nav-link:hover {
    text-decoration: underline;
}

#apim-signIn {
    display: flex;
    align-items: center;
    gap: 24px;
}

  6. Sla de wijzigingen op . Selecteer Opnieuw opslaan om de wijzigingen in het thema op te slaan.

  7. Meld u af bij de WordPress-beheersite.

Stap 9: Meld u aan bij de API Management-ontwikkelaarsportal die is geïmplementeerd op WordPress

Open de WordPress-site om uw nieuwe API Management-ontwikkelaarsportal te zien die is geïmplementeerd op WordPress en gehost op App Service.

  1. Navigeer in een nieuw browservenster naar uw WordPress-site, waarbij u de naam van uw app-service vervangt door de volgende URL: https://<yourapp-service-name>.azurewebsites.net

  2. Wanneer u hierom wordt gevraagd, meldt u zich aan met de Microsoft Entra ID-referenties voor een ontwikkelaarsaccount. Als niet-geverifieerde toegang tot de ontwikkelaarsportal is ingeschakeld, selecteert u Aanmelden op de startpagina van de ontwikkelaarsportal.

Notitie

U kunt zich alleen aanmelden bij de ontwikkelaarsportal op WordPress met behulp van Microsoft Entra ID-referenties. Basisverificatie wordt niet ondersteund.

U kunt nu de volgende functies van de API Management-ontwikkelaarsportal gebruiken:

  • Aanmelden bij de portal
  • Lijst met API's weergeven
  • Ga naar de pagina API-details en bekijk de lijst met bewerkingen
  • De API testen met geldige API-sleutels
  • Lijst met producten weergeven
  • Abonneren op een product en abonnementssleutels genereren
  • Ga naar het tabblad Profiel met account- en abonnementsgegevens
  • Afmelden bij de portal

In de volgende schermopname ziet u een voorbeeldpagina van de API Management-ontwikkelaarsportal die wordt gehost op WordPress.

Schermopname van de ontwikkelaarsportal die wordt gehost op WordPress.

Probleemoplossing

Ik zie de meest recente pagina's van de ontwikkelaarsportal niet op de WordPress-site

Als u de meest recente pagina's van de ontwikkelaarsportal niet ziet wanneer u de WordPress-site bezoekt, controleert u of de invoegtoepassing voor de ontwikkelaarsportal is geïnstalleerd, geactiveerd en geconfigureerd op de WordPress-beheersite. Zie De invoegtoepassing voor de ontwikkelaarsportal installeren voor stappen.

Mogelijk moet u ook de cache op uw WordPress-site of in Azure Front Door wissen als deze is geconfigureerd. Je kunt ook de cache van je browser wissen.

Ik ondervind problemen bij het aanmelden of afmelden bij de ontwikkelaarsportal

Als u problemen ondervindt bij het inloggen of uitloggen op de ontwikkelaarsportal, wis de browsercache of bekijk de ontwikkelaarsportalsite in een afzonderlijke browsersessie (met behulp van de incognito- of privébrowsermodus).

Ik zie geen aanmeldingsknop op de navigatiebalk van de ontwikkelaarsportal

Als u een aangepast thema gebruikt dat verschilt van het thema in de opslagplaats van de invoegtoepassing, moet u mogelijk de aanmeldingsfunctionaliteit handmatig toevoegen aan de navigatiebalk. Voeg op de startpagina het volgende shortcodeblok toe: [SignInButton] Zie de WordPress-documentatie voor meer informatie.

U kunt zich ook handmatig aanmelden of afmelden door de volgende URL's in uw browser in te voeren:

  • Aanmelden: https://<app-service-name>.azurewebsites.net/.auth/login/aad
  • Afmelden: https://<app-service-name>.azurewebsites.net/.auth/logout

Gerelateerde inhoud

  • Last updated on