从 API 管理实例同步 API（预览版）

2025-06-05

本文介绍如何集成 API 管理实例，以便实例的 API 在 API 中心库存中持续保持最新状态。

小窍门

本文介绍如何从 API 中心集成 API 管理实例。或者，直接从 API 管理实例快速设置集成。在实例的左侧菜单中，在 API 下，选择 API 中心，然后在订阅中选择目标 API 中心以将 API 同步到。

关于集成 API 管理实例

尽管可以使用 Azure CLI 按需将 API 从 Azure API 管理导入到 Azure API 中心，但集成（链接）API 管理实例可实现持续同步，以便 API 库存保持最新状态。 Azure API 中心还可以从包括 Amazon API 网关在内的源同步 API。

在集成 API 管理实例作为 API 源时，会发生以下情况：

API 管理实例中的所有 API 以及可选的 API 定义（规范）都添加到 API 中心库存中。
请在 API 中心配置“Azure API 管理”类型的环境。
为每个从 API 管理同步的 API 定义创建关联的部署。

更改现有 API 的设置（例如，添加新版本）、创建新 API 或删除 API 时，API 管理 API 会自动同步到 API 中心。此同步是从 API 管理到 Azure API 中心的单向同步，这意味着 API 中心内的 API 更新不会同步回 API 管理实例。

注意

Azure API 管理的集成目前为预览版。
集成的 API 管理实例（API 源）的数量存在限制。
API 管理中的 API 更新通常在几分钟内同步到 API 中心，但同步可能需要长达 24 小时。
如果你在集成期间选择了包含 API 定义的选项，那么 API 定义也会同步到 API 中心。

从 API 管理同步的实体

你可以在 API 中心中为同步的 API 添加或更新元数据属性和文档，以帮助利益干系人发现、了解和使用这些 API。详细了解 Azure API 中心的内置和自定义元数据属性。

下表显示了可以在 Azure API 中心中修改的实体属性，以及根据 API 源中的值设置的属性。

实体	可在 API 中心配置的属性	在集成 API 源中确定的属性
API（应用程序编程接口）	摘要生命周期阶段服务条款许可证外部文档 customProperties	title 描述 kind
API 版本	生命周期阶段	title 定义（如果已同步）
环境	title 描述 kind server.managementPortalUri 加入 customProperties	服务器.类型
部署	title 描述服务器州 customProperties	server.runtimeUri

注意

同步到 Azure API 中心的实体的资源 ID 和系统 ID 是自动生成的，无法更改。

先决条件

Azure 订阅中的 API 中心。如果尚未创建 API 中心，请参阅快速入门：创建 API 中心。
相同或不同订阅中的 Azure API 管理实例。此实例必须位于同一目录中。
对于 Azure CLI：
- 在 Azure Cloud Shell 中使用 Bash 环境。有关详细信息，请参阅 Azure Cloud Shell 入门。
- 如需在本地运行 CLI 参考命令，请安装 Azure CLI。如果在 Windows 或 macOS 上运行，请考虑在 Docker 容器中运行 Azure CLI。有关详细信息，请参阅如何在 Docker 容器中运行 Azure CLI。
  - 如果使用的是本地安装，请使用 az login 命令登录 Azure CLI。若要完成身份验证过程，请遵循终端中显示的步骤。有关其他登录选项，请参阅使用 Azure CLI 向 Azure 进行身份验证。
  - 出现提示时，请在首次使用时安装 Azure CLI 扩展。有关扩展的详细信息，请参阅使用和管理 Azure CLI 中的扩展。
  - 运行 az version 以查找安装的版本和依赖库。若要升级到最新版本，请运行 az upgrade。
注意

az apic 命令需要 Azure CLI 扩展 apic-extension。如果尚未使用 az apic 命令，则可以在运行第一个 az apic 命令时动态安装扩展，也可以手动安装扩展。详细了解 Azure CLI 扩展。

请参阅最新更改的发行说明和 apic-extension 中的更新。某些功能可能需要预览版或特定版本的扩展。

