如何使用模板自定义 Azure API 管理开发人员门户How to customize the Azure API Management developer portal using templates

在 Azure API 管理中自定义开发人员门户有三种基本方法:There are three fundamental ways to customize the developer portal in Azure API Management:

模板用于自定义系统生成的开发人员门户页的内容(例如,API 文档、产品、用户身份验证等)。Templates are used to customize the content of system-generated developer portal pages (for example, API docs, products, user authentication, etc.). 使用 DotLiquid 语法和一组提供的本地化字符串资源、图标和页面控件,可根据需要非常灵活地配置页面内容。Using DotLiquid syntax, and a provided set of localized string resources, icons, and page controls, you have great flexibility to configure the content of the pages as you see fit.

可用性Availability

Important

此功能在 API 管理的“高级”、“标准”、“基本”和“开发人员”层中可用。This feature is available in the Premium, Standard, Basic and Developer tiers of API Management.

开发人员门户模板概述Developer portal templates overview

在以管理员身份登录时,可从“开发人员门户”编辑模板。Editing templates is done from the Developer portal while being logged in as an administrator. 若要访问它,请先打开 Azure 门户,再单击 API 管理实例的服务工具栏中的“开发人员门户”。To get there first open the Azure Portal and click Developer portal from the service toolbar of your API Management instance.

若要访问开发人员门户模板,请单击左侧的自定义图标显示自定义菜单,并单击“模板”。To access the developer portal templates, click the customize icon on the left to display the customization menu, and click Templates.

开发人员门户模板

模板列表显示了模板的多个类别,涵盖开发人员门户中的不同页面。The templates list displays several categories of templates covering the different pages in the developer portal. 每个模板都不同,但编辑它们并发布更改的步骤均相同。Each template is different, but the steps to edit them and publish the changes are the same. 若要编辑模板,请单击模板的名称。To edit a template, click the name of the template.

开发人员门户模板

单击模板将转到由该模板自定义的开发人员门户页面。Clicking a template takes you to the developer portal page that is customizable by that template. 在此示例中,显示“产品列表”模板。In this example, the Product list template is displayed. “产品列表”模板控制红色矩形所示的屏幕区域。The Product list template controls the area of the screen indicated by the red rectangle.

产品列表模板

某些模板(如“用户配置文件”模板)自定义同一页面的不同部分。Some templates, like the User Profile templates, customize different parts of the same page.

用户配置文件模板

每个开发人员门户模板的编辑器都具有显示在页面底部的两个部分。The editor for each developer portal template has two sections displayed at the bottom of the page. 左侧显示模板的编辑窗格,右侧显示模板的数据模型。The left-hand side displays the editing pane for the template, and the right-hand side displays the data model for the template.

模板编辑窗格包含标记,用于控制开发人员门户中的对应页面的外观和行为。The template editing pane contains the markup that controls the appearance and behavior of the corresponding page in the developer portal. 模板中的标记使用 DotLiquid 语法。The markup in the template uses the DotLiquid syntax. DotLiquid 的一个流行编辑器是 DotLiquid for DesignersOne popular editor for DotLiquid is DotLiquid for Designers. 在编辑期间对模板所作的任何更改都实时显示在浏览器中,但在保存发布该模板之前对客户不可见。Any changes made to the template during editing are displayed in real-time in the browser, but are not visible to your customers until you save and publish the template.

模板标记

“模板数据”窗格提供可在特定模板中使用的实体的数据模型指南。The Template data pane provides a guide to the data model for the entities that are available for use in a particular template. 它通过显示当前在开发人员门户中显示的实时数据提供此指南。It provides this guide by displaying the live data that are currently displayed in the developer portal. 可通过单击“模板数据”窗格右上角的矩形展开模板窗格。You can expand the template panes by clicking the rectangle in the upper-right corner of the Template data pane.

模板数据模型

在前面的示例中,开发人员门户中显示两个从“模板数据”窗格中显示的数据检索的产品,如以下示例所示:In the previous example, there are two products displayed in the developer portal that were retrieved from the data displayed in the Template data pane, as shown in the following example:

{
    "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
        }
    ]
}

产品列表模板中的标记处理数据以显示所需的输出,方法是循环访问产品集合以显示信息和指向每个单独产品的链接。The markup in the Product list template processes the data to provide the desired output by iterating through the collection of products to display information and a link to each individual product. 请注意标记中的 <search-control><page-control> 元素。Note the <search-control> and <page-control> elements in the markup. 这些元素控制页面上的搜索和分页控件的显示。These control the display of the searching and paging controls on the page. ProductsStrings|PageTitleProducts 是一个本地化的字符串引用,包含页面的 h2 标题文本。ProductsStrings|PageTitleProducts is a localized string reference that contains the h2 header text for the page. 有关可在开发人员门户模板中使用的字符串资源、页面控件和图标的列表,请参阅 API 管理开发人员门户模板参考For a list of string resources, page controls, and icons available for use in developer portal templates, see API Management developer portal templates reference.

<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>

保存模板To save a template

若要模板,请在模板编辑器中单击“保存”。To save a template, click save in the template editor.

保存模板

已保存的更改在开发人员门户中不生效,直到它们发布。Saved changes are not live in the developer portal until they are published.

发布模板To publish a template

已保存的模板可单独发布,也可全部一起发布。Saved templates can be published either individually, or all together. 若要发布个别模板,请在模板编辑器中单击“发布”。To publish an individual template, click publish in the template editor.

发布模板

单击“是”进行确认并使模板在开发人员门户中生效。Click Yes to confirm and make the template live on the developer portal.

确认发布

若要发布所有当前未发布的模板版本,请单击模板列表中的“发布”。To publish all currently unpublished template versions, click Publish in the templates list. 未发布的模板由跟在模板名称之后的星号予以指示。Unpublished templates are designated by an asterisk following the template name. 在此示例中,将发布“产品列表”和“产品”模板。In this example, the Product list and Product templates are being published.

发布模板

单击“发布自定义”进行确认。Click Publish customizations to confirm.

确认发布

新发布的模板在开发人员门户中立即生效。Newly published templates are effective immediately in the developer portal.

将模板还原到以前版本To revert a template to the previous version

要将模板还原到以前发布的版本,请单击模板编辑器中的“还原”。To revert a template to the previous published version, click revert in the template editor.

还原模板

单击“是”确认。Click Yes to confirm.

确认

还原操作完成后,模板的以前发布的版本在开发人员门户中生效。The previously published version of a template is live in the developer portal once the revert operation is complete.

将模板还原到默认版本To restore a template to the default version

将模板还原到其默认版本的过程分为两步。Restoring templates to their default version is a two-step process. 首先,必须还原模板,然后必须发布还原后的版本。First the templates must be restored, and then the restored versions must be published.

若要将单个模板还原到默认版本,请在模板编辑器中单击“还原”。To restore a single template to the default version click restore in the template editor.

还原模板

单击“是”确认。Click Yes to confirm.

确认

若要将所有模板还原到其默认版本,请单击模板列表中的“还原默认模板”。To restore all templates to their default versions, click Restore default templates on the template list.

还原模板

然后,必须按照发布模板中的步骤分别或一起发布还原后的所有模板。The restored templates must then be published individually or all at once by following the steps in To publish a template.

后续步骤Next steps

有关开发人员门户模板、字符串资源、图标和页面控件的参考信息,请参阅 API 管理开发人员门户模板参考For reference information for developer portal templates, string resources, icons, and page controls, see API Management developer portal templates reference.