在 WordPress 上自定义 API 管理开发人员门户

适用于：开发人员 |基本 |标准 |奖赏

本文介绍如何配置开源的开发人员门户插件（预览版），以便在 WordPress 上自定义 API 管理开发人员门户。 使用该插件可以将任何 WordPress 站点转变成开发人员门户。 利用 WordPress 中的站点功能在开发人员门户中自定义和添加功能，包括本地化、可折叠和可缩放的菜单、自定义样式表、文件下载等。

在本文中，你将在 Azure 应用服务上创建一个 WordPress 站点，并在 WordPress 站点上配置开发人员门户插件。 将配置 Microsoft Entra ID 以便向 WordPress 站点和开发人员门户进行身份验证。

先决条件

  • 创建 API 管理实例。
  • 启用并发布开发人员门户。 有关步骤，请参阅教程：访问和自定义开发人员门户。
  • 在与 Azure 订阅关联的 Microsoft Entra 租户中创建应用注册的权限。
  • 从插件存储库获取的开发人员门户 WordPress 插件和自定义 WordPress 主题的安装文件。 从存储库中的 dist 文件夹下载以下 zip 文件：
    • 插件文件： apim-devportal.zip
    • 主题文件： twentytwentyfour.zip

步骤 1：在应用服务上创建 WordPress

对于此方案，您将创建一个在 Azure 应用服务上管理的 WordPress 站点。 下面是简要步骤：

  1. 在 Azure 门户中，导航到 https://portal.azure.cn/#create/WordPress.WordPress。

  2. 在“在应用服务上创建 WordPress”页面上的“基本信息”选项卡中，输入项目详细信息、Web 应用详细信息和 WordPress 安装设置。

    在安全的位置存储 WordPress 管理员用户名和密码。 在后续步骤中登录到 WordPress 管理站点和安装插件时需要这些凭据。

    谨慎

    避免使用默认的 WordPress admin 用户名，并创建强密码。 若要了解详细信息，请参阅 WordPress 密码最佳做法。

  3. 在“加载项”选项卡上：

    1. 选择 使用 Azure 通信服务、 Azure Front Door 和 Azure Blob 存储的电子邮件的建议默认值。
    2. 选择或创建新的 AFD 配置文件。
    3. 在“虚拟网络”中，选择“新建”值或现有虚拟网络。

  4. 在“部署”选项卡上，保持“添加备用槽”未选中。

  5. 选择查看 + 创建以运行最终验证。

  6. 选择“创建”完成应用服务部署。

应用服务部署过程可能需要几分钟时间。

步骤 2：创建新的 Microsoft Entra 应用注册

在此步骤中创建新的 Microsoft Entra 应用。 在后续步骤中，你会将此应用配置为标识提供者，以便向 API 管理实例中的应用服务和开发人员门户进行身份验证。

  1. 在 Azure 门户中，导航到 “应用注册”，然后选择“ + 新建注册”。

  2. 提供新的应用名称，并在 支持的帐户类型中， 仅选择“单租户”。 选择“注册”。

  3. 在“概述”页面上，复制并安全存储“应用程序(客户端) ID”和“目录(租户) ID”。在后续步骤中，需要使用这些值来配置对 API 管理实例和应用服务的身份验证。 门户中应用注册的“概述”页的屏幕截图。

  4. 在边栏菜单中的“ 管理”下，选择“ 身份验证>+ 添加平台”。 如果未看到此设置，请选择切换到旧体验的选项。

  5. 在“配置平台”页面上，选择“Web”。

  6. 在“配置 Web”页面上输入以下重定向 URI（替换为你的应用服务名称），然后选择“配置”：

    https://app-service-name>.chinacloudsites.cn/.auth/login/aad/callback

  7. 再次选择“+ 添加平台”。 选择“单页应用程序”。

  8. 在“配置单页应用程序”页面上输入以下重定向 URI（替换为你的 API 管理实例名称），然后选择“配置”：

    https://<apim-instance-name>.developer.azure-api.cn/signin

  9. 再次选择“+ 添加平台”。 再次选择“单页应用程序”。

  10. 在“配置单页应用程序”页面上输入以下重定向 URI（替换为你的 API 管理实例名称），然后选择“配置”：

    https://<management-instance-name>.developer.azure-api.cn/

  11. 在边栏菜单中的“ 管理”下，选择“ 令牌配置>+ 添加可选声明”。

  12. 在 “添加可选声明 ”页上，选择 ID，然后选择以下声明： 电子邮件、family_name、given_name、onprem_sid、preferred_username、upn。 选择 添加 。

  13. 如果出现提示，请选择“启用 Microsoft Graph 电子邮件、个人资料权限”。 选择 添加 。

  14. 在边栏菜单中，在 “管理 ”下选择 API 权限 ，并确认存在以下Microsoft图形权限： 电子邮件、配置文件、User.Read。

    门户中的 API 权限的屏幕截图。

  15. 在边栏菜单中的“ 管理”下，选择“ 证书和机密>+ 新建客户端机密”。

  16. 配置机密设置，然后选择“添加”。 请在生成机密的值后，立即复制并妥善存储它。 在后续步骤中，需要使用此值将应用程序添加到 API 管理实例和应用服务进行身份验证。

  17. 在边栏菜单中的“ 管理”下，选择“ 公开 API”。 记下默认的“应用程序 ID URI”。 （可选）根据需要添加自定义范围。

