访问和自定义开发人员门户Access and customize developer portal

开发人员门户是一个自动生成的、完全可自定义的网站,其中包含 API 的文档。Developer portal is an automatically generated, fully customizable website with the documentation of your APIs. API 使用者可在其中找到 API、了解 API 的用法以及请求访问权限。It is where API consumers can discover your APIs, learn how to use them, and request access.

本教程介绍如何执行下列操作:In this tutorial, you learn how to:

  • 访问托管版开发人员门户Access the managed version of the developer portal
  • 在门户管理界面中导航Navigate its administrative interface
  • 自定义内容Customize the content
  • 发布更改Publish the changes
  • 查看发布的门户View the published portal

可以在 Azure API 管理开发人员门户概述中找到有关开发人员门户的详细信息。You can find more details on the developer portal in the Azure API Management developer portal overview.

API 管理开发人员门户 - 管理模式

先决条件Prerequisites

可用性Availability

重要

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

以管理员身份访问门户Access the portal as an administrator

遵循以下步骤访问托管版本的门户。Follow the steps below to access the managed version of the portal.

  1. 在 Azure 门户中转到你的 API 管理服务实例。Go to your API Management service instance in the Azure portal.
  2. 单击顶部导航栏中的“开发人员门户”按钮。 Click on the Developer portal button in the top navigation bar. 此时会打开一个新的浏览器标签页,其中包含管理版本的门户。A new browser tab with an administrative version of the portal will open.

了解门户的管理界面Understand the portal's administrative interface

默认内容Default content

首次访问门户时,将自动在后台预配默认内容。If you're accessing the portal for the first time, the default content will be automatically provisioned in the background. 默认内容旨在展示门户的功能,并最大程度地减少个性化门户所要完成的自定义工作量。Default content has been designed to showcase portal's capabilities and minimize the amount of customizations needed to personalize your portal. 可以在 Azure API 管理开发人员门户概述中详细了解具体的门户内容。You can learn more about what is included in the portal content in the Azure API Management developer portal overview.

视觉编辑器Visual editor

可以使用视觉编辑器来自定义门户的内容。You can customize the content of the portal with the visual editor. 使用左侧的菜单部分可以创建或修改页面、媒体、布局、菜单、样式或网站设置。The menu sections on the left let you create or modify pages, media, layouts, menus, styles, or website settings. 使用底部的菜单项可以在视区之间切换(例如,切换为移动或桌面版)、查看门户中向已进行身份验证的用户或匿名用户显示的元素,或者保存或撤消操作。The menu items on the bottom let you switch between viewports (for example, mobile or desktop), view the elements of the portal visible to authenticated or anonymous users, or save or undo actions.

单击带有加号的蓝色图标可以在页面中添加行。You can add rows to a page by clicking on a blue icon with a plus sign. 按下带有加号的灰色图标可以添加小组件(例如文本、图像或 API 列表)。Widgets (for example, text, images, or APIs list) can be added by pressing a grey icon with a plus sign. 可以使用拖放交互操作重新排列页面中的项。You can rearrange items in a page with the drag-and-drop interaction.

布局和页面Layouts and pages

页面和布局

布局定义页面的显示方式。Layouts define how pages are displayed. 例如,默认内容中有两个布局 - 一个布局应用于主页,另一个布局应用于所有剩余页面。For example, in the default content, there are two layouts - one applies to the home page, and the other to all remaining pages.

将布局的 URL 模板与页面的 URL 相匹配即可将该布局应用到该页面。A layout gets applied to a page by matching its URL template to the page's URL. 例如,使用 URL 模板 /wiki/* 的布局将应用到其 URL 包含 /wiki/ 段的每个页面:/wiki/getting-started/wiki/styles,等等。For example, layout with a URL template of /wiki/* will be applied to every page with the /wiki/ segment in the URL: /wiki/getting-started, /wiki/styles, etc.

在上面的图像中,属于该布局的内容标为蓝色,页面标为红色。In the image above, content belonging to the layout is marked in blue, while the page is marked in red. 不同的菜单部分做了相应的标记。The menu sections are marked respectively.

样式指引Styling guide

