自行托管 API 管理开发者门户

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

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

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

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

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

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

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

2. 转到存储库的本地副本：

   cd api-management-developer-portal
   

3. 查看门户的最新版本。

   运行以下代码之前，请检查 存储库的“发布”部分中的 当前发布标记，并将值替换为 <current-release-tag> 最新的发布标记。

   git checkout <current-release-tag>
   

4. 安装任何可用的 npm 包：

   npm install
   

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

转到 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": "..."
      }
  }
}

配置该文件：

1. 在 managementApiUrl 值中，将 <service-name> 替换为 API 管理实例的名称。 如果配置 了自定义域，请改用它（例如， https://management.contoso.com）。

   {
   ...
   "managementApiUrl": "https://contoso-api.management.azure-api.cn"
   ...
   

2. 手动创建 SAS 令牌 以启用对 API 管理实例的直接 REST API 访问。

3. 复制生成的令牌并将其粘贴为 managementApiAccessToken 值。

4. 在 backendUrl 值中，将 <service-name> 替换为 API 管理实例的名称。 如果配置 了自定义域，请改用它（例如， https://portal.contoso.com）。

   {
   ...
   "backendUrl": "https://contoso-api.developer.azure-api.cn"
   ...
   

5. 若要在开发人员门户中启用 CAPTCHA，请设置 "useHipCaptcha": true。 请确保 为开发人员门户后端配置 CORS 设置。

转到 src 文件夹并打开 config.publish.json 该文件。

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

配置该文件：

1. 从上一个配置文件中复制并粘贴 managementApiUrl 值和 managementApiAccessToken 值。

2. 若要在开发人员门户中启用 CAPTCHA，请设置 "useHipCaptcha": true。 请确保 为开发人员门户后端配置 CORS 设置。

转到 src 文件夹并打开 config.runtime.json 该文件。

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

配置该文件：

1. 复制并粘贴 managementApiUrl 上一个配置文件中的值。

2. 在 backendUrl 值中，将 <service-name> 替换为 API 管理实例的名称。 如果你配置了自定义域，请使用该域代替（例如https://portal.contoso.com）。

   {
   ...
   "backendUrl": "https://contoso-api.developer.azure-api.cn"
   ...
   

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

1. 在 Azure 门户中转到存储帐户，然后从左侧菜单中选择 静态网站 。

2. 在 “静态网站 ”页上，选择“ 已启用”。

3. 在 “索引文档名称 ”字段中，输入 index.html。

4. 在 “错误文档路径 ”字段中，输入 404/index.html。

5. 选择“保存”。

为存储帐户配置跨域资源共享（CORS）设置：

1. 在 Azure 门户中转到存储帐户，然后从左侧菜单中选择 CORS 。

2. 在 “Blob 服务 ”选项卡中，配置以下规则：

   展開資料表

   规则	价值
   允许的域	*
   允许的方法	选择所有 Http 谓词。
   允许的标题	*
   公开的标题	*
   最大年龄	0

3. 选择“保存”。

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

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

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

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

现在可以在开发模式下生成并运行本地门户实例。 在开发模式下，所有优化都处于关闭状态，并且源映射处于打开状态。

运行下面的命令：

npm start

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

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

• 自定义门户
• 创作内容
• 组织网站的结构
• 风格化其外观

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

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

npm run publish

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

1. 打开 Windows 命令提示符、PowerShell 或其他命令行界面。

2. 运行以下 Azure CLI 命令。

   将 <account-connection-string> 替换为存储帐户的连接字符串。 可以从存储帐户的 “访问密钥 ”部分获取它。

   az storage blob upload-batch --source dist/website \
       --destination '$web' \
       --connection-string <account-connection-string>
   

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

将 API 管理通知模板中的开发者门户 URL 替换为指向您自己托管的门户。 请参阅 如何在 Azure API 管理中配置通知和电子邮件模板。

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

更新“电子邮件更改确认”通知模板中的开发人员门户 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>

更新 新订阅激活通知 模板中的开发人员门户网址：

原始内容

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 管理开发人员门户的托管版本不再满足你的需求。 例如，新的需求可能会迫使你生成与第三方数据提供程序集成的自定义小组件。 与托管版本不同，门户的自承载版本提供完全的灵活性和可扩展性。

可以在同一 API 管理服务实例中从托管版本过渡到自承载版本。 此过程会保留已在门户的托管版本中执行的修改。 请确保事先备份门户的内容。 可以在 API 管理开发人员门户 scripts的文件夹中找到备份脚本。

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

• 了解 自托管的替代方法