步骤 3：启用对应用服务的身份验证

此步骤将 Microsoft Entra 应用注册添加为标识提供者，用于对 WordPress 应用服务进行身份验证。

  1. 在门户中，导航到 WordPress 应用服务。

  2. 在边栏菜单中的 “设置”下，选择“ 身份验证>添加标识提供者”。

  3. 在“基本信息”选项卡上的“标识提供者”中，选择“Microsoft”。

  4. 在“应用注册”下，选择“提供现有应用注册的详细信息”。

    1. 输入在上一步骤中创建的应用注册的“应用程序(客户端) ID”和“客户端机密”。
    2. 在“颁发者 URL”中，输入身份验证终结点的以下任一值： 或 https://login.partner.microsoftonline.cn/<tenant-id>https://sts.chinacloudapi.cn/<tenantid>。 请将 <tenant-id> 替换为应用注册中的 目录(租户) ID。

      重要

      不要将版本 2.0 端点用于颁发者 URL（URL 以 /v2.0 结尾）。

  5. 在 允许的令牌受众 中，输入应用注册的 应用程序 ID URI。 示例：api://<app-id>。

  6. 在“其他检查”下，选择适合你的环境的值，或使用默认值。

  7. 配置剩余设置的所需值，或者可以使用默认值。 选择 添加 。

    注意

    如果想要允许来宾用户和登录用户访问 WordPress 上的开发人员门户，则可以启用未经身份验证的访问。 在“限制访问”中，选择“允许未经身份验证的访问”。 若要了解详细信息，请参阅 授权行为。

身份提供者被添加到应用服务中。

步骤 4：启用对 API 管理开发人员门户的身份验证

将相同的 Microsoft Entra 应用注册配置为 API 管理开发人员门户的标识提供者。

  1. 在门户中导航到 API 管理实例。

  2. 在边栏菜单中的 “开发人员门户”下，选择“ 标识>+ 添加”。

  3. 在 “添加标识提供者 ”页上，选择 Microsoft Entra ID。

  4. 输入在上一步骤中创建的应用注册的“客户端 ID”、“客户端机密”和“登录租户”值。 “登录租户”是应用注册中的“目录(租户) ID”。

  5. 在“客户端库”中，选择“MSAL”。

  6. 接受其余设置的默认值，然后选择“添加”。

  7. 重新发布开发人员门户以应用更改。

  8. 通过以下 URL（替换为你的 API 管理实例名称）登录到开发人员门户来测试身份验证：https://<management-instance-name>.developer.azure-api.cn/signin。 选择底部 的“Microsoft Entra ID ”按钮进行登录。

    首次打开它时，系统可能会提示你同意特定权限。

步骤 5：在 API 管理中配置开发人员门户设置

