自托管 API Management 开发人员门户

项目
04/15/2024

可用性

重要

此功能在 API 管理的“高级”、“标准”、“基本”和“开发人员”层中可用。

本教程介绍如何自托管 API Management 开发人员门户。 “自托管”是扩展开发人员门户功能的几个选项之一。例如，可以为 API 管理实例自托管多个具有不同功能的门户。自托管门户时，你将成为门户的维护人员并负责其升级。

重要

仅当需要修改开发人员门户代码库的核心时，才考虑自托管开发人员门户。此选项需要高级配置，包括：

部署到托管平台，可选择以 CDN 等解决方案为前端，以提高可用性和性能
维护和管理托管基础结构
手动更新（包括安全修补程序），可能需要在升级代码库时解决代码冲突

注意

自承载门户不支持托管开发人员门户中提供的可见性和访问控制。

如果你已在托管门户中上传或修改了媒体文件，请参阅本文后面的从托管迁移到自托管部分。

先决条件

若要设置本地开发环境，需要具有：

API Management 服务实例。如果没有，请参阅快速入门 - 创建 Azure API Management 实例。
已启用静态网站功能的 Azure 存储帐户。请参阅创建存储帐户。
计算机上安装有 Git。请按照此 Git 教程安装。
计算机上安装有 Node.js（LTS v10.15.0 或更高版本）和 npm。请参阅下载并安装 Node.js 和 npm。
Azure CLI。请按照 Azure CLI 安装步骤操作。

步骤 1：设置本地环境

若要设置本地环境，必须克隆存储库，切换到最新版本的开发人员门户，并安装 npm 包。

从 GitHub 克隆 api-management-developer-portal 存储库：

git clone https://github.com/Azure/api-management-developer-portal.git

转到存储库的本地副本：
```
cd api-management-developer-portal
```
查看门户是否为最新版本。

运行以下代码之前，在存储库的版本部分中检查当前版本标记，并将 <current-release-tag> 值替换为最新版本标记。
```
git checkout <current-release-tag>
```
安装任何可用的 npm 包：
```
npm install
```

提示

始终使用最新的门户版本，并使分支门户保持最新。出于日常开发目的，软件工程师使用此存储库的 master 分支。该分支具有不稳定的软件版本。

步骤 2：配置 JSON 文件、静态网站和 CORS 设置

开发人员门户需要使用 API Management REST API 来管理内容。

config.design.json 文件

转到 src 文件夹，然后打开 config.design.json 文件。

{
  "environment": "development",
  "managementApiUrl": "https://<service-name>.management.azure-api.cn",
  "managementApiAccessToken": "SharedAccessSignature ...",
  "backendUrl": "https://<service-name>.developer.azure-api.cn",
  "useHipCaptcha": false,
  "integration":�{
      "googleFonts":�{
    ��    "apiKey":�"..."
    ��}
  }
}

配置该文件：

在 managementApiUrl 值中，将 <service-name> 替换为 API Management 实例的名称。如果已配置自定义域，请改用它（例如 https://management.contoso.com）。
```
{
...
"managementApiUrl": "https://contoso-api.management.azure-api.cn"
...
```
手动创建一个 SAS 令牌，以启用对 API Management 实例的直接 REST API 访问。
复制生成的令牌，并将其粘贴为 managementApiAccessToken 值。
在 backendUrl 值中，将 <service-name> 替换为 API Management 实例的名称。如果已配置自定义域，请改用它（例如 https://portal.contoso.com）。
```
{
...
"backendUrl": "https://contoso-api.developer.azure-api.cn"
...
```
若要在开发人员门户中启用 CAPTCHA，请设置 "useHipCaptcha": true。确保为开发人员门户后端配置 CORS 设置。

config.publish.json 文件

转到 src 文件夹，然后打开 config.publish.json 文件。

{
  "environment": "publishing",
  "managementApiUrl": "https://<service-name>.management.azure-api.cn",
  "managementApiAccessToken": "SharedAccessSignature...",
  "useHipCaptcha": false
}

配置该文件：

复制并粘贴以前的配置文件中的 managementApiUrl 和 managementApiAccessToken 值。
若要在开发人员门户中启用 CAPTCHA，请设置 "useHipCaptcha": true。确保为开发人员门户后端配置 CORS 设置。

config.runtime.json 文件

转到 src 文件夹，然后打开 config.runtime.json 文件。

{
  "environment": "runtime",
  "managementApiUrl": "https://<service-name>.management.azure-api.cn",
  "backendUrl": "https://<service-name>.developer.azure-api.cn"
}

配置该文件：

复制并粘贴以前的配置文件中的 managementApiUrl 值。
在 backendUrl 值中，将 <service-name> 替换为 API Management 实例的名称。如果已配置自定义域，请改用它（例如 https://portal.contoso.com）。
```
{
...
"backendUrl": "https://contoso-api.developer.azure-api.cn"
...
```

