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

可用性

重要

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

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

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

先决条件

  • API 管理实例。 如果需要,请创建一个实例

    注意

    目前,API 管理 v2 层不支持该插件。

  • 启用并发布开发人员门户。 有关步骤,请参阅教程:访问和自定义开发人员门户
  • 在与 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”页面上的“基本信息”选项卡中,输入项目详细信息

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

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

    1. 为“使用 Azure 通信服务发送电子邮件”、“Azure CDN”和“Azure Blob 存储”选择建议的默认值
    2. 在“虚拟网络”中,选择“新建”值或现有虚拟网络
  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. 在“身份验证”页面上的“单页应用程序”下,选择“添加 URI”,然后输入以下 URI(替换为你的 API 管理实例名称)

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

  10. 在“隐式授权和混合流”下,依次选择“ID 令牌”、“保存”

  11. 在左侧菜单中的“管理”下,选择“令牌配置”>“+ 添加可选声明”

  12. 在“添加可选声明”页面上选择“ID”,然后选择以下声明:email、family_name、given_name、onprem_sid、preferred_username、upn。 选择 添加

  13. 如果出现提示,请选择“启用 Microsoft Graph电子邮件、配置文件权限”。 选择 添加

  14. 在左侧菜单中的“管理”下选择“API 权限”,并确认存在以下 Microsoft Graph 权限:email、profile、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”

      重要

      请不要对颁发者 URL(以 /v2.0 结尾的 URL)使用 2.0 版终结点。

  5. 在“允许的令牌受众”中,输入应用注册的“应用程序 ID URI”。 示例:api://<app-id>
  6. 在“其他检查”下,选择适合你的环境的值,或使用默认值
  7. 为剩余设置配置所需的值,或者使用默认值。 选择 添加

    注意

    如果想要允许来宾用户以及登录用户访问 WordPress 上的开发人员门户,可启用未经身份验证的访问。 在“限制访问”中,选择“允许未经身份验证的访问”。 了解详细信息

标识提供者随即会添加到应用服务。

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

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

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

  2. 在左侧菜单中的“开发人员门户”下,选择“标识”>“+ 添加”

  3. 在“添加标识提供者”页面上,选择“Azure Active Directory”(Microsoft Entra ID)

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

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

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

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

  8. 通过以下 URL(替换为你的 API 管理实例名称)登录到开发人员门户来测试身份验证:https://<apim-instance-name>.developer.azure-api.cn/signin。 选择底部的“Azure Active Directory”(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 站点上的开发人员门户测试控制台进行调用。

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

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

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

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

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

重要

我们建议上传插件存储库中提供的主题。 该主题基于 Twenty Twenty Four 主题,并经过自定义,可支持 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 站点或 CDN 上配置了缓存,则还可能需要清除缓存。 或者,可能需要清除浏览器上的缓存。

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

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

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

如果你使用的主题不同于插件存储库中提供的主题,则可能需要手动将登录功能添加到导航栏。 在主页上添加以下短代码块:[SignInButton]。 在 WordPress 文档中了解详细信息

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

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