教程:访问和自定义开发人员门户Tutorial: Access and customize the developer portal

开发人员门户是一个自动生成的、可完全自定义的网站,其中包含 API 的文档。The 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 管理实例。In the Azure portal, navigate to your API Management instance.
  2. 在顶部导航栏中选择“开发人员门户”按钮。Select 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 is automatically provisioned in the background. 默认内容旨在展示门户功能,并最大程度地减少个性化门户所需的自定义项。Default content has been designed to showcase the portal's capabilities and minimize the 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.
  • 通过单击带有加号的蓝色图标向页面添加行。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.
  • 使用拖放交互重新排列页面中的项。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, a 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 preceding image, 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, select it and select the pencil icon that appears on top of it. 在弹出窗口中进行更改后,请将其关闭。After you make the changes in the pop-up window, close it.

“保存”按钮Save button

“保存”按钮

在门户中进行更改时,需要通过选择底部菜单中的“保存”按钮,或按 [Ctrl]+[S] 来手动保存。Whenever you make a change in the portal, you need to save it manually by selecting the Save button in the menu at the bottom, or press [Ctrl]+[S]. 保存更改时,修改的内容会自动上传到 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 placeholder content. 可以删除包含此内容的整个部分,也可以保留结构并逐个调整元素。You can either remove entire sections containing this 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. 可以在门户的管理界面中或从 Azure 门户发布门户。You can publish the portal within the portal's administrative interface or from the Azure portal.

从管理界面发布Publish from the administrative interface

  1. 请确保通过选择“保存”图标保存更改。Make sure you saved your changes by selecting the Save icon.

  2. 在菜单的“操作”部分,选择“发布网站” 。In the Operations section of the menu, select Publish website . 此操作可能需要几分钟的时间。This operation may take a few minutes.

    发布门户

从 Azure 门户发布Publish from the Azure portal

  1. Azure 门户,导航到 API 管理实例。In the Azure portal, navigate to your API Management instance.

  2. 在左侧菜单中的“开发人员门户”下,选择“门户概述” 。In the left menu, under Developer portal, select Portal overview.

  3. 在“门户概述”窗口中,选择“发布” 。In the Portal overview window, select Publish.

    从 Azure 门户发布门户

备注

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

访问发布的门户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 (using incognito or private browsing mode) as an external visitor.

在 API 上应用 CORS 策略Apply the CORS policy on APIs

若要让门户的访问者通过内置交互控制台来测试 API,请在 API 上启用 CORS(跨域资源共享)。To let the visitors of your portal test the APIs through the built-in interactive console, enable CORS (cross-origin resource sharing) on your APIs. 有关详细信息,请参阅 Azure API 管理开发人员门户概述For details, see the Azure API Management developer portal overview.

后续步骤Next steps

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