注意

本文中的 Azure CLI 命令示例可以在 PowerShell 或 bash shell 中运行。由于不同的变量语法，需要为两个 shell 提供单独的命令示例。

在 API 中心中启用托管标识

对于此场景，你的 API 中心使用托管标识来访问 Azure 资源。根据你的需要，启用一个系统分配的托管标识或一个或多个用户分配的托管标识。

下面的示例展示了如何使用 Azure 门户或 Azure CLI 启用系统分配的托管标识。概括而言，配置步骤与用户分配的托管标识类似。

门户
Azure CLI

在门户中，导航到你的 API 中心。
在左侧菜单中，在“安全性”下，选择“托管标识”。
选择“系统已分配”，并将状态设置为“开”。
选择“保存”。

使用以下 az apic update 命令在 API 中心设置系统分配的标识。替换 API 中心和资源组的名称：

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

为托管标识分配 API 管理服务读者角色

要允许导入 API，请在 API 管理实例中为 API 中心的托管身份分配 API 管理服务读者角色。可以使用门户或 Azure CLI。

门户
Azure CLI

在门户中导航到 API 管理实例。
在左侧菜单中，选择“访问控制(IAM)”。
选择“+ 添加角色分配”。
在“添加角色分配”页面上，按如下所示设置值：
1. 在“角色”选项卡上，选择“API 管理服务读者”。
2. 在“成员”页上的“访问权限分配对象”中，选择“托管标识”>“+ 选择成员”。
3. 在“选择托管标识”页上，选择你在上一部分中添加的 API 中心的系统分配托管标识。单击“选择”。
4. 选择“查看 + 分配”。

获取标识的主体 ID。对于系统分配的标识，请使用 az apic show 命令。

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

使用 az apim show 命令获取 API 管理实例的资源 ID。

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

使用 az role assignment create 命令在 API 管理实例中为托管标识分配 API 管理服务读者角色。

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

集成 API 管理实例

可以使用门户或 Azure CLI 集成 API 管理实例。

门户
Azure CLI

在门户中，导航到你的 API 中心。
在 “平台”下，选择 “集成”。
从 Azure API 管理中选择“+ 新建集成>”。
在 “集成 Azure API 管理服务 ”页中：
1. 选择要集成的“订阅”、“资源组”和“Azure API 管理服务”。
2. 在 集成详细信息中，输入标识符。如果尚未配置有权访问 API 管理实例的托管标识，请启用 “自动配置托管标识”并分配权限。此选择会自动为 API 中心的系统分配的托管标识分配从 API 管理实例同步 API 所需的权限。
3. 在“环境详细信息”中，输入“环境标题”（名称）、“环境类型”和“说明”（可选）。
4. 在“API 详细信息”中：
  1. 为同步的 API 选择“生命周期”。（将 API 添加到 API 中心后，可以更新 API 的该值。）
  2. （可选）选择是否使用同步的 API 包含 API 定义。
选择创建。

在门户中集成 Azure API 管理服务的屏幕截图。

运行 az apic integration create apim 命令，将 API 管理实例集成到 API 中心。

提供资源组、API 中心和集成的名称。
如果 API 管理实例和 API 中心位于同一资源组中，则可以提供 API 管理实例名称作为 azure-apim 的值；否则，请提供 Azure 资源 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>

该环境已添加到 API 中心。 API 管理 API 被导入到 API 中心库存中。

门户中的环境列表的屏幕截图。

删除集成

在集成 API 源期间，你无法从 API 中心删除已同步的 API。可以根据需要删除集成。删除集成时：

API 中心清单中同步的 API 会被删除
与 API 源关联的环境和部署会被删除

可以使用门户或 Azure CLI 删除集成。

门户
Azure CLI

在门户中，导航到你的 API 中心。
在“资产”下，选择“环境>集成”（预览版）。
选择集成，然后选择“ 删除 ”（垃圾桶图标）。

运行 az apic integration delete（预览版）命令以删除集成。提供资源组、API 中心和集成的名称。

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

通过