通过

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

启用并查看 Azure API 中心平台 API 目录

  • 项目

本文介绍如何在 Azure API 中心的 Visual Studio Code 扩展中为企业开发者提供对 Azure API 中心平台 API 目录（预览版）的访问权限。 使用平台 API 目录，开发人员可以在 Azure API 中心发现 API、查看 API 定义，并且可以在无权管理 API 中心本身或将 API 添加到库存时选择生成 API 客户端。 使用 Microsoft Entra ID 和 Azure 基于角色的访问控制来管理对平台 API 目录的访问。

提示

Visual Studio Code 扩展为有权管理 Azure API 中心的 API 开发人员提供更多功能。 例如，API 开发人员可以直接或使用 CI/CD 管道在 API 中心内注册 API。 了解详细信息

先决条件

面向 API 中心管理员

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

  • 在与 Azure 订阅关联的 Microsoft Entra 租户中创建应用注册的权限，以及授予对 API 中心中的数据的访问权限的权限。

面向应用开发人员

以下 Visual Studio Code 扩展是可选的：

API 中心管理员启用目录访问权限的步骤

以下部分提供了 API 中心管理员为企业开发人员启用平台 API 目录访问权限的步骤。

创建 Microsoft Entra 应用注册

首先，在 Microsoft Entra ID 租户中配置应用注册。 应用注册使 Azure API 中心的 Visual Studio Code 扩展能够代表已登录用户访问平台 API 目录。

  1. 在 Azure 门户中，导航到 “Microsoft Entra ID”>“应用注册”。

  2. 选择“+ 新建注册”。

  3. 在“注册应用程序”页上，按如下方式设置值：

    • 将“名称”设置为有意义的名称，例如“platform-api-catalog”
    • 在“支持的帐户类型”下，选择“此组织目录中的帐户（单租户）”
    • 在“重定向 URI”中，选择“单页应用程序(SPA)”并将 URI 设置为 API 中心的运行时 URI。 例如，https://<service name>.data.<region>.azure-apicenter.ms。 示例：https://contoso-apic.data.eastus.azure-apicenter.ms。
    • 选择“注册”。

    提示

    可以使用同一个应用注册来访问更多的 API 中心。 在“重定向 URI”中，继续添加要在平台 API 目录中显示的其他 API 中心的重定向 URI。

  4. 在“概述”页上，复制应用程序（客户端）ID 和目录（租户）ID。 稍后从 Visual Studio Code 扩展连接到 API 中心时设置这些值。

  5. 在左侧菜单中的“管理”下，选择“身份验证”>“+ 添加平台”。

  6. 在“配置平台”页上，选择“移动和桌面应用程序”。

  7. 在“配置桌面 + 设备”页上输入以下重定向 URI，然后选择“配置”：

    https://vscode.dev/redirect

  8. 在左侧菜单中的“管理”下，选择“API 权限”>“+ 添加权限”。

  9. 在“请求 API 权限”页上，执行以下操作：

    1. 选择“我的组织使用的 API”选项卡。
    2. 搜索并选择“Azure API 中心”。 还可以搜索并选择应用程序 ID c3ca1a77-7a87-4dba-b8f8-eea115ae4573。
    3. 在“选择权限”页中，选择“user_impersonation”。
    4. 选择“添加权限”。

    Azure API 中心权限显示在“已配置权限”下。

    在门户中注册 Microsoft Entra ID 应用时所需权限的屏幕截图。

允许 Microsoft Entra 用户和组登录平台 API 目录

企业开发人员必须使用 Microsoft 帐户登录才能查看 API 中心的平台 API 目录。 根据需要添加或邀请开发人员加入 Microsoft Entra 租户。

接下来，若要启用登录，请将“Azure API 中心数据读取者”角色分配给租户中的用户或组，范围限定为 API 中心。

重要

默认情况下，API 中心的其他管理员无权访问 API 中心扩展的平台 API 目录的 API。 请务必将 Azure API 中心数据读取者角色分配给自己和其他管理员。

有关向用户和组分配角色的详细先决条件和步骤，请参阅使用 Azure 门户分配 Azure 角色。 简单步骤如下：

  1. 在 Azure 门户中，导航到 API 中心。
  2. 在左侧菜单中，选择“访问控制(IAM)”>“+添加角色分配”。
  3. 在“添加角色分配”窗格中，按如下所示设置值：
    • 在“角色”页上，搜索并选择 Azure API 中心数据读取者。 选择下一步。
    • 在“成员”页上，在“分配访问权限”中，选择“用户”、“组”或“服务主体”>“+ 选择成员”。
    • 在“选择成员”页上，搜索并选择要向其分配角色的用户或组。 单击“选择”，然后单击“下一步”。
    • 查看角色分配，然后选择“查看 + 分配”。
  4. 重复以上步骤，即可为更多 API 中心启用登录平台 API 目录的功能。

