Delen via

Uw API Center-portal zelf hosten

In dit artikel wordt beschreven hoe u de API Center-portal zelf host, een website die ontwikkelaars en andere belanghebbenden in uw organisatie kunnen gebruiken om de API's te detecteren in uw API Center-. Implementeer een referentie-implementatie van de portal vanuit de API Center-portalstarter repository.

Schermopname van de API Center-portal nadat de gebruiker zich heeft aangemeld.

Hint

Nieuw! U kunt nu een door Azure beheerde versie van de API Center-portal instellen. Zie De API Center-portal instellenvoor meer informatie.

Over het zelf hosten van de portal

U kunt een referentie-implementatie van de portal bouwen en implementeren met behulp van code in de API Center-portalstart opslagplaats. De portal gebruikt de Azure API Center-gegevensvlak-API om gegevens op te halen uit uw API-centrum.

De naslagimplementatie van de API Center-portal biedt:

  • Een framework voor het publiceren en onderhouden van een door de klant beheerde API-portal met behulp van GitHub Actions
  • Een portalplatform dat klanten kunnen wijzigen of uitbreiden om aan hun behoeften te voldoen
  • Flexibiliteit voor het hosten van verschillende infrastructuren, waaronder implementatie voor services zoals Azure Static Web Apps.

Notitie

Wanneer u de API Center-portal zelf host, wordt u de onderhouder en bent u verantwoordelijk voor de upgrades. Azure-ondersteuning is beperkt.

Vereiste voorwaarden

  • Een API-centrum in uw Azure-abonnement. Als u er nog geen hebt gemaakt, raadpleeg dan Quickstart: Uw API-centrum maken.

  • Machtigingen voor het maken van een app-registratie in een Microsoft Entra-tenant die is gekoppeld aan uw Azure-abonnement en machtigingen voor het verlenen van toegang tot gegevens in uw API-centrum.

  • Als u de portal wilt bouwen en implementeren, hebt u een GitHub-account en de volgende hulpprogramma's nodig die op uw lokale computer zijn geïnstalleerd:

Microsoft Entra-app-registratie maken

Configureer eerst een app-registratie in uw Microsoft Entra ID-tenant. Met de app-registratie kan de API Center-portal toegang krijgen tot gegevens vanuit uw API-centrum namens een aangemelde gebruiker.

API Center kan de app-registratie automatisch instellen of u kunt de app-registratie handmatig maken.

De app-registratie automatisch instellen

Voer de volgende stappen uit om de app-registratie automatisch in te stellen:

  1. Navigeer in Azure Portal naar uw API-centrum.
  2. Selecteer in het menu aan de linkerkant de portalinstellingen> voor API Center.
  3. Op het tabblad Id-provider selecteer Instellen starten.
  4. Selecteer Opslaan en publiceren.

De app-registratie handmatig instellen

Als u de app-registratie handmatig wilt maken, voert u de volgende stappen uit:

  1. Ga in Azure Portal naar Microsoft Entra ID>App-registraties.

  2. Selecteer + Nieuwe registratie.

  3. Op de pagina Een toepassing registreren stelt u de waarden als volgt in:

    1. Stel Naam in op een beschrijvende naam, zoals api-center-portal
    2. Selecteer onder Ondersteunde accounttypen op Accounts in deze organisatiemap (één tenant).
    3. Selecteer bij Redirect URI de optie Single Page Application (SPA) en stel de URI in. Voer de URI van uw API Center-portalimplementatie in, in de volgende vorm: https://<service-name>.portal.<location>.azure-apicenter.ms. Vervang <service name> en <location> door de naam van uw API-centrum en de locatie waar deze is geïmplementeerd, bijvoorbeeld: https://myapicenter.portal.eastus.azure-apicenter.ms.
    4. Selecteer Registreren.

Aanvullende omleidings-URI's configureren voor VS Code-extensie

Wanneer u de api Center-portalweergave inschakelt in de Visual Studio Code-extensie voor API Center, configureert u ook de volgende omleidings-URI's in de app-registratie:

  1. Navigeer in Azure Portal naar uw app-registratie.

  2. Selecteer op de pagina Beheren>Verificatie, Een platform toevoegen en selecteer Mobiele en bureaubladtoepassingen.

  3. Configureer de volgende drie aangepaste omleidings-URI's:
    https://vscode.dev/redirect
    http://localhost
    ms-appx-web://Microsoft.AAD.BrokerPlugin/<application-client-id>

    Vervang <application-client-id> door de toepassings-id (client) van deze app. U vindt deze waarde op de overzichtspagina van de app-registratie.

Notitie

Wanneer u de portal zelf host en deze lokaal wilt testen voordat u implementeert in Azure, stelt u de omleidings-URI in de app-registratie in op https://localhost:5173.

Lokale omgeving configureren

Volg deze stappen om de API Center-portal lokaal te bouwen en te testen.

  1. Kloon de API Center-portalstarter repository naar uw lokale computer.

    git clone https://github.com/Azure/APICenter-Portal-Starter.git

  2. Ga naar de APICenter-Portal-Starter directory.

    cd APICenter-Portal-Starter

  3. Bekijk de hoofdtak.

    git checkout main

  4. Als u de service wilt configureren, kopieert of wijzigt u de naam van het public/config.example-bestand in public/config.json.

  5. Bewerk vervolgens het public/config.json-bestand om naar uw service te verwijzen. Werk de waarden in het bestand als volgt bij:

    1. Vervang <service name> en <location> door de naam van uw API-centrum en de locatie waar deze is geïmplementeerd
    2. Vervang <client ID> en <tenant ID> door de toepassings-id (client)-id en directory-id (tenant) van de app-registratie die u in de vorige sectie hebt gemaakt.
    3. Werk de waarde van title bij naar een naam die u wilt weergeven in de bovenste balk van de portal.
    {
  "dataApiHostName": "<service name>.data.<location>.azure-apicenter.ms/workspaces/default",
  "title": "API portal",
  "authentication": {
      "clientId": "<client ID>",
      "tenantId": "<tenant ID>",
      "scopes": ["https://azure-apicenter.net/user_impersonation"],
      "authority": "https://login.microsoftonline.com/"
  }
}

  6. Vereiste pakketten installeren.

    npm install

  7. Start de ontwikkelserver. Met de volgende opdracht wordt de portal gestart in de ontwikkelmodus die lokaal wordt uitgevoerd:

    npm start

    Blader naar de portal op https://localhost:5173.

