Delen via

Uw API Center-portal zelf hosten

  • Artikel

In dit artikel wordt de API Center-portal geïntroduceerd, een website die ontwikkelaars en andere belanghebbenden in uw organisatie kunnen gebruiken om de API's in uw API-centrum te detecteren. Implementeer een referentie-implementatie van de portal vanuit de startersopslagplaats van de API Center-portal.

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

Over de API Center-portal

De API Center-portal is een website die u kunt bouwen en hosten om de API-inventaris in uw API-centrum weer te geven. Met de portal kunnen ontwikkelaars en andere belanghebbenden in uw organisatie API's detecteren en API-details bekijken.

U kunt een referentie-implementatie van de portal bouwen en implementeren met behulp van code in de startersopslagplaats van de API Center-portal. De portal maakt gebruik van de Azure API Center-gegevensvlak-API om gegevens op te halen uit uw API-centrum. Gebruikerstoegang tot API-gegevens is gebaseerd op op rollen gebaseerd toegangsbeheer van Azure.

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.

Vereisten

  • Een API-centrum in uw Azure-abonnement. Als u er nog geen hebt gemaakt, raadpleegt u 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.

  1. Navigeer in Azure Portal naar Microsoft Entra-id> App-registraties.

  2. Selecteer + Nieuwe registratie.

  3. Stel op de pagina Een toepassing registreren de waarden als volgt in:

    • Naam instellen op een betekenisvolle naam, zoals api-center-portal

    • Selecteer onder Ondersteunde accounttypen accounts in deze organisatiemap (één tenant).

    • Selecteer in omleidings-URI de optie Spa (Single Page Application) en stel de URI in.

      • Voor lokale tests stelt u de URI in op https://localhost:5173.
      • Voor productie stelt u de URI in op de URI van uw API Center-portalimplementatie.

    • Selecteer Registreren.

  4. Kopieer op de pagina Overzicht de toepassings-id (client) en de map-id (tenant). U stelt deze waarden in wanneer u de portal bouwt.

  5. Selecteer + Een machtiging toevoegen op de pagina API-machtigingen.

    1. Selecteer op de pagina Api-machtigingen aanvragen de API's die mijn organisatie gebruikt . Zoek en selecteer Azure API Center. U kunt ook de toepassings-id c3ca1a77-7a87-4dba-b8f8-eea115ae4573zoeken en selecteren.
    2. Selecteer user_impersonation op de pagina Machtigingen aanvragen.
    3. Selecteer Machtigingen toevoegen.

    De Azure API Center-machtigingen worden weergegeven onder Geconfigureerde machtigingen.

    Schermopname van de vereiste machtigingen in de registratie van de Microsoft Entra ID-app in de portal.

Lokale omgeving configureren

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

  1. Kloon de startersopslagplaats van de API Center-portal naar uw lokale computer.

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

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

    cd APICenter-Portal-Starter

  3. Bekijk de hoofdbranch.

    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:

    • Vervang <service name> en <region> door de naam van uw API-centrum en de regio waar deze is geïmplementeerd
    • Vervang en <tenant ID> door <client ID> de id van de toepassing (client) en de map-id (tenant) van de app-registratie die u in de vorige sectie hebt gemaakt.
    • Werk de waarde bij van title een naam die u wilt weergeven in de portal.
    {
  "dataApiHostName": "<service name>.data.<region>.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 op Azure

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

Aanmeldingsportal inschakelen door Microsoft Entra-gebruikers en -groepen

Gebruikers moeten zich aanmelden om de API's in uw API-centrum te zien. Als u aanmelding wilt inschakelen, wijst u de azure API Center-gegevenslezerrol toe aan gebruikers of groepen in uw organisatie, die zijn afgestemd op 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 Portal voor 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:
    • Zoek en selecteer Azure API Center Data Reader op de pagina Rol. Selecteer Volgende.
    • Selecteer op de pagina Leden bij Toegang toewijzen aan, gebruiker, groep of service-principal>+ Leden selecteren.
    • 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.
    • 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 ID voor 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.

Probleemoplossing

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 rol Gegevenslezer van Azure API Center 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 en moet u de resourceprovider mogelijk 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 rol Gegevenslezer van Azure API Center is toegewezen, de aanmeldingsstroom niet kunnen voltooien nadat ze Aanmelden hebben geselecteerd in de API Center-portal, 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, 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 startersopslagplaats van de API Center-portal.

Gerelateerde inhoud