自行托管您的 API 中心门户

本文介绍如何自行托管 API 中心门户，这是组织中的开发人员和其他利益干系人可用于在 API 中心发现 API 的网站。 从 API 中心门户启动库 存储库中部署门户的参考实现。

关于自托管门户

可以使用 API Center portal starter 存储库中的代码生成并部署门户的参考实现。 门户使用 Azure API 中心数据平面 API 从 API 中心检索数据。

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

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

先决条件

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

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

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

  • Node.js 和 npm
  • Vite 包

创建 Microsoft Entra 应用注册

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

API 中心可以自动设置应用注册，也可以手动创建应用注册。

自动设置应用注册

若要自动设置应用注册，请执行以下步骤：

1. 在 Azure 门户中，导航到 API 中心。
2. 在左侧菜单中，选择 “API 中心门户>设置”。
3. 在“标识提供者”选项卡上，选择“开始设置”。
4. 选择“保存 + 发布”。

手动设置应用注册

若要手动创建应用注册，请执行以下步骤：

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

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

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

   1. 将“名称”设置为有意义的名称，例如“api-center-portal”
   2. 在“支持的帐户类型”下，选择“此组织目录中的帐户(单租户)”。
   3. 在“重定向 URI”中，选择“单页应用程序(SPA)”并设置 URI。 使用以下格式输入 API 中心门户部署的 URI：https://<service-name>.portal.<location>.azure-apicenter.ms。 请将 <service name> 和 <location> 替换为你的 API 中心的名称及其部署的位置，例如：https://myapicenter.portal.eastus.azure-apicenter.ms。
   4. 选择“注册”。

为 VS Code 扩展配置其他重定向 URI

在适用于 API 中心的 Visual Studio Code 扩展中启用 API 中心门户视图时，还在应用注册中配置以下重定向 URI：

1. 在 Azure 门户中，导航到应用注册。

2. 在“ 管理>身份验证 ”页上，选择“ 添加平台 ”，然后选择 “移动和桌面应用程序”。

3. 配置以下三个自定义重定向 URI：
   https://vscode.dev/redirect
http://localhost
ms-appx-web://Microsoft.AAD.BrokerPlugin/<application-client-id>
   

   将 <application-client-id> 替换为此应用的应用程序（客户端）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 文件以指向你的服务。 按如下所示更新文件中的值：

   1. 将<service name> 和<location>替换为您的API中心名称及其部署位置
   2. 将 <client ID> 和 <tenant ID> 替换为在上一部分创建的应用注册的应用程序（客户端）ID 和目录（租户）ID。
   3. 将 title 的值更新为要在门户的顶栏中显示的名称。

   {
     "dataApiHostName": "<service name>.data.<location>.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 静态 Web 应用的步骤，请参阅 API 中心门户初学者 存储库。

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

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

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

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

配置对门户的访问权限后，配置的用户可以登录到门户并在 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

无法登录到门户

如果在 API 中心门户中选择“登录”后，已分配了 Azure 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 中心门户参考实现的支持。

相关内容

• 设置 API 中心门户
• 什么是 Azure 基于角色的访问控制 (RBAC)？
• Azure RBAC 最佳做法
• 注册资源提供程序