通过 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 import-from-apim 命令直接从 API 管理导入 API 到 API 中心。

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

先决条件

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

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

• 要添加到 API 中心的 API 管理实例中管理的一个或多个 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 提供单独的命令示例。

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

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

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

以下示例命令在 API 的 myAPIManagement 实例中导出带有标识符 my-api 的 API。 API 将以 OpenApiJson 格式导出到指定路径的本地 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"

# Formatted for PowerShell
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 大约五分钟可用。 在这一步，系统会将 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)

# Formatted for PowerShell
$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-name 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-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"}'

# Formatted for PowerShell
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"}'

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

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

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

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

在 API 中心中添加托管标识

在 API 中心中启用托管标识

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

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

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

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

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

从 API 管理导入 API

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

从 API 管理实例导入所有 API

在以下命令中，请替换以下对象的名称：API 中心、API 中心的资源组、API 管理实例以及实例的资源组。 请使用 * 指定 API 管理实例中的所有 API。

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

# Formatted for PowerShell
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 '*'  

从 API 管理实例导入特定 API

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

在以下命令中，请替换以下对象的名称：API 中心、API 中心的资源组、API 管理实例以及实例的资源组。 请使用 petstore-api 参数传递 API 名称，例如 --apim-apis。

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

# Formatted for PowerShell
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'    

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

相关内容

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