配置静态网站

通过向索引和错误页提供路由，在存储帐户中配置“静态网站”功能：

在 Azure 门户中转到存储帐户，然后从左侧菜单中选择“静态网站”。
在“静态网站”页上，选择“启用” 。
在“索引文档名称”字段中，输入 index.html。
在“错误文档路径”字段中，输入 404/index.html。
选择“保存”。

为存储帐户配置 CORS 设置

为存储帐户配置跨源资源共享 (CORS) 设置：

在 Azure 门户中转到存储帐户，然后从左侧菜单中选择“CORS”。
在“BLOB 服务”选项卡中，配置以下规则：

规则 “值”

允许的源 *

允许的方法选择所有 Http 谓词。

允许的标题 *

公开的标题 *

最长时间 0
选择“保存”。

规则	“值”
允许的源	*
允许的方法	选择所有 Http 谓词。
允许的标题	*
公开的标题	*
最长时间	0

为开发人员门户后端配置 CORS 设置

为开发人员门户后端配置 CORS 设置，以允许源自自托管开发人员门户的请求。自托管开发人员门户依赖于开发人员门户的后端终结点（在门户配置文件的 backendUrl 中设置）来启用多项功能，包括：

CAPTCHA 验证
测试控制台中的 OAuth 2.0 授权
用户身份验证和产品订阅的委派

若要添加 CORS 设置，请执行以下操作：

在 Azure 门户中转到你的 API 管理实例，然后从左侧菜单中选择“开发人员门户”>“门户设置”。
在“自托管门户配置”选项卡上，添加一个或多个“源”域值。例如：
- 托管自托管门户的域，例如 https://www.contoso.com
- localhost 用于本地开发（如果适用），例如 http://localhost:8080 或 https://localhost:8080
选择“保存”。

步骤 3：运行门户

现在，你可在开发模式下生成并运行本地门户实例。在开发模式下，所有优化都处于禁用状态，源映射处于启用状态。

运行以下命令：

npm start

一小段时间后，默认浏览器将自动打开你的本地开发人员门户实例。默认地址为 http://localhost:8080，但如果 8080 已被占用，端口可能会更改。对项目的代码库所做的任何更改都会触发重新生成和刷新浏览器窗口。

步骤 4：通过可视化编辑器进行编辑

使用可视化编辑器执行以下任务：

自定义门户
创作内容
组织网站结构
设置外观样式

请参阅教程：访问和自定义开发人员门户。该教程介绍管理用户界面的基本知识，并列出对默认内容的建议更改。保存本地环境中的所有更改，然后按 Ctrl+C 将其关闭。

步骤 5：在本地发布

门户数据的最初形式为强类型化对象。可使用以下命令将它们转换为静态文件，并将输出放入 ./dist/website 目录中：

npm run publish

步骤 6：将静态文件上传到 Blob

使用 Azure CLI 将本地生成的静态文件上传到 Blob，确保访问者可以访问它们：

打开 Windows 命令提示符、PowerShell 或其他命令行界面。
运行以下 Azure CLI 命令。

将 <account-connection-string> 替换为存储帐户的连接字符串。可从存储帐户的“访问密钥”部分获取该字符串。
```
az storage blob upload-batch --source dist/website \
    --destination '$web' \
    --connection-string <account-connection-string>
```

步骤 7：转到你的网站

你的网站现在处于 Azure 存储属性中指定的主机名下（“静态网站”中的“主终结点”）。

步骤 8：更改 API Management 通知模板

替换 API Management 通知模板中的开发人员门户 URL，使其指向你的自托管门户。请参阅如何在 Azure API Management 中配置通知和电子邮件模板。

具体而言，请对默认模板执行以下更改：

注意

下面的“已更新”部分中的值假定你要在 https://portal.contoso.com/ 托管门户。

电子邮件更改确认

更新“电子邮件更改确认”通知模板中的开发人员门户 URL：

原始内容

<a id="confirmUrl" href="$ConfirmUrl" style="text-decoration:none">
  <strong>$ConfirmUrl</strong></a>

已更新

<a id="confirmUrl" href="https://portal.contoso.com/signup?$ConfirmQuery" style="text-decoration:none">
  <strong>https://portal.contoso.com/signup?$ConfirmQuery</strong></a>

新的开发人员帐户确认

更新“新的开发人员帐户确认”通知模板中的开发人员门户 URL：

原始内容

<a id="confirmUrl" href="$ConfirmUrl" style="text-decoration:none">
  <strong>$ConfirmUrl</strong></a>

已更新

<a id="confirmUrl" href="https://portal.contoso.com/signup?$ConfirmQuery" style="text-decoration:none">
  <strong>https://portal.contoso.com/signup?$ConfirmQuery</strong></a>

