API's importeren in uw API-centrum vanuit Azure API Management

In dit artikel wordt beschreven hoe u API's importeert (toevoegt) vanuit een Azure API Management-exemplaar naar uw API-centrum met behulp van de Azure CLI. Door API's van API Management toe te voegen aan uw API-inventaris, kunnen ze worden gedetecteerd en toegankelijk voor ontwikkelaars, API-programmamanagers en andere belanghebbenden in uw organisatie.

In dit artikel worden twee opties beschreven voor het gebruik van de Azure CLI om API's toe te voegen aan uw API-centrum vanuit API Management:

• Optie 1 : exporteer een API-definitie vanuit een API Management-exemplaar met behulp van de opdracht az apim api export . Importeer vervolgens de definitie in uw API-centrum.

  Mogelijke manieren om een API-definitie te importeren die uit API Management wordt geëxporteerd, zijn onder andere:

  • Voer az apic API register uit om een nieuwe API te registreren in uw API-centrum.
  • Voer az apic api definition import-specification uit om de API-definitie te importeren in een bestaande API.

• Optie 2 : importeer API's rechtstreeks vanuit API Management naar uw API-centrum met behulp van de opdracht az apic import-from-apim .

Nadat u API-definities of API's uit API Management hebt geïmporteerd, kunt u metagegevens en documentatie toevoegen in uw API-centrum om belanghebbenden te helpen de API te detecteren, begrijpen en gebruiken.

Vereisten

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

• Een of meer exemplaren van Azure API Management, in hetzelfde of een ander abonnement. Wanneer u API's rechtstreeks vanuit API Management importeert, moeten het API Management-exemplaar en HET API-centrum zich in dezelfde map bevinden. Zie Een Azure API Management-exemplaar maken als u er nog geen hebt gemaakt.

• Een of meer API's die worden beheerd in uw API Management-exemplaar dat u wilt toevoegen aan uw API-centrum.

• Voor Azure CLI:

  • Gebruik de Bash-omgeving in Azure Cloud Shell. Zie quickstart voor Bash in Azure Cloud Shell voor meer informatie.

    

  • Installeer de Azure CLI, indien gewenst, om CLI-referentieopdrachten uit te voeren. Als u in Windows of macOS werkt, kunt u Azure CLI uitvoeren in een Docker-container. Zie De Azure CLI uitvoeren in een Docker-container voor meer informatie.

    • Als u een lokale installatie gebruikt, meldt u zich aan bij Azure CLI met behulp van de opdracht az login. Volg de stappen die worden weergegeven in de terminal, om het verificatieproces te voltooien. Raadpleeg Aanmelden bij Azure CLI voor aanvullende aanmeldingsopties.

    • Installeer de Azure CLI-extensie bij het eerste gebruik, wanneer u hierom wordt gevraagd. Raadpleeg Extensies gebruiken met Azure CLI voor meer informatie over extensies.

    • Voer az version uit om de geïnstalleerde versie en afhankelijke bibliotheken te vinden. Voer az upgrade uit om te upgraden naar de nieuwste versie.

  Notitie

  az apic voor opdrachten is de apic-extension Azure CLI-extensie vereist. Als u geen opdrachten hebt gebruikt az apic , kan de extensie dynamisch worden geïnstalleerd wanneer u uw eerste az apic opdracht uitvoert of kunt u de extensie handmatig installeren. Meer informatie over Azure CLI-extensies.

  Zie de releaseopmerkingen voor de meest recente wijzigingen en updates in de apic-extension.

  Notitie

  Voorbeelden van Azure CLI-opdrachten in dit artikel kunnen worden uitgevoerd in PowerShell of een bash-shell. Indien nodig vanwege verschillende syntaxis van variabelen, worden er afzonderlijke opdrachtvoorbeelden gegeven voor de twee shells.

Optie 1: Een API-definitie exporteren vanuit API Management en deze importeren in uw API-centrum

Exporteer eerst een API van uw API Management-exemplaar naar een API-definitie met behulp van de opdracht az apim api export . Afhankelijk van uw scenario kunt u de API-definitie exporteren naar een lokaal bestand of een URL.

API exporteren naar een lokaal API-definitiebestand

Met de volgende voorbeeldopdracht wordt de API met id my-API geëxporteerd in het exemplaar van myAPIManagement van de API. De API wordt geëxporteerd in OpenApiJson-indeling naar een lokaal OpenAPI-definitiebestand op het pad dat u opgeeft.

#! /bin/bash
az apim api export --api-id my-api --resource-group myResourceGroup \
    --service-name myAPIManagement --export-format OpenApiJsonFile \
    --file-path "/path/to/folder"

#! PowerShell syntax
az apim api export --api-id my-api --resource-group myResourceGroup `
    --service-name myAPIManagement --export-format OpenApiJsonFile `
    --file-path '/path/to/folder'

API exporteren naar een URL

