Delen via

Api Center-platformcatalogus voor Azure API Center inschakelen en weergeven

  • Artikel

In dit artikel wordt beschreven hoe u zakelijke ontwikkelaars toegang kunt bieden tot de API-catalogus van het Azure API Center-platform (preview) in de Visual Studio Code-extensie voor Azure API Center. Met behulp van de platform-API-catalogus kunnen ontwikkelaars API's detecteren in uw Azure API-centrum, API-definities weergeven en optioneel API-clients genereren wanneer ze geen toegang hebben om het API-centrum zelf te beheren of API's toe te voegen aan de inventaris. Toegang tot de api-catalogus van het platform wordt beheerd met behulp van Microsoft Entra ID en op rollen gebaseerd toegangsbeheer van Azure.

Tip

De Visual Studio Code-extensie biedt meer functies voor API-ontwikkelaars die gemachtigd zijn om een Azure API-centrum te beheren. API-ontwikkelaars kunnen bijvoorbeeld API's rechtstreeks in het API-centrum registreren of CI/CD-pijplijnen gebruiken. Meer informatie

Vereisten

Voor beheerders van API-centrum

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

Voor app-ontwikkelaars

  • Azure API Center-extensie voor Visual Studio Code

    Belangrijk

    Op dit moment is de toegang tot de api-catalogus van het platform alleen beschikbaar in de voorlopige versie van de extensie. Wanneer u de extensie installeert vanuit Visual Studio Code Marketplace, kunt u ervoor kiezen om de releaseversie of een voorlopige versie te installeren. Schakel op elk gewenst moment tussen de twee versies met behulp van het contextmenu voor de knop Beheren van de extensie in de weergave Extensies.

De volgende Visual Studio Code-extensie is optioneel:

Stappen voor BEHEERDERS van API-centrum om toegang tot catalogus in te schakelen

De volgende secties bevatten stappen voor BEHEERDERS van HET API-centrum om bedrijfsontwikkelaars toegang te geven tot de platform-API-catalogus.

Microsoft Entra-app-registratie maken

Configureer eerst een app-registratie in uw Microsoft Entra ID-tenant. Met de app-registratie kan de Visual Studio Code-extensie voor Azure API Center toegang krijgen tot de platform-API-catalogus 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 platform-api-catalog
    • Selecteer onder Ondersteunde accounttypen accounts in deze organisatiemap (één tenant).
    • Selecteer in omleidings-URI de optie Toepassing met één pagina (SPA) en stel de URI in op de runtime-URI van uw API-centrum. Bijvoorbeeld: https://<service name>.data.<region>.azure-apicenter.ms. Voorbeeld: https://contoso-apic.data.eastus.azure-apicenter.ms.
    • Selecteer Registreren.

    Tip

    U kunt dezelfde app-registratie gebruiken voor toegang tot meer API-centra. Ga in omleidings-URI door met het toevoegen van omleidings-URI's voor andere API-centra die u wilt weergeven in de platform-API-catalogus.

  4. Kopieer op de pagina Overzicht de toepassings-id (client) en de map-id (tenant). U stelt deze waarden later in wanneer u vanuit de Visual Studio Code-extensie verbinding maakt met het API-centrum.

  5. Selecteer in het linkermenu onder Beheren de optie Authentication>+ Add a platform.

  6. Selecteer op de pagina Platformen configureren de optie Mobiele en bureaubladtoepassingen.

  7. Voer op de pagina Desktop + apparaten configureren de volgende omleidings-URI in en selecteer Configureren:

    https://vscode.dev/redirect

  8. Selecteer in het linkermenu onder Beheren API-machtigingen>+ Een machtiging toevoegen.

  9. Ga als volgt te werk op de pagina API-machtigingen aanvragen:

    1. Selecteer de API's die door mijn organisatie worden gebruikt .
    2. Zoek en selecteer Azure API Center. U kunt ook de toepassings-id c3ca1a77-7a87-4dba-b8f8-eea115ae4573zoeken en selecteren.
    3. Selecteer user_impersonation op de pagina Machtigingen selecteren.
    4. 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.

Aanmelden inschakelen voor platform-API-catalogus door Microsoft Entra-gebruikers en -groepen

Bedrijfsontwikkelaars moeten zich aanmelden met een Microsoft-account om de platform-API-catalogus voor uw API-centrum weer te geven. Voeg indien nodig ontwikkelaars toe aan of nodig ze uit voor uw Microsoft Entra-tenant.

Als u vervolgens aanmelding wilt inschakelen, wijst u de azure API Center-gegevenslezerrol toe aan gebruikers of groepen in uw tenant, 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 platform-API-catalogus van de API-extensie van API Center. 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.
  4. Herhaal de voorgaande stappen om aanmelding in te schakelen bij de platform-API-catalogus voor meer API-centra.

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.

Stappen voor bedrijfsontwikkelaars voor toegang tot de platform-API-catalogus

