通过

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

自行托管 API 中心门户

  • 项目

本文介绍 API 中心门户，这是组织中的开发人员和其他利益干系人可用于在 API 中心发现 API 的网站。 从API 中心门户初始版存储库部署门户的参考实现。

用户登录后 API 中心门户的屏幕截图。

关于 API 中心门户

API 中心门户是一个网站，你可以生成和托管该门户以在 API 中心显示 API 清单。 门户使组织中的开发人员和其他利益干系人能够发现 API 并查看 API 详细信息。

可以使用 API 中心门户初始版存储库中的代码生成和部署门户的引用实现。 门户使用 Azure API 中心数据平面 API 从 API 中心检索数据。 用户对 API 信息的访问权限基于 Azure 基于角色的访问控制。

API 中心门户参考实现提供：

  • 使用 GitHub Actions 发布和维护客户管理的 API 门户的框架
  • 客户可修改或扩展以满足其需求的门户平台
  • 灵活托管在不同基础结构上，包括部署到 Azure Static Web Apps 等服务。

先决条件

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

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

  • 若要生成和部署门户，需要在本地计算机上安装 GitHub 帐户和以下工具：

创建 Microsoft Entra 应用注册

首先在 Microsoft Entra ID 租户中配置应用注册。 应用注册使 API 中心门户能够代表已登录用户从 API 中心访问数据。

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

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

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

    • 将“名称”设置为有意义的名称，例如“api-center-portal”

    • 在“支持的帐户类型”下，选择“此组织目录中的帐户（单租户）”

    • 在重定向 URI 中，选择“单页应用程序 (SPA)”并设置 URI。

      • 对于本地测试，请将 URI 设置为 https://localhost:5173。
      • 对于生产，请将 URI 设置为 API 中心门户部署的 URI。

    • 选择“注册”。

  4. 在“概述”页上，复制应用程序（客户端）ID 和目录（租户）ID。 需要在生成门户时设置这些值。

  5. 在“API 权限”页上，选择“+添加权限”。

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

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

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

配置本地环境

按照以下步骤在本地生成和测试 API 中心门户。

  1. 将 API 中心门户初始版存储库克隆到本地计算机。

    git clone https://github.com/Azure/APICenter-Portal-Starter.git

  2. 切换到 APICenter-Portal-Starter 目录。

    cd APICenter-Portal-Starter

  3. 签出主分支。

    git checkout main

  4. 若要配置服务，请将 public/config.example 文件重命名为 public/config.json 或将其复制到其中。

  5. 然后编辑 public/config.json 文件，以指向你的服务。 按如下所示更新 文件中的值：

    • 将 <service name> 和 <region> 替换为 API 中心的名称及其部署的区域
    • 将 <client ID> 和 <tenant ID> 替换为在上一部分创建的应用注册的应用程序（客户端）ID 和目录（租户）ID。
    • 将 title 的值更新为要在门户中显示的名称。
    {
  "dataApiHostName": "<service name>.data.<region>.azure-apicenter.ms/workspaces/default",
  "title": "API portal",
  "authentication": {
      "clientId": "<client ID>",
      "tenantId": "<tenant ID>",
      "scopes": ["https://azure-apicenter.net/user_impersonation"],
      "authority": "https://login.microsoftonline.com/"
  }
}

  6. 安装所需程序包。

    npm install

  7. 启动开发服务器。 以下命令将在本地运行的开发模式下启动门户：

    npm start

    浏览到位于 https://localhost:5173 的门户。

部署到 Azure

有关将门户部署到 Azure Static Web Apps 的步骤，请参阅 API 中心门户初始版存储库。

通过 Microsoft Entra 用户和组启用登录到门户

用户必须登录才能在 API 中心查看 API。 若要启用登录，请将 Azure API 中心数据读取者角色分配给组织中的用户或组，范围限定为 API 中心。

重要

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

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

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

注意

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

配置对门户的访问权限后，配置的用户可以登录到门户并在 API 中心查看 API。

注意

系统会提示第一个登录到门户的用户同意 API 中心门户应用注册请求的权限。 此后，系统不会提示其他已配置的用户同意。

疑难解答

错误：“无权访问此门户”

在某些情况下，用户在使用配置的用户帐户登录到 API 中心门户后可能会遇到以下错误消息：

You are not authorized to access this portal. Please contact your portal administrator for assistance. `

首先，确认用户在 API 中心中分配了 Azure API 中心数据读取者角色。

如果用户分配了该角色，则订阅中 Microsoft.ApiCenter 资源提供程序的注册可能存在问题，并且可能需要重新注册资源提供程序。 为此，请在 Azure CLI 中运行以下命令：

az provider register --namespace Microsoft.ApiCenter

无法登录到门户

如果已分配“Azure API 中心数据读者”角色的用户在 API 中心门户中选择“登录”后无法完成登录流程，则 Microsoft Entra ID 标识提供者的配置可能存在问题。

在 Microsoft Entra 应用注册中，查看并根据需要更新重定向 URI 设置，以确保 URI 与 API 中心门户部署的 URI 匹配。

无法在 Microsoft Entra 应用注册中选择 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 权限。

支持策略

在 API 中心门户初始版存储库中提供反馈、请求功能，并获取对 API 中心门户参考实现的支持。

相关内容