Implementeren in Azure

Zie de API Center-portal-starter opslagplaats voor stappen voor het implementeren van de portal in Azure Static Web Apps.

Inloggen op portal inschakelen voor Microsoft Entra-gebruikers en -groepen

Om aanmelding in te schakelen, wijst u de Azure API Center Data Reader rol toe aan gebruikers of groepen in uw organisatie, binnen het bereik van uw API-centrum.

Belangrijk

Standaard hebben u en andere beheerders van het API-centrum geen toegang tot API's in de API Center-portal. Zorg ervoor dat u de rol Azure API Center-gegevenslezer toewijst aan uzelf en andere beheerders.

Zie Azure-rollen toewijzen met behulp van Azure Portalvoor gedetailleerde vereisten en stappen voor het toewijzen van een rol aan gebruikers en groepen. Korte stappen volgen:

  1. Navigeer in Azure Portal naar uw API-centrum.
  2. Selecteer in het linkermenu Toegangsbeheer (IAM)>+ Roltoewijzing toevoegen.
  3. Stel in het deelvenster Roltoewijzing toevoegen de waarden als volgt in:
    1. Zoek op de pagina Role naar en selecteer Azure API Center Data Reader. Kies Volgende.
    2. Selecteer op de pagina Leden, in Toegang toewijzen aan, de optie Gebruiker, groep of service-principal>+ Leden kiezen.
    3. Zoek en selecteer op de pagina Leden selecteren de gebruikers of groepen waaraan u de rol wilt toewijzen. Klik op Selecteren en vervolgens op Volgende.
    4. Controleer de roltoewijzing en selecteer Beoordelen en toewijzen.

Notitie

Als u de toegangsconfiguratie voor nieuwe gebruikers wilt stroomlijnen, wordt u aangeraden de rol toe te wijzen aan een Microsoft Entra-groep en een dynamische groepslidmaatschapsregel te configureren. Zie Een dynamische groep maken of bijwerken in Microsoft Entra IDvoor meer informatie.

Nadat u de toegang tot de portal hebt geconfigureerd, kunnen geconfigureerde gebruikers zich aanmelden bij de portal en de API's weergeven in uw API-centrum.

Notitie

De eerste gebruiker die zich bij de portal aanmeldt, wordt gevraagd om toestemming te geven voor de machtigingen die zijn aangevraagd door de registratie van de API Center-portal-app. Daarna worden andere geconfigureerde gebruikers niet gevraagd om toestemming te geven.

Problemen oplossen

Fout: 'U bent niet gemachtigd om toegang te krijgen tot deze portal'

Onder bepaalde voorwaarden kan een gebruiker het volgende foutbericht tegenkomen na het aanmelden bij de API Center-portal met een geconfigureerd gebruikersaccount:

You are not authorized to access this portal. Please contact your portal administrator for assistance. `

Controleer eerst of de gebruiker de Azure API Center-gegevenslezer rol in uw API-centrum heeft toegewezen.

Als de gebruiker de rol krijgt toegewezen, kan er een probleem zijn met de registratie van de Microsoft.ApiCenter resourceprovider in uw abonnement. Mogelijk moet u de resourceprovider opnieuw registreren. Voer hiervoor de volgende opdracht uit in de Azure CLI:

az provider register --namespace Microsoft.ApiCenter

Kan niet aanmelden bij de portal

Als gebruikers aan wie de Azure API Center-gegevenslezer rol zijn toegewezen, de aanmeldingsstroom niet kunnen voltooien nadat ze aanmelden in de API Center-portal hebben geselecteerd, kan er een probleem zijn met de configuratie van de Id-provider van Microsoft Entra ID.

Controleer in de registratie van de Microsoft Entra-app de omleidings-URI--instellingen en werk deze indien nodig bij om ervoor te zorgen dat de URI overeenkomt met de URI van de API Center-portalimplementatie.

Kan geen Machtigingen voor Azure API Center selecteren in de registratie van de Microsoft Entra-app

Als u geen API-machtigingen kunt aanvragen voor Azure API Center in uw Microsoft Entra-app-registratie voor de API Center-portal, controleert u of u zoekt naar Azure API Center- (of toepassings-id c3ca1a77-7a87-4dba-b8f8-eea115ae4573).

Als de app niet aanwezig is, is er mogelijk een probleem met de registratie van de Microsoft.ApiCenter resourceprovider in uw abonnement. Mogelijk moet u de resourceprovider opnieuw registreren. Voer hiervoor de volgende opdracht uit in de Azure CLI:

az provider register --namespace Microsoft.ApiCenter

Nadat u de resourceprovider opnieuw hebt geregistreerd, probeert u opnieuw API-machtigingen aan te vragen.

Ondersteuningsbeleid

Feedback geven, functies aanvragen en ondersteuning krijgen voor de naslagimplementatie van de API Center-portal in de API Center-portal starter opslagplaats.

Verwante inhoud