In het volgende voorbeeld exporteert az apim api export de API met id my-api in OpenApiJson-indeling naar een URL in Azure Storage. De URL is ongeveer 5 minuten beschikbaar. Hier wordt de waarde van de URL opgeslagen in de variabele $link .

#! /bin/bash
link=$(az apim api export --api-id my-api --resource-group myResourceGroup \
    --service-name myAPIManagement --export-format OpenApiJsonUrl --query properties.value.link \
    --output tsv)

# PowerShell syntax
$link=$(az apim api export --api-id my-api --resource-group myResourceGroup `
    --service-name myAPIManagement --export-format OpenApiJsonUrl --query properties.value.link `
    --output tsv)

API registreren in uw API-centrum vanuit geëxporteerde API-definitie

U kunt een nieuwe API registreren in uw API-centrum vanuit de geëxporteerde definitie met behulp van de opdracht az apic api register .

In het volgende voorbeeld wordt een API in het myAPICenter-API-centrum geregistreerd vanuit een lokaal OpenAPI-definitiebestand met de naam definitionFile.json.

az apic api register --resource-group myResourceGroup --service-name myAPICenter --api-location "/path/to/definitionFile.json"

API-definitie importeren in een bestaande API in uw API-centrum

In het volgende voorbeeld wordt de opdracht az apic api definition import-specification gebruikt om een API-definitie te importeren in een bestaande API in het myAPICenter API-centrum. Hier wordt de API-definitie geïmporteerd uit een URL die is opgeslagen in de $link variabele.

In dit voorbeeld wordt ervan uitgegaan dat u een API hebt met de naam mijn-API en een bijbehorende API-versie v1-0-0 en openapi voor definitie-entiteiten in uw API-centrum. Als u dit niet doet, raadpleegt u API's toevoegen aan uw API-centrum.

#! /bin/bash
az apic api definition import-specification \
    --resource-group myResourceGroup --service-name myAPICenter \
    --api-id my-api --version-id v1-0-0 \
    --definition-id openapi --format "link" --value '$link' \
    --specification '{"name":"openapi","version":"3.0.2"}'

# PowerShell syntax
az apic api definition import-specification `
    --resource-group myResourceGroup --service-name myAPICenter `
    --api-id my-api --version-id v1-0-0 `
    --definition-id openapi --format "link" --value '$link' `
    --specification '{"name":"openapi","version":"3.0.2"}'

Optie 2: API's rechtstreeks vanuit uw API Management-exemplaar importeren

Hier volgen de stappen voor het importeren van API's uit uw API Management-exemplaar naar uw API-centrum met behulp van de opdracht az apic import-from-apim . Deze opdracht is handig als u meerdere API's uit API Management wilt importeren in uw API-centrum, maar u kunt deze ook gebruiken om één API te importeren.

Wanneer u API's vanuit een API Management-exemplaar toevoegt aan uw API-centrum met behulp van az apic import-from-apim, gebeurt het volgende automatisch:

• De versies, definities en implementatiegegevens van elke API worden gekopieerd naar uw API-centrum.
• De API ontvangt een door het systeem gegenereerde API-naam in uw API-centrum. De weergavenaam (titel) van API Management blijft behouden.
• De levenscyclusfase van de API is ingesteld op Ontwerpen.
• Azure API Management wordt toegevoegd als een omgeving.

Een beheerde identiteit toevoegen in uw API-centrum

Voor dit scenario gebruikt uw API-centrum een beheerde identiteit voor toegang tot API's in uw API Management-exemplaar. Afhankelijk van uw behoeften configureert u een door het systeem toegewezen of een of meer door de gebruiker toegewezen beheerde identiteiten.

In de volgende voorbeelden ziet u hoe u een door het systeem toegewezen beheerde identiteit configureert met behulp van Azure Portal of de Azure CLI. Op hoog niveau zijn configuratiestappen vergelijkbaar voor een door de gebruiker toegewezen beheerde identiteit.

Portal

1. Navigeer in de portal naar uw API-centrum.
2. Selecteer beheerde identiteiten in het linkermenu onder Beveiliging.
3. Selecteer Systeem toegewezen en stel de status in op Aan.
4. Selecteer Opslaan.

Azure-CLI

Stel de door het systeem toegewezen identiteit in uw API-centrum in met behulp van de volgende az apic update-opdracht . Vervang de namen van uw API-centrum en resourcegroep:

az apic update --name <api-center-name> --resource-group <resource-group-name> --identity '{"type": "SystemAssigned"}'

De rol API Management Service Reader toewijzen aan de beheerde identiteit

Als u het importeren van API's wilt toestaan, wijst u de beheerde identiteit van uw API Center toe aan de rol API Management-servicelezer in uw API Management-exemplaar. U kunt de portal of de Azure CLI gebruiken.

Portal

1. Navigeer in de portal naar uw API Management-exemplaar.
2. Selecteer toegangsbeheer (IAM) in het linkermenu.
3. Selecteer + Roltoewijzing toevoegen.
4. Stel op de pagina Roltoewijzing toevoegen de waarden als volgt in:
   1. Selecteer API Management Service Reader op het tabblad Rol.
   2. Op het tabblad Leden, in Toegang toewijzen aan - Beheerde identiteit> selecteren+ Leden selecteren.
   3. Selecteer op de pagina Beheerde identiteiten selecteren: selecteer de door het systeem toegewezen beheerde identiteit van uw API-centrum dat u in de vorige sectie hebt toegevoegd. Klik op Selecteren.
   4. Selecteer Controleren + toewijzen.

Azure-CLI

1. Haal de principal-id van de identiteit op. Gebruik de opdracht az apic show voor een door het systeem toegewezen identiteit.

   #! /bin/bash
   apicObjID=$(az apic show --name <api-center-name> \
       --resource-group <resource-group-name> \
       --query "identity.principalId" --output tsv)
   

   # PowerShell syntax
   $apicObjID=$(az apic show --name <api-center-name> `
       --resource-group <resource-group-name> `
       --query "identity.principalId" --output tsv)
   

2. Haal de resource-id van uw API Management-exemplaar op met behulp van de opdracht az apim show .

   #! /bin/bash
   apimID=$(az apim show --name <apim-name> --resource-group <resource-group-name> --query "id" --output tsv)
   

   # PowerShell syntax
   $apimID=$(az apim show --name <apim-name> --resource-group <resource-group-name> --query "id" --output tsv)
   

3. Wijs de beheerde identiteit toe aan de rol API Management Service Reader in uw API Management-exemplaar met behulp van de opdracht az role assignment create .

   #! /bin/bash
   scope="${apimID:1}"
   
   az role assignment create \
       --role "API Management Service Reader Role" \
       --assignee-object-id $apicObjID \
       --assignee-principal-type ServicePrincipal \
       --scope $scope 
   

   #! PowerShell syntax
   $scope=$apimID.substring(1)
   
   az role assignment create `
       --role "API Management Service Reader Role" `
       --assignee-object-id $apicObjID `
       --assignee-principal-type ServicePrincipal `
       --scope $scope 
   

API's importeren uit API Management

Gebruik de opdracht az apic import-from-apim om een of meer API's uit uw API Management-exemplaar te importeren in uw API Center.

Notitie

• Deze opdracht is afhankelijk van een beheerde identiteit die is geconfigureerd in uw API-centrum met leesmachtigingen voor het API Management-exemplaar. Zie Een beheerde identiteit toevoegen in uw API-centrum eerder in dit artikel als u nog geen beheerde identiteit hebt toegevoegd of geconfigureerd.

• Als uw API-centrum meerdere beheerde identiteiten heeft, zoekt de opdracht eerst naar een door het systeem toegewezen identiteit. Als er geen wordt gevonden, wordt de eerste door de gebruiker toegewezen identiteit in de lijst gekozen.

Alle API's importeren uit een API Management-exemplaar

Vervang in de volgende opdracht de namen van uw API-centrum, de resourcegroep van uw API Center, uw API Management-exemplaar en de resourcegroep van uw exemplaar. Gebruik * dit om alle API's op te geven van het API Management-exemplaar.

#! /bin/bash
az apic import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> \
    --apim-name <api-management-name> --apim-resource-group <api-management-resource-group-name> \
    --apim-apis '*'  

# PowerShell syntax
az apic import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> `
    --apim-name <api-management-name> --apim-resource-group <api-management-resource-group-name> `
    --apim-apis '*'  

Notitie

Als uw API Management-exemplaar een groot aantal API's heeft, kan het enige tijd duren voordat u importeert in uw API-centrum.

Een specifieke API importeren uit een API Management-exemplaar

Geef een API op die moet worden geïmporteerd met behulp van de naam van het API Management-exemplaar.

Vervang in de volgende opdracht de namen van uw API-centrum, de resourcegroep van uw API Center, uw API Management-exemplaar en de resourcegroep van uw exemplaar. Geef een API-naam door, zoals petstore-api het gebruik van de --apim-apis parameter.

#! /bin/bash
az apic import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> \
    --apim-name <api-management-name> --apim-resource-group <api-management-resource-group-name> \
    --apim-apis 'petstore-api'        

# PowerShell syntax
az apic import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> `
    --apim-name <api-management-name> --apim-resource-group <api-management-resource-group-name> `
    --apim-apis 'petstore-api'    

Notitie

Geef een API-naam op met behulp van de NAAM van de API-resource in het API Management-exemplaar, niet de weergavenaam. Voorbeeld: petstore-api in plaats van Petstore API.

Nadat u API's hebt geïmporteerd vanuit API Management, kunt u de geïmporteerde API's in uw API-centrum bekijken en beheren.

Gerelateerde inhoud

• Naslaginformatie over Azure CLI voor Azure API Center
• Naslaginformatie over Azure CLI voor API Management
• API-inventaris beheren met Azure CLI-opdrachten
• Azure-rollen toewijzen aan een beheerde identiteit
• Documentatie voor Azure API Management