如何使用模板自定义 Azure API Management 开发人员门户

在 Azure API 管理中自定义开发人员门户有三种基本方法:

模板用于自定义系统生成的开发人员门户页的内容(例如,API 文档、产品、用户身份验证等)。 使用 DotLiquid 语法和一组提供的本地化字符串资源、图标和页面控件,可根据需要非常灵活地配置页面内容。

注意

以下文档内容与已弃用的开发人员门户有关。 你可以像往常一样继续使用它,直到它在 2023 年 10 月停用,届时将从所有 API 管理服务中将其删除。 弃用的门户只会接收关键安全更新。 有关更多详细信息,请参阅以下文章:

可用性

重要

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

开发人员门户模板概述

在以管理员身份登录时,可从“开发人员门户” 编辑模板。 若要访问它,请先打开 Azure 门户,再单击 API 管理实例的服务工具栏中的“开发人员门户”。

要访问开发人员门户模板,请单击左侧的自定义图标显示自定义菜单,并单击“模板” 。

Screenshot that highlights the customize icon to display the customization menu.

模板列表显示模板的多个类别,涵盖开发人员门户中的不同页面。 每个模板都不同,但编辑它们并发布更改的步骤均相同。 若要编辑模板,请单击模板的名称。

Developer portal templates

单击模板转到由该模板自定义的开发人员门户页面。 在此示例中,显示“产品列表” 模板。 “产品列表” 模板控制红色矩形所示的屏幕区域。

Products list template

某些模板(如“用户配置文件” 模板)自定义同一页面的不同部分。

User profile templates

每个开发人员门户模板的编辑器都具有两个在页面底部显示的部分。 左侧显示模板的编辑窗格,右侧显示模板的数据模型。

模板编辑窗格包含标记,用于控制开发人员门户中的对应页面的外观和行为。 模板中的标记使用 DotLiquid 语法。 DotLiquid 的一个流行编辑器是 DotLiquid for Designers。 在编辑期间对模板所作的任何更改都实时显示在浏览器中,但在保存发布该模板之前对客户不可见。

Template markup

“模板数据” 窗格提供可在特定模板中使用的实体的数据模型指南。 它通过显示当前在开发人员门户中显示的实时数据提供此指南。 可通过单击“模板数据” 窗格右上角的矩形展开模板窗格。

Template data model

在前面的示例中,开发人员门户中显示两个从“模板数据” 窗格中显示的数据检索的产品,如以下示例所示:

{
    "Paging": {
        "Page": 1,
        "PageSize": 10,
        "TotalItemCount": 2,
        "ShowAll": false,
        "PageCount": 1
    },
    "Filtering": {
        "Pattern": null,
        "Placeholder": "Search products"
    },
    "Products": [
        {
            "Id": "56ec64c380ed850042060001",
            "Title": "Starter",
            "Description": "Subscribers will be able to run 5 calls/minute up to a maximum of 100 calls/week.",
            "Terms": "",
            "ProductState": 1,
            "AllowMultipleSubscriptions": false,
            "MultipleSubscriptionsCount": 1
        },
        {
            "Id": "56ec64c380ed850042060002",
            "Title": "Unlimited",
            "Description": "Subscribers have completely unlimited access to the API. Administrator approval is required.",
            "Terms": null,
            "ProductState": 1,
            "AllowMultipleSubscriptions": false,
            "MultipleSubscriptionsCount": 1
        }
    ]
}

产品列表模板中的标记处理数据以显示所需的输出,方法是循环访问产品集合以显示信息和指向每个单独产品的链接。 请注意标记中的 <search-control><page-control> 元素。 这些元素控制页面上的搜索和分页控件的显示。 ProductsStrings|PageTitleProducts 是一个本地化字符串参考,包含页面的 h2 标题文本。 有关可在开发人员门户模板中使用的字符串资源、页面控件和图标的列表,请参阅 API 管理开发人员门户模板参考

<search-control></search-control>
<div class="row">
    <div class="col-md-9">
        <h2>{% localized "ProductsStrings|PageTitleProducts" %}</h2>
    </div>
</div>
<div class="row">
    <div class="col-md-12">
    {% if products.size > 0 %}
    <ul class="list-unstyled">
    {% for product in products %}
        <li>
            <h3><a href="/products/{{product.id}}">{{product.title}}</a></h3>
            {{product.description}}
        </li>
    {% endfor %}
    </ul>
    <paging-control></paging-control>
    {% else %}
    {% localized "CommonResources|NoItemsToDisplay" %}
    {% endif %}
    </div>
</div>

保存模板

若要模板,请在模板编辑器中单击“保存”。

Save template

已保存的更改在开发人员门户中不生效,直到它们发布。

发布模板

已保存的模板可单独或全部一起发布。 若要发布个别模板,请在模板编辑器中单击“发布”。

Publish template

单击“是” 确认并使模板在开发人员门户中生效。

Screenshot that shows where you select Yes to make the template live.

若要发布所有当前未发布的模板版本,请单击模板列表中的“发布” 。 未发布的模板通过模板名称后跟星号来指定。 在此示例中,将发布“产品列表” 和“产品” 模板。

Publish templates

单击“发布自定义” 确认。

Confirm publish

新发布的模板在开发人员门户中立即生效。

将模板还原到以前版本

要将模板还原到以前发布的版本,请单击模板编辑器中的“还原”。

Screenshot that highlights the icon you use to revert a template.

单击“是” 以确认。

Screenshot that shows where you select Yes to confirm the changes.

还原操作完成后,模板的以前发布的版本在开发人员门户中生效。

将模板还原到默认版本

将模板还原到其默认版本的过程分为两步。 首先必须还原模板,然后必须发布已还原的版本。

要将单个模板还原到默认版本,请在模板编辑器中单击“还原”。

Revert template

单击“是” 以确认。

Confirm

要将所有模板还原到其默认版本,请单击模板列表中的“还原默认模板” 。

Restore templates

然后,还原的模板必须按照发布模板中的步骤单独或全部同时发布。

后续步骤

有关开发人员门户模板、字符串资源、图标和页面控件的参考信息,请参阅 API 管理开发人员门户模板参考