Ontwikkelaars kunnen deze stappen volgen om verbinding te maken en u aan te melden om een platform-API-catalogus weer te geven met behulp van de Visual Studio Code-extensie. Instellingen om verbinding te maken met het API-centrum moeten worden verstrekt door de beheerder van het API-centrum.

Verbinding maken met een API-centrum

  1. Installeer de voorlopige versie van de Azure API Center-extensie voor Visual Studio Code voor Visual Studio Code voor Visual Studio Code.

  2. Selecteer API Center in Visual Studio Code in de activiteitenbalk aan de linkerkant.

    Schermopname van het API Center-pictogram op de activiteitenbalk.

  3. Gebruik de sneltoets Ctrl+Shift+P om het opdrachtenpalet te openen. Typ Azure API Center: maak verbinding met een API Center en druk op Enter.

  4. Beantwoord de aanwijzingen om de volgende informatie in te voeren:

    1. De runtime-URL van uw API-centrum, in de indeling <service name>.data.<region>.azure-apicenter.ms (geen voorvoegsel met https://). Voorbeeld: contoso-apic.data.eastus.azure-apicenter.ms. Deze runtime-URL wordt weergegeven op de pagina Overzicht van het API-centrum in Azure Portal.
    2. De toepassings-id (client) van de app-registratie die is geconfigureerd door de beheerder in de vorige sectie.
    3. De map-id (tenant) van de app-registratie die is geconfigureerd door de beheerder in de vorige sectie.

    Tip

    Een BEHEERDER van het API-centrum moet deze verbindingsgegevens verstrekken aan ontwikkelaars of een directe koppeling in de volgende indeling opgeven:
    vscode://apidev.azure-api-center?clientId=<Client ID>&tenantId=<tenant ID>&runtimeUrl=<service-name>.data.<region>.azure-apicenter.ms

    Nadat u verbinding hebt gemaakt met het API-centrum, wordt de naam van het API-centrum weergegeven in de API-catalogus van het API Center-platform.

  5. Als u de API's in het API-centrum wilt weergeven, selecteert u Aanmelden bij Azure onder de naam van het API-centrum. Aanmelden is toegestaan met een Microsoft-account waaraan de rol Azure API Center-gegevenslezer is toegewezen in het API-centrum.

    Schermopname van api Center-platform-API-catalogus in VS Code-extensie.

  6. Nadat u zich hebt aangemeld, selecteert u API's om de API's in het API-centrum weer te geven. Vouw een API uit om de versies en definities ervan te verkennen.

    Schermopname van API Center-platform-API-catalogus met API's in VS Code-extensie.

  7. Herhaal de voorgaande stappen om verbinding te maken met meer API-centra als de toegang is geconfigureerd.

API's in de catalogus detecteren en gebruiken

De platform-API-catalogus helpt ontwikkelaars bij het detecteren van API-details en het starten van api-clientontwikkeling. Ontwikkelaars hebben toegang tot de volgende functies door met de rechtermuisknop te klikken op een API-definitie in de platform-API-catalogus:

  • Api-specificatiedocument exporteren - Een API-specificatie exporteren uit een definitie en deze vervolgens downloaden als een bestand
  • API-client genereren - De Microsoft Kiota-extensie gebruiken om een API-client te genereren voor hun favoriete taal
  • Markdown genereren - API-documentatie genereren in Markdown-indeling
  • OpenAPI-documentatie - Bekijk de documentatie voor een API-definitie en probeerbewerkingen in een Swagger-gebruikersinterface (alleen beschikbaar voor OpenAPI-definities)

Probleemoplossing

Onder bepaalde voorwaarden kan een gebruiker het volgende foutbericht tegenkomen nadat hij zich heeft aangemeld bij de API-catalogus van het API Center-platform en de API-lijst voor een API-centrum heeft uitgebreid:

Error: Cannot read properties of undefined (reading 'nextLink')

Controleer of de gebruiker de rol Gegevenslezer van Azure API Center heeft toegewezen in het API-centrum. Wijs de rol indien nodig opnieuw toe aan de gebruiker. Vernieuw vervolgens de API-catalogus van het API Center-platform in de Visual Studio Code-extensie.

Kan niet aanmelden bij Azure

Als gebruikers aan wie de rol Gegevenslezer van Azure API Center is toegewezen, de aanmeldingsstroom niet kunnen voltooien nadat ze Aanmelden bij Azure hebben geselecteerd in de platform-API-catalogus, kan er een probleem zijn met de configuratie van de verbinding.

Controleer de instellingen in de app-registratie die u hebt geconfigureerd in Microsoft Entra-id. Bevestig de waarden van de toepassings-id (client) en de map-id (tenant) in de app-registratie en de runtime-URL van het API-centrum. Stel vervolgens de verbinding met het API-centrum opnieuw in.

Kan azure API Center-machtigingen niet selecteren in de registratie van de Microsoft Entra ID-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.

Gerelateerde inhoud