在 API 管理实例中更新开发人员门户的设置，以启用 CORS 并将应用服务站点包含为门户源。

  1. 在 Azure 门户，导航到 API 管理实例。

  2. 在边栏菜单中的 “开发人员门户”下，选择 “门户概述”。

  3. 在“门户概述”选项卡上，选择“启用 CORS”。

  4. 在边栏菜单中的 “开发人员门户”下，选择 “门户设置”。

  5. 在“自承载门户配置”选项卡上，输入应用服务站点上 WordPress 的主机名，将其用作门户的来源，并将以下 URL 中的占位符替换为你的应用服务名称：https://<yourapp-service-name>.chinacloudsites.cn

  6. 重新发布开发人员门户以应用更改。

另外，请更新 API 管理实例中的 cors 策略配置，以将应用服务站点添加为允许的源。 为了允许从 WordPress 站点的开发者门户测试控制台进行调用，需要使用此值。

在 origin 策略配置中添加以下 cors 值：

<cors ...>
    <allowed-origins>
        [...]
        <origin>https://<yourapp-service-name>.chinacloudsites.cn</origin>
    </allowed-origins>
</cors>

详细了解如何设置或编辑策略。

步骤 6：导航到 WordPress 管理站点并上传自定义主题

此步骤将 API 管理开发人员门户的自定义主题上传到 WordPress 管理站点。

重要

我们建议上传插件存储库中提供的主题。 该主题基于 2024 主题，并自定义为支持 WordPress 中的开发人员门户功能。 如果选择使用不同的主题，某些功能可能无法按预期工作或需要其他自定义。

  1. 通过以下 URL 打开 WordPress 后台管理网站（请将占位符替换为应用服务名称）：http://<app-service-name>.chinacloudsites.cn/wp-admin

    首次打开它时，系统可能会提示你同意特定权限。

  2. 使用在应用服务上创建 WordPress 时输入的用户名和密码登录到 WordPress 管理站点。

  3. 在边栏菜单中，选择 “外观>主题 ”，然后选择 “添加新主题”。

  4. 选择“上传主题”。 选择“选择文件”以上传先前下载的 API 管理开发人员门户主题 zip 文件。 选择“立即安装”。

  5. 在下一个屏幕中，选择“用上传的文件替换活动文件”。

  6. 如果出现提示，请选择“激活”。

注意

如果 WordPress 站点包含缓存插件，请在激活主题后清除缓存，以确保更改生效。

步骤 7：安装开发人员门户插件

  1. 在 WordPress 管理站点的侧栏中，选择“>插件添加新插件”。

  2. 选择“上传插件”。 选择 选择文件 选项来上传您之前下载的 API 管理开发者门户插件 zip 文件（apim-devportal.zip）。 选择“立即安装”。

  3. 成功安装后，选择“激活插件”。

  4. 在边栏菜单中，选择 Azure API 管理开发人员门户。

  5. 在 “APIM 设置” 页上，输入以下设置，然后选择“ 保存更改” ：

    • APIM 服务名称 - 你的 API 管理实例的名称
    • 启用“创建默认页面”和“创建导航菜单”

步骤 8：添加自定义样式表

为 API 管理开发人员门户添加自定义样式表。

  1. 在 WordPress 管理站点的边栏菜单中，选择 “外观>主题”。

  2. 选择“自定义”，然后导航到“样式”。

  3. 选择铅笔图标（“编辑样式”）。

  4. 在“样式”窗格中，选择“更多”（三个点）“其他 CSS”>。

  5. 在“其他 CSS”中输入以下 CSS：

    .apim-table {
  width: 100%;
  border: 1px solid #D1D1D1;
  border-radius: 4px;
  border-spacing: 0;
}

.apim-table th {
  background: #E6E6E6;
  font-weight: bold;
  text-align: left;
}

.apim-table th,
.apim-table td {
  padding: .7em 1em;
}

.apim-table td {
  border-top: #E6E6E6 solid 1px;
}

.apim-input,
.apim-button,
.apim-nav-link-btn {
    border-radius: .33rem;
    padding: 0.6rem 1rem;
}