样式指引

样式指引是根据设计器创建的面板。Styling guide is a panel created with designers in mind. 在此面板中可以检查门户中的所有视觉元素并设置其样式。It allows for overseeing and styling all the visual elements in your portal. 样式是分层的 - 许多元素从其他元素继承属性。The styling is hierarchical - many elements inherit properties from other elements. 例如,按钮元素使用文本和背景的颜色。For example, button elements use colors for text and background. 若要更改按钮颜色,需要更改原始颜色变体。To change a button's color, you need to change the original color variant.

若要编辑某个变体,请单击它,并选择其顶部显示的铅笔图标。To edit a variant, click on it and select the pencil icon that appears on top of it. 在弹出窗口中进行更改后将其关闭。Once you make the changes in the pop-up window, close it.

“保存”按钮Save button

“保存”按钮

每当在门户中进行更改,都需要按下底部菜单中的“保存”按钮来手动保存更改。 Whenever you make a change in the portal, you need to save it manually by pressing the Save button in the menu at the bottom. 保存更改时,修改的内容会自动上传到 API 管理服务。When you save your changes, the modified content is automatically uploaded to your API Management service.

自定义门户的内容Customize the portal's content

在将门户提供给访问者使用之前,应个性化自动生成的内容。Before you make your portal available to the visitors, you should personalize the automatically generated content. 建议的更改包括主页的布局、样式和内容。Recommended changes include the layouts, styles, and the content of the home page.

备注

由于集成方面的因素,无法删除以下页面或将其移到不同的 URL 下:/404/500/captcha/change-password/config.json/confirm/invitation/confirm-v2/identities/basic/signup/confirm-v2/password/internal-status-0123456789abcdef/publish/signin/signin-sso/signupDue to integration considerations, the following pages can't be removed or moved under a different URL: /404, /500, /captcha, /change-password, /config.json, /confirm/invitation, /confirm-v2/identities/basic/signup, /confirm-v2/password, /internal-status-0123456789abcdef, /publish, /signin, /signin-sso, /signup.

主页Home page

默认主页中已填充虚构内容。The default Home page is filled with dummy content. 可以删除包含这些内容的整个部分,或保留结构并逐个调整元素。You can either remove the whole sections with the content or keep the structure and adjust the elements one by one. 将生成的文本和图像替换为自己的内容,并确保链接指向所需的位置。Replace the generated text and images with your own and make sure the links point to desired locations.

布局Layouts

将导航栏中自动生成的徽标替换为自己的图像。Replace the automatically generated logo in the navigation bar with your own image.

样式Styling

尽管无需调整任何样式,但可以考虑调整特定的元素。Although you don't need to adjust any styles, you may consider adjusting particular elements. 例如,更改主色,使之与自己的品牌色相匹配。For example, change the primary color to match your brand's color.

发布门户 Publish the portal

若要将门户提供给访问者使用并反映其最新更改,需要发布门户。To make your portal and its latest changes available to visitors, you need to publish it.

  1. 请务必单击“保存”图标保存更改。 Make sure you saved your changes by clicking on the Save icon.
  2. 在菜单的“操作”部分单击“发布网站”。 Click on Publish website in the Operations section of the menu. 此操作可能需要几分钟的时间。This operation may take a few minutes.
    发布门户Publish portal

备注

API 管理服务配置更改后,需要重新发布门户,例如分配自定义域、更新标识提供者、设置委托、指定登录和产品条款等。The portal needs to be republished after API Management service configuration changes, such as assigning a custom domain, updating the identity providers, setting delegation, specifying sign-in and product terms, and more.

访问发布的门户Visit the published portal

发布门户后,可以通过管理面板所用的相同 URL(例如 https://contoso-api.developer.azure-api.cn)访问该门户。After you publish the portal, you can access it at the same URL as the administrative panel, for example https://contoso-api.developer.azure-api.cn. 在单独的浏览器会话(incognito/专用浏览模式)中以外部访问者身份查看它。View it in a separate browser session (incognito / private browsing mode) as an external visitor.

后续步骤Next steps

详细了解开发人员门户:Learn more about the developer portal: