Synchronize APIs from an API Management instance (preview)

This article shows how to integrate an API Management instance so that the instances's APIs are continuously kept up to date in your API center inventory.

About integrating an API Management instance

Although you can use the Azure CLI to import APIs on demand from Azure API Management to Azure API Center, integrating (linking) an API Management instance enables continuous synchronization so that the API inventory stays up to date. Azure API Center can also synchronize APIs from sources including Amazon API Gateway.

When you integrate an API Management instance as an API source, the following happens:

1. All APIs, and optionally API definitions (specs), from the API Management instance are added to the API center inventory.
2. You configure an environment of type Azure API Management in the API center.
3. An associated deployment is created for each synchronized API definition from API Management.

API Management APIs automatically synchronize to the API center whenever existing APIs' settings change (for example, new versions are added), new APIs are created, or APIs are deleted. This synchronization is one-way from API Management to your Azure API center, meaning API updates in the API center aren't synchronized back to the API Management instance.

Note

• Integration of Azure API Management is currently in preview.
• There are limits for the number of integrated API Management instances (API sources).
• API updates in API Management typically synchronize to your API center within minutes, but synchronization can take up to 24 hours.
• API definitions also synchronize to the API center if you select the option to include them during integration.

Entities synchronized from API Management

You can add or update metadata properties and documentation to the synchronized APIs in your API center to help stakeholders discover, understand, and consume the APIs. Learn more about Azure API Center's built-in and custom metadata properties.

The following table shows entity properties that can be modified in Azure API Center and properties that are set based on their values in the API source.

Entity	Properties configurable in API Center	Properties determined in integrated API source
API	summary lifecycleStage termsOfService license externalDocumentation customProperties	title description kind
API version	lifecycleStage	title definitions (if synchronized)
Environment	title description kind server.managementPortalUri onboarding customProperties	server.type
Deployment	title description server state customProperties	server.runtimeUri

Note

Resource and system IDs for entities synchronized to Azure API Center are automatically generated and can't be changed.

Prerequisites

• An API center in your Azure subscription. If you haven't created one, see Quickstart: Create your API center.

• An Azure API Management instance, in the same or a different subscription. The instance must be in the same directory.

• For Azure CLI:

  • Use the Bash environment in Azure Cloud Shell. For more information, see Quickstart for Bash in Azure Cloud Shell.

    

  • If you prefer to run CLI reference commands locally, install the Azure CLI. If you're running on Windows or macOS, consider running Azure CLI in a Docker container. For more information, see How to run the Azure CLI in a Docker container.

    • If you're using a local installation, sign in to the Azure CLI by using the az login command. To finish the authentication process, follow the steps displayed in your terminal. For other sign-in options, see Sign in with the Azure CLI.

    • When you're prompted, install the Azure CLI extension on first use. For more information about extensions, see Use extensions with the Azure CLI.

    • Run az version to find the version and dependent libraries that are installed. To upgrade to the latest version, run az upgrade.

  Note

  az apic commands require the apic-extension Azure CLI extension. If you haven't used az apic commands, the extension can be installed dynamically when you run your first az apic command, or you can install the extension manually. Learn more about Azure CLI extensions.

  See the release notes for the latest changes and updates in the apic-extension. Certain features may require a preview or specific version of the extension.

  Note

  Azure CLI command examples in this article can run in PowerShell or a bash shell. Where needed because of different variable syntax, separate command examples are provided for the two shells.

Enable a managed identity in your API center

For this scenario, your API center uses a managed identity to access Azure resources. Depending on your needs, enable either a system-assigned or one or more user-assigned managed identities.

The following examples show how to enable a system-assigned managed identity by using the Azure portal or the Azure CLI. At a high level, configuration steps are similar for a user-assigned managed identity.

Portal

1. In the portal, navigate to your API center.
2. In the left menu, under Security, select Managed identities.
3. Select System assigned, and set the status to On.
4. Select Save.

Azure CLI

Set the system-assigned identity in your API center using the following az apic update command. Substitute the names of your API center and resource group:

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

Assign the managed identity the API Management Service Reader role

To allow import of APIs, assign your API center's managed identity the API Management Service Reader role in your API Management instance. You can use the portal or the Azure CLI.

Portal

1. In the portal, navigate to your API Management instance.
2. In the left menu, select Access control (IAM).
3. Select + Add role assignment.
4. On the Add role assignment page, set the values as follows:
   1. On the Role tab, select API Management Service Reader.
   2. On the Members tab, in Assign access to - Select Managed identity > + Select members.
   3. On the Select managed identities page, select the system-assigned managed identity of your API center that you added in the previous section. Click Select.
   4. Select Review + assign.

Azure CLI

1. Get the principal ID of the identity. For a system-assigned identity, use the az apic show command.

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

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

2. Get the resource ID of your API Management instance using the az apim show command.

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

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

3. Assign the managed identity the API Management Service Reader role in your API Management instance using the az role assignment create command.

   #! /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 
   

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

Integrate an API Management instance

You can integrate an API Management instance using the portal or the Azure CLI.

Portal

1. In the portal, navigate to your API center.
2. Under Assets, select Environments.
3. Select Links (preview) > + Create a link.
4. In the Link your Azure API Management Service page:
   1. Select the Subscription, Resource group, and Azure API Management service that you want to integrate.
   2. In Link details, enter an identifier.
   3. In Environment details, enter an Environment title (name), Environment type, and optional Description.
   4. In API Details:
      1. Select a Lifecycle for the synchronized APIs. (You can update this value for the APIs after they're added to your API center.)
      2. Optionally, select whether to include API definitions with the synchronized APIs.
5. Select Create.

Azure CLI

Run the az apic integration create apim command to integrate an API Management instance to your API center.

• Provide the names of the resource group, API center, and integration.

• If the API Management instance and the API center are in the same resource group, you can provide the API Management instance name as the value of azure-apim; otherwise, provide the Azure resource ID.

az apic integration create apim \
    --resource-group <resource-group-name> \
    --service-name <api-center-name> \
    --integration-name <apim-integration-name> \
    --azure-apim <apim-instance-name>

The environment is added in your API center. The API Management APIs are imported to the API center inventory.

Delete an integration

While an API source is integrated, you can't delete synchronized APIs from your API center. If you need to, you can delete the integration. When you delete an integration:

• The synchronized APIs in your API center inventory are deleted
• The environment and deployments associated with the API source are deleted

You can delete an integration using the portal or the Azure CLI.

Portal

1. In the portal, navigate to your API center.
2. Under Assets, select Environments > Links (preview).
3. Select the link, and then select Delete (trash can icon).

Azure CLI

Run the az apic integration delete (preview) command to delete an integration. Provide the names of the resource group, API center, and integration.

az apic integration delete \
    --resource-group <resource-group-name> \
    --service-name <api-center-name> \
    --integration-name <integration-name> \

Related content

• Manage API inventory with Azure CLI commands
• Import APIs from API Management to your Azure API center
• Azure API Management documentation