邀请用户

更新“邀请用户”通知模板中的开发人员门户 URL：

原始内容

<a href="$ConfirmUrl">$ConfirmUrl</a>

已更新

<a href="https://portal.contoso.com/confirm-v2/identities/basic/invite?$ConfirmQuery">https://portal.contoso.com/confirm-v2/identities/basic/invite?$ConfirmQuery</a>

激活的新订阅

更新“激活的新订阅”通知模板中的开发人员门户 URL：

原始内容

Thank you for subscribing to the <a href="http://$DevPortalUrl/products/$ProdId"><strong>$ProdName</strong></a> and welcome to the $OrganizationName developer community. We are delighted to have you as part of the team and are looking forward to the amazing applications you will build using our API!

已更新

Thank you for subscribing to the <a href="https://portal.contoso.com/product#product=$ProdId"><strong>$ProdName</strong></a> and welcome to the $OrganizationName developer community. We are delighted to have you as part of the team and are looking forward to the amazing applications you will build using our API!

原始内容

Visit the developer <a href="http://$DevPortalUrl/developer">profile area</a> to manage your subscription and subscription keys

已更新

Visit the developer <a href="https://portal.contoso.com/profile">profile area</a> to manage your subscription and subscription keys

原始内容

<a href="http://$DevPortalUrl/docs/services?product=$ProdId">Learn about the API</a>

已更新

<a href="https://portal.contoso.com/product#product=$ProdId">Learn about the API</a>

原始内容

<p style="font-size:12pt;font-family:'Segoe UI'">
  <strong>
    <a href="http://$DevPortalUrl/applications">Feature your app in the app gallery</a>
  </strong>
</p>
<p style="font-size:12pt;font-family:'Segoe UI'">You can publish your application on our gallery for increased visibility to potential new users.</p>
<p style="font-size:12pt;font-family:'Segoe UI'">
  <strong>
    <a href="http://$DevPortalUrl/issues">Stay in touch</a>
  </strong>
</p>
<p style="font-size:12pt;font-family:'Segoe UI'">
      If you have an issue, a question, a suggestion, a request, or if you just want to tell us something, go to the <a href="http://$DevPortalUrl/issues">Issues</a> page on the developer portal and create a new topic.
</p>

已更新

<!--Remove the entire block of HTML code above.-->

密码更改确认

更新“密码更改确认”通知模板中的开发人员门户 URL：

原始内容

<a href="$DevPortalUrl">$DevPortalUrl</a>

已更新

<a href="https://portal.contoso.com/confirm-password?$ConfirmQuery">https://portal.contoso.com/confirm-password?$ConfirmQuery</a>

所有模板

在页脚中包含链接的所有模板中更新开发人员门户 URL：

原始内容

<a href="$DevPortalUrl">$DevPortalUrl</a>

已更新

<a href="https://portal.contoso.com/">https://portal.contoso.com/</a>

从托管迁移到自托管开发人员门户

随着时间的推移，业务需求可能会改变。最终可能会发现 API Management 开发人员门户的托管版本不再满足你的需求。例如，新的需求可能会迫使你生成与第三方数据提供程序集成的自定义小组件。与托管版本不同，自托管版本的门户提供完全的灵活性和可扩展性。

转换过程

你可以在同一 API Management 服务实例中从托管版本转换为自托管版本。此过程将保留你在门户的托管版本中执行的修改。请确保事先备份门户内容。可在 API Management 开发人员门户 GitHub 存储库的 scripts 文件夹中找到备份脚本。

转换过程与设置通用自托管门户几乎完全相同，如本文前面的步骤所示。配置步骤中有一个例外。 config.design.json 文件中的存储帐户需要与门户的托管版本的存储帐户相同。有关如何检索 SAS URL 的说明，请参阅教程：使用 Linux VM 系统分配的标识通过 SAS 凭据访问 Azure 存储。

提示

建议在 config.publish.json 文件中使用单独的存储帐户。使用此方法，可以更好地控制和简化门户托管服务的管理。

后续步骤

了解自托管的替代方法

通过

自托管 API Management 开发人员门户

可用性

先决条件

步骤 1：设置本地环境

步骤 2：配置 JSON 文件、静态网站和 CORS 设置

config.design.json 文件

config.publish.json 文件

config.runtime.json 文件

配置静态网站

为存储帐户配置 CORS 设置

为开发人员门户后端配置 CORS 设置

步骤 3：运行门户

步骤 4：通过可视化编辑器进行编辑

步骤 5：在本地发布

步骤 6：将静态文件上传到 Blob

步骤 7：转到你的网站

步骤 8：更改 API Management 通知模板

电子邮件更改确认

新的开发人员帐户确认

邀请用户

激活的新订阅

密码更改确认

所有模板

从托管迁移到自托管开发人员门户

转换过程

后续步骤

其他资源