.apim-button,
.apim-nav-link-btn {
    background-color: var(--wp--preset--color--contrast);
    border-color: var(--wp--preset--color--contrast);
    border-width: 0;
    color: var(--wp--preset--color--base);
    font-size: var(--wp--preset--font-size--small);
    font-weight: 500;
    text-decoration: none;
    cursor: pointer;
    transition: all .25s ease;
}

.apim-nav-link-btn:hover {
    background: var(--wp--preset--color--base);
    color: var(--wp--preset--color--contrast);
}

.apim-button:hover {
    background: var(--wp--preset--color--vivid-cyan-blue);
}

.apim-button:disabled {
    background: var(--wp--preset--color--contrast-2);
    cursor: not-allowed;
}

.apim-label {
    display: block;
    margin-bottom: 0.5rem;
}

.apim-input {
    border: solid 1px var(--wp--preset--color--contrast);
}

.apim-grid {
    display: grid;
    grid-template-columns: 11em max-content;
}

.apim-link,
.apim-nav-link {
    text-align: inherit;
    font-size: inherit;
    padding: 0;
    background: none;
    border: none;
    font-weight: inherit;
    cursor: pointer;
    text-decoration: none;
    color: var(--wp--preset--color--vivid-cyan-blue);
}

.apim-nav-link {
    font-weight: 500;
}

.apim-link:hover,
.apim-nav-link:hover {
    text-decoration: underline;
}

#apim-signIn {
    display: flex;
    align-items: center;
    gap: 24px;
}

  6. 保存更改。 再次选择“保存”以保存对主题所做的更改。

  7. 从 WordPress 管理站点中退出登录。

步骤 9：登录到 WordPress 上部署的 API 管理开发人员门户

访问 WordPress 站点，查看部署在 WordPress 上并托管在应用服务上的新 API 管理开发人员门户。

  1. 在新的浏览器窗口中，导航到你的 WordPress 站点（请将以下 URL 中的占位符替换为你的应用服务名称）：https://<yourapp-service-name>.chinacloudsites.cn。

  2. 出现提示时，使用 Microsoft Entra ID 凭据登录到开发人员帐户。 如果启用了对开发人员门户的未经身份验证的访问权限，请在开发人员门户主页上选择“登录”。

注意

只能使用 Microsoft Entra ID 凭据登录到 WordPress 上的开发人员门户。 不支持基本身份验证。

现在可以使用 API 管理开发人员门户的以下功能：

  • 登录到门户
  • 查看 API 列表
  • 导航到 API 详细信息页面并查看操作列表
  • 使用有效的 API 密钥测试 API
  • 查看产品列表
  • 订阅产品并生成订阅密钥
  • 导航到包含帐户和订阅详细信息的“配置文件”选项卡
  • 退出门户

以下屏幕截图显示了托管在 WordPress 上的 API 管理开发人员门户的示例页面。

托管在 WordPress 上的开发人员门户的屏幕截图。

故障排除

WordPress 站点上未显示最新的开发人员门户页面

如果在访问 WordPress 站点时未看到最新的开发人员门户页面，请检查 WordPress 管理站点中是否安装、激活并配置了开发人员门户插件。 有关步骤，请参阅 安装开发人员门户插件。

如果已配置缓存，则可能需要清除 WordPress 站点或 Azure Front Door 上的缓存。 或者，可能需要清除浏览器上的缓存。

我在登录或退出登录开发人员门户时遇到问题

如果在登录或退出登录开发人员门户时遇到问题，请清除浏览器缓存，或在单独的浏览器会话中查看开发人员门户站点（使用隐身或私密浏览模式）。

开发人员门户导航栏上未显示登录按钮

如果使用的是与插件存储库中提供的自定义主题不同的自定义主题，则可能需要手动将登录功能添加到导航栏。 在主页上添加以下短代码块：[SignInButton]。 若要了解更多信息，请参阅 WordPress 文档。

也可以通过在浏览器中输入以下 URL 来手动登录或退出登录：

  • 登录：https://<app-service-name>.chinacloudsites.cn/.auth/login/aad
  • 退出登录：https://<app-service-name>.chinacloudsites.cn/.auth/logout

相关内容

  • Last updated on