你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

通过 API 管理将 API 导入 API 中心

本文介绍如何使用 Azure CLI 将 API 从 Azure API 管理实例导入（添加）到 API 中心。 将 API 从 API 管理添加到 API 清单有助于使开发者、API 项目经理和组织中的其他利益相关者可以发现和访问这些 API。

本文介绍了使用 Azure CLI 从 API 管理将 API 添加到 API 中心的两个选项：

• 选项 1 - 使用 az apim api export 命令从 API 管理实例导出 API 定义。 然后，将定义导入 API 中心。

  导入从 API 管理导出的 API 定义的可行方法包括：

  • 运行 az apic api register，在 API 中心注册新 API。
  • 运行 az apic api definition import-specification，将 API 定义导入现有 API。

• 选项 2 - 使用 az apic service import-from-apim 命令直接从 API 管理导入 API 中心。

从 API 管理导入 API 定义或 API 后，可以在 API 中心添加元数据和文档，以帮助利益相关者发现、理解和使用 API。

先决条件

• Azure 订阅中的 API 中心。 如果尚未创建 API 中心，请参阅快速入门：创建 API 中心。

• 同一或不同订阅中的一个或多个 Azure API 管理实例。 直接从 API 管理导入 API 时，API 管理实例和 API 中心必须位于同一目录中。 如果尚未创建 API 管理实例，请参阅创建 Azure API 管理实例。

• 要添加到 API 中心的 API 管理实例中管理的一个或多个 API。

• 对于 Azure CLI：

  • 在 Azure Cloud Shell 中使用 Bash 环境。 有关详细信息，请参阅 Azure Cloud Shell 中的 Bash 快速入门。

    

  • 如需在本地运行 CLI 参考命令，请安装 Azure CLI。 如果在 Windows 或 macOS 上运行，请考虑在 Docker 容器中运行 Azure CLI。 有关详细信息，请参阅如何在 Docker 容器中运行 Azure CLI。

    • 如果使用的是本地安装，请使用 az login 命令登录到 Azure CLI。 若要完成身份验证过程，请遵循终端中显示的步骤。 有关其他登录选项，请参阅使用 Azure CLI 登录。

    • 出现提示时，请在首次使用时安装 Azure CLI 扩展。 有关扩展详细信息，请参阅使用 Azure CLI 的扩展。

    • 运行 az version 以查找安装的版本和依赖库。 若要升级到最新版本，请运行 az upgrade。

  注意

  az apic 命令需要 Azure CLI 扩展 apic-extension。 如果尚未使用 az apic 命令，那么在运行第一个 az apic 命令时，会动态安装该扩展。 详细了解 Azure CLI 扩展。

  注意

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

选项 1：从 API 管理导出 API 定义并将其导入 API 中心

首先，使用 az apim api export 命令将 API 从 API 管理实例导出到 API 定义。 可以将 API 定义导出到本地文件或 URL，视方案而定。

将 API 导出到本地 API 定义文件

以下示例命令在 API 的 myAPIManagement 实例中导出带有标识符 my-api 的 API。 系统会以 OpenApiJson 格式将 API 导出到名为 specificationFile.json 的本地 OpenAPI 定义文件中。

#! /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 导出到 URL

在以下示例中，az apim api export 命令会以 OpenApiJson 格式将带有标识符 my-api 的 API 导出到 Azure 存储中的 URL。 该 URL 的可用时间大约为 5 分钟。 在这一步，系统会将 URL 的值存储在 $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 定义在 API 中心注册 API

可以使用 az apic api register 命令根据导出的定义在 API 中心注册新 API。

以下示例根据名为 definitionFile.json 的本地 OpenAPI 定义文件在 myAPICenter API 中心注册 API。

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

将 API 定义导入 API 中心中的现有 API

以下示例使用 az apic api definition import-specification 命令将 API 定义导入 myAPICenter API 中心中的现有 API。 在这一步，系统是从 $link 变量中存储的 URL 导入的 API 定义。

此示例假设你拥有的 API 名为 my-api，并且 API 中心有关联的 API 版本 v1-0-0 和定义实体 openapi。 如果没有，请参阅将 API 添加到 API 中心。

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

选项 2：直接从 API 管理实例导入 API

以下是使用 az apic service import-from-apim 命令将 API 从 API 管理实例导入到 API 中心的步骤。 要将多个 API 从 API 管理导入到 API 中心时，此命令非常有用，但也可以使用此命令来导入单个 API。

使用 az apic service import-from-apim 将 API 从 API 管理实例添加到 API 中心时，会自动发生以下情况：

• 每个 API 的版本、定义和部署信息都将复制到 API 中心。
• API 会在 API 中心接收系统生成的 API 名称。 保留 API 管理中的显示名称（标题）。
• API 的生命周期阶段设为“设计”。
• 将 Azure API 管理添加为环境。

在 API 中心中添加托管标识

对于此方案，API 中心使用托管标识访问 API 管理实例中的 API。 根据你的需要，配置一个系统分配的托管标识或一个或多个用户分配的托管标识。

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

门户

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

Azure CLI

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

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

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

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

门户

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

Azure CLI

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

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

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

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

   #! /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. 使用 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 
   

   #! 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 管理导入 API

使用 az apic service import-from-apim 命令将一个或多个 API 从 API 管理实例导入 API 中心。

注意

• 此命令取决于 API 中心中配置的托管标识，该标识具有对 API 管理实例的读取权限。 如果尚未添加或配置托管标识，请参阅本文前面所述的向 API 中心添加托管标识。

• 如果 API 中心有多个托管标识，该命令首先搜索系统分配的标识。 如果未找到任何标识，它将选取列表中第一个用户分配的标识。

从 API 管理实例导入所有 API

使用通配符 (*) 指定 API 管理实例中的所有 API。

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

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

2. 使用 az apic service import-from-apim 命令导入 API。 替换 API 中心和资源组的名称，并使用 * 指定 API 管理实例中的所有 API。

   az apic service import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> --source-resource-ids $apimID/apis/*  
   

   注意

   如果 API 管理实例具有大量 API，则导入到 API 中心可能需要一些时间。

从 API 管理实例导入特定 API

使用 API 管理实例中的名称指定要导入的 API。

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

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

2. 使用 az apic service import-from-apim 命令导入 API。 替换 API 中心和资源组的名称，并从 API 管理实例指定 API 名称。

   az apic service import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> --source-resource-ids $apimID/apis/<api-name>    
   

   注意

   使用 API 管理实例中的 API 资源名称指定 <api-name>，而不是显示名称。 例如：petstore-api，而非 Petstore API。

从 API 管理导入 API 后，可以在 API 中心查看和管理导入的 API。

相关内容

• Azure API 中心的 Azure CLI 参考
• 用于 API 管理的 Azure CLI 参考
• 使用 Azure CLI 命令管理 API 清单
• 向托管标识分配 Azure 角色
• Azure API 管理文档