注意

若要简化新用户的访问配置，建议将角色分配给 Microsoft Entra 组并配置动态组成员身份规则。 若要了解详细信息，请参阅在 Microsoft Entra ID 中创建或更新动态组。

企业开发人员访问平台 API 目录的步骤

开发人员可以按照以下步骤连接并登录，以使用 Visual Studio Code 扩展查看平台 API 目录。 连接到 API 中心的设置需要由 API 中心管理员提供。

连接到 API 中心

  1. 为 Visual Studio Code 安装适用于 Visual Studio Code 的 Azure API 中心扩展的预发布版本。

  2. 在 Visual Studio Code 的左侧“活动栏”中，选择“API 中心”。

    活动栏中的 API 中心图标的屏幕截图。

  3. 使用键盘快捷方式 (Ctrl+Shift+P) 开启命令面板。 键入“Azure API 中心: 连接到 API 中心”，然后按 Enter。

  4. 按照提示输入以下信息：

    1. API 中心的运行时 URL，格式为 <service name>.data.<region>.azure-apicenter.ms（不要以 https:// 为前缀）。 示例：contoso-apic.data.eastus.azure-apicenter.ms。 此运行时 URL 显示在 Azure 门户中的 API 中心的“概述”页上。
    2. 上一部分由管理员配置的应用注册中的应用程序（客户端）ID。
    3. 上一部分由管理员配置的应用注册中的目录（租户）ID。

    提示

    API 中心管理员需要向开发人员提供这些连接详细信息，或者提供以下格式的直接链接：
    vscode://apidev.azure-api-center?clientId=<Client ID>&tenantId=<tenant ID>&runtimeUrl=<service-name>.data.<region>.azure-apicenter.ms

    连接到 API 中心后，API 中心的名称会出现在 API 中心平台 API 目录中。

  5. 若要在 API 中心查看 API，请在 API 中心名称下选择“登录 Azure”。 允许使用在 API 中心分配有“Azure API 中心数据读取者”角色的 Microsoft 帐户登录。

    屏幕截图显示 VS Code 扩展中的 API 中心平台 API 目录。

  6. 登录后，选择“API”以列出 API 中心的 API。 展开 API 以浏览其版本和定义。

    屏幕截图显示包含 VS Code 扩展中的 API 的 API 中心平台 API 目录。

  7. 如果配置了访问权限，请重复上述步骤以连接到更多 API 中心。

发现和使用目录中的 API

平台 API 目录帮助企业开发者发现 API 详细信息并启动 API 客户端开发。 开发人员可以通过右键单击平台 API 目录中的 API 定义来访问以下功能：

  • 导出 API 规范文档 - 从定义中导出 API 规范，然后将其作为文件下载
  • 生成 API 客户端 - 使用 Microsoft Kiota 扩展为其喜欢的语言生成 API 客户端
  • 生成 Markdown - 生成 Markdown 格式的 API 文档
  • OpenAPI 文档 - 查看 API 定义的文档并在 Swagger UI 中尝试操作（仅适用于 OpenAPI 定义）

故障排除

在某些情况下，用户登录 API 中心平台 API 目录并展开 API 中心的 API 列表后，可能会遇到以下错误消息：

Error: Cannot read properties of undefined (reading 'nextLink')

检查是否在 API 中心为用户分配了“Azure API 中心数据读取者”角色。 必要时为用户重新分配该角色。 然后，刷新 Visual Studio Code 扩展中的 API 中心平台 API 目录。

无法登录到 Azure

如果已分配“Azure API 中心数据读者”角色的用户在平台 API 目录中选择“登录到 Azure”后无法完成登录流，则连接的配置可能存在问题。

检查在 Microsoft Entra ID 中配置的应用注册中的设置。 确认应用注册中的应用程序（客户端）ID 和目录（租户）ID 的值以及 API 中心的运行时 URL。 然后重新建立与 API 中心的连接。

无法在 Microsoft Entra ID 应用注册中选择 Azure API 中心权限

如果在 API 中心门户的 Microsoft Entra 应用注册中无法向 Azure API 中心请求 API 权限，请检查是否正在搜索 Azure API 中心（或应用程序 ID c3ca1a77-7a87-4dba-b8f8-eea115ae4573）。

如果应用不存在，则订阅中 Microsoft.ApiCenter 资源提供程序的注册可能存在问题。 可能需要重新注册资源提供程序。 为此，请在 Azure CLI 中运行以下命令：

az provider register --namespace Microsoft.ApiCenter

重新注册资源提供程序后，请重试请求 API 权限。

相关内容