开发人员门户概述Overview of the developer portal

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

本文介绍了 API 管理中开发人员门户的自承载版本与托管版本之间的差异。This article describes the differences between self-hosted and managed versions of the developer portal in API Management. 它还提供常见问题的答案。It also provides answers to frequently asked questions.

API 管理开发人员门户



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

从旧门户迁移Migration from the legacy portal


旧开发人员门户现在已弃用,并且将仅接收安全更新。The legacy developer portal is now deprecated and it will receive security updates only. 你可以像往常一样继续使用它,直到它在 2023 年 10 月停用,届时将从所有 API 管理服务中将其删除。You can continue to use it, as per usual, until its retirement in October 2023, when it will be removed from all API Management services.

专用文档文章中介绍了到新开发人员门户的迁移。Migration to the new developer portal is described in the dedicated documentation article.

自定义和样式Customization and styling

可通过内置的拖放可视化编辑器对开发人员门户进行自定义和样式设置。The developer portal can be customized and styled through the built-in, drag-and-drop visual editor. 有关更多详细信息,请参阅本教程See this tutorial for more details.


API 管理服务包括始终保持最新的内置托管开发人员门户。Your API Management service includes a built-in, always up-to-date, managed developer portal. 可以从 Azure 门户界面访问它。You can access it from the Azure portal interface.

如果需要用自定义逻辑(不支持开箱即用)来扩展它,可以修改其代码库。If you need to extend it with custom logic, which isn't supported out-of-the-box, you can modify its codebase. 门户的代码库在 GitHub 存储库中可用The portal's codebase is available in a GitHub repository. 例如,你可以实现与第三方支持系统集成的新的小组件。For example, you could implement a new widget, which integrates with a third-party support system. 实现新功能时,可以选择以下选项之一:When you implement new functionality, you can choose one of the following options:

  • 在 API 管理服务之外自行承载生成的门户。Self-host the resulting portal outside of your API Management service. 当你自行承载门户时,你将成为门户的维护人员并负责其升级。When you self-host the portal, you become its maintainer and you are responsible for its upgrades. Azure 支持的协助仅限于自承载门户的基本设置,如存储库的 Wiki 部分所述。Azure Support's assistance is limited only to the basic setup of self-hosted portals, as documented in the Wiki section of the repository.
  • 为 API 管理团队打开拉取请求,以将新功能合并到托管门户的代码库。Open a pull request for the API Management team to merge new functionality to the managed portal's codebase.

有关扩展性的详细信息和说明,请参阅 GitHub 存储库有关实现小组件的教程For extensibility details and instructions, refer to the GitHub repository and the tutorials on implementing a widget. 自定义托管门户的教程介绍了门户的管理面板,该面板在托管版本和自承载版本中很常见 。The tutorial for customizing the managed portal walks you through the portal's administrative panel, which is common for managed and self-hosted versions.

常见问题Frequently asked questions

本部分解答有关开发人员门户的一般性常见问题。In this section, we answer common questions about the developer portal, which are of general nature. 有关自承载版本的特定问题,请参阅 GitHub 存储库的 wiki 部分For questions specific to the self-hosted version, refer to the wiki section of the GitHub repository.

如何从门户预览版迁移?How can I migrate from the preview version of the portal?

首次启动开发人员门户预览版时,你在 API 管理服务中预配了其默认内容的预览版。When you first launched the preview version of developer portal, you provisioned the preview version of its default content in your API Management service. 正式版中的默认内容已进行重大修改。The default content has been significantly modified in the generally available version. 例如,默认内容的预览版不包括登录页面中的 OAuth 按钮,它使用不同的小组件来显示 API,并依赖有限的功能来构建开发人员门户页面。For example, the preview version of default content doesn't include OAuth buttons in the log-in pages, it uses different widgets for displaying APIs, and relies on limited capabilities for structuring developer portal pages. 即使内容存在差异,门户的引擎(包括基础小组件)也会在每次发布开发人员门户时自动更新。Even though there are differences in the content, the portal's engine (including underlying widgets) is automatically updated every time you publish your developer portal.

如果根据内容的预览版对门户进行了大量自定义,可以继续按原样使用它,并在门户的页面上手动放置新的小组件。If you heavily customized your portal based on the preview version of content, you may continue to use it as is and place new widgets manually on portal's pages. 否则,建议将门户内容替换为新的默认内容。Otherwise, we recommend replacing your portal's content with the new default content.

若要重置托管门户中的内容,请选择“操作”菜单部分中的“重置内容” 。To reset the content in a managed portal, select Reset content in the Operations menu section. 此操作将删除门户的所有内容并预配新的默认内容。This operation will remove all the content of the portal and provision new default content. 你将丢失所有开发人员门户自定义和更改。You will lose all developer portal customizations and changes. 不能撤消此操作。You can't undo this action.


如果使用的是自承载版本,请运行 GitHub 存储库中的 scripts.v2/cleanup.batscripts.v2/generate.bat 脚本删除现有内容并预配新内容。If you're using the self-hosted version, run scripts.v2/cleanup.bat and scripts.v2/generate.bat scripts from the GitHub repository to remove existing content and provision new content. 确保提前将门户代码升级到 GitHub 存储库中的最新版本。Make sure to upgrade your portal's code to the latest release from the GitHub repository beforehand.

如果是在 2019 年 11 月正式发布后首次访问门户,则该门户应已具有新的默认内容,无需执行其他操作。If you first accessed the portal after the general availability announcement in November 2019, it should already feature the new default content and no further action is required.

门户不支持我需要的功能Functionality I need isn't supported in the portal

可以在 GitHub 存储库中打开功能请求或自行实现缺失的功能You can open a feature request in the GitHub repository or implement the missing functionality yourself. 有关更多详细信息,请参阅上面的“扩展性”部分。See the Extensibility section above for more details.

如何自动部署门户?How can I automate portal deployments?

不管使用的是托管版本还是自承载版本,都可以通过 REST API 以编程方式访问和管理开发人员门户的内容。You can programmatically access and manage the developer portal's content through the REST API, regardless if you're using a managed or a self-hosted version.

GitHub 存储库的 Wiki 部分介绍了该 API。The API is documented in the GitHub repository's wiki section. 可以使用该 API 在环境之间自动迁移门户内容(例如,从测试环境迁移到生产环境)。It can be used for automating migrations of portal content between environments - for example, from a test environment to the production environment. 可以在 GitHub 上的此文档中详细了解此过程。You can learn more about this process in this documentation article on GitHub.

如何从托管版本迁移到自承载版本?How do I move from the managed to the self-hosted version?

请参阅 GitHub 上的开发人员门户存储库的 Wiki 部分文章。See the detailed article in the Wiki section of the developer portal repository on GitHub.

能否在一个 API 管理服务中有多个开发人员门户?Can I have multiple developer portals in one API Management service?

可以有一个托管门户和多个自承载门户。You can have one managed portal and multiple self-hosted portals. 所有门户的内容都存储在同一个 API 管理服务中,因此它们是相同的。The content of all portals is stored in the same API Management service, so they will be identical. 如果希望门户的外观和功能不同,可以使用自己的自定义小组件对其进行自承载,以便在运行时上动态自定义页面(例如基于 URL)。If you want to differentiate portals' appearance and functionality, you can self-host them with your own custom widgets that dynamically customize pages on runtime, for example based on the URL.

门户是否支持 Azure 资源管理器模板,和/或是否与 API 管理 DevOps 资源工具包兼容?Does the portal support Azure Resource Manager templates and/or is it compatible with API Management DevOps Resource Kit?


门户的内容是否随 API 管理中的备份/还原功能一起保存?Is the portal's content saved with the backup/restore functionality in API Management?


是否需要为托管门户依赖项启用额外的 VNet 连接?Do I need to enable additional VNet connectivity for the managed portal dependencies?

大多数情况下是不需要的。In most cases - no.

如果 API 管理服务位于内部 VNet 中,则只能从网络内部访问开发人员门户。If your API Management service is in an internal VNet, your developer portal is only accessible from within the network. 管理终结点的主机名必须解析成用于访问门户管理界面的计算机中的服务的内部 VIP。The management endpoint's host name must resolve to the internal VIP of the service from the machine you use to access the portal's administrative interface. 请确保管理终结点已在 DNS 中注册。Make sure the management endpoint is registered in the DNS. 如果配置不当,将会出现以下错误:Unable to start the portal. See if settings are specified correctly in the configuration (...)In case of misconfiguration, you will see an error: Unable to start the portal. See if settings are specified correctly in the configuration (...).

如果 API 管理服务位于内部 VNet 中,并且是通过 Internet 上的应用程序网关访问它,请确保启用与开发人员门户和“API 管理”的管理终结点的连接。If your API Management service is in an internal VNet and you're accessing it through Application Gateway from the Internet, make sure to enable connectivity to the developer portal and the management endpoints of API Management. 可能需要禁用 Web 应用程序防火墙规则。You may need to disable Web Application Firewall rules. 有关更多详细信息,请参阅此文档文章See this documentation article for more details.

我已分配一个自定义 API 管理域,但发布的门户无法正常工作I have assigned a custom API Management domain and the published portal doesn't work

更新域后,需要重新发布门户才能使更改生效。After you update the domain, you need to republish the portal for the changes to take effect.

我已添加一个标识提供者,但门户中未显示它I have added an identity provider and I can't see it in the portal

配置标识提供者(例如 Azure AD、AAD B2C)之后,需要重新发布门户才能使更改生效。After you configure an identity provider (for example, Azure AD, Azure AD B2C), you need to republish the portal for the changes to take effect. 请确保开发人员门户页包含 OAuth 按钮小组件。Make sure your developer portal pages include the OAuth buttons widget.

我已设置委托,但门户不使用它I have set up delegation and the portal doesn't use it

设置委托后,需要重新发布门户才能使更改生效。After you set up delegation, you need to republish the portal for the changes to take effect.

我的其他 API 管理配置更改未传播到开发人员门户中My other API Management configuration changes haven't been propagated in the developer portal

大多数配置更改(例如 VNet、登录和产品条款)都需要重新发布门户Most configuration changes (for example, VNet, sign-in, product terms) require republishing the portal.

使用交互式控制台时出现 CORS 错误I'm getting a CORS error when using the interactive console

交互式控制台从浏览器发出客户端 API 请求。The interactive console makes a client-side API request from the browser. 通过在 API 中添加 CORS 策略解决 CORS 问题。Resolve the CORS problem by adding a CORS policy on your API(s).

可以在 Azure 门户的 API 管理服务的“门户概述”部分中检查 CORS 策略的状态。You can check the status of the CORS policy in the Portal overview section of your API Management service in the Azure portal. 警告框指示缺少策略或策略配置不正确。A warning box indicates an absent or misconfigured policy.

显示可检查 CORS 策略状态的位置的屏幕截图。

通过单击“启用 CORS”按钮自动应用 CORS 策略。Automatically apply the CORS policy by clicking on the Enable CORS button.

还可以手动启用 CORS。You can also enable CORS manually.

  1. 选择“在全局级别上手动应用”链接以查看生成的策略代码。Select the Manually apply it on the global level link to see the generated policy code.
  2. 在 Azure 门户中导航到 API 管理服务的“API”部分的“所有 API” 。Navigate to All APIs in the APIs section of your API Management service in the Azure portal.
  3. 在“入站处理”部分中,选择 </> 图标 。Select the </> icon in the Inbound processing section.
  4. 将策略插入到 XML 文件的 部分中。Insert the policy in the section of the XML file. 请确保 值与开发人员门户的域匹配。Make sure the value matches your developer portal's domain.


如果在产品范围而不是 API 范围内应用 CORS 策略,并且 API 通过标头使用订阅密钥身份验证,则控制台无法正常工作。If you apply the CORS policy in the Product scope, instead of the API(s) scope, and your API uses subscription key authentication through a header, your console won't work.

浏览器会自动发出 OPTIONS HTTP 请求,但该请求不包含带有订阅密钥的标头。The browser automatically issues an OPTIONS HTTP request, which doesn't contain a header with the subscription key. 由于缺少订阅密钥,API 管理无法将 OPTIONS 调用与产品相关联,因此也就无法应用 CORS 策略。Because of the missing subscription key, API Management can't associate the OPTIONS call with a Product, so it can't apply the CORS policy.

解决方法之一是在查询参数中传递订阅密钥。As a workaround you can pass the subscription key in a query parameter.


仅执行一个 CORS 策略。Only one CORS policy is executed. 如果你指定了多个 CORS 策略(例如在 API 级别和所有 API 级别),则交互式控制台可能不会按预期方式工作。If you specified multiple CORS policies (for example, on the API level and on the all-APIs level), your interactive console may not work as expected.

编辑开发人员门户需要哪些权限?What permissions do I need to edit the developer portal?

如果在管理模式下打开门户时出现 Oops. Something went wrong. Please try again later. 错误,则原因可能是缺少所需的权限 (Azure RBAC)。If you're seeing the Oops. Something went wrong. Please try again later. error when you open the portal in the administrative mode, you may be lacking the required permissions (Azure RBAC).

旧门户需要服务范围 (/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ApiManagement/service/<apim-service-name>) 的 Microsoft.ApiManagement/service/getssotoken/action 权限,以允许用户管理员访问门户。The legacy portals required the permission Microsoft.ApiManagement/service/getssotoken/action at the service scope (/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ApiManagement/service/<apim-service-name>) to allow the user administrator access to the portals. 新门户需要 /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ApiManagement/service/<apim-service-name>/users/1 范围的 Microsoft.ApiManagement/service/users/token/action 权限。The new portal requires the permission Microsoft.ApiManagement/service/users/token/action at the scope /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ApiManagement/service/<apim-service-name>/users/1.

可以使用以下 PowerShell 脚本创建拥有所需权限的角色。You can use the following PowerShell script to create a role with the required permission. 请记得更改 <subscription-id> 参数。Remember to change the <subscription-id> parameter.

#New Portals Admin Role 
Import-Module Az 
Connect-AzAccount  -Environment AzureChinaCloud
$contributorRole = Get-AzRoleDefinition "API Management Service Contributor" 
$customRole = $contributorRole 
$customRole.Id = $null
$customRole.Name = "APIM New Portal Admin" 
$customRole.Description = "This role gives the user ability to log in to the new Developer portal as administrator" 
$customRole.Actions = "Microsoft.ApiManagement/service/users/token/action" 
$customRole.IsCustom = $true 
New-AzRoleDefinition -Role $customRole 

创建角色后,可以通过 Azure 门户中的“访问控制(IAM)”部分将其授予任何用户。Once the role is created, it can be granted to any user from the Access Control (IAM) section in the Azure portal. 将此角色分配给用户会在服务范围分配权限。Assigning this role to a user will assign the permission at the service scope. 该用户可以代表服务中的任何用户生成 SAS 令牌。The user will be able to generate SAS tokens on behalf of any user in the service. 最起码需要将此角色分配给服务的管理员。At the minimum, this role needs to be assigned to the administrator of the service. 以下 PowerShell 命令演示如何在最低范围将角色分配给用户 user1,以避免向该用户授予不必要的权限:The following PowerShell command demonstrates how to assign the role to a user user1 at the lowest scope to avoid granting unnecessary permissions to the user:

New-AzRoleAssignment -SignInName "user1@contoso.com" -RoleDefinitionName "APIM New Portal Admin" -Scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ApiManagement/service/<apim-service-name>/users/1" 

向用户授予权限后,该用户必须注销并重新登录到 Azure 门户,才能使新权限生效。After the permissions have been granted to a user, the user must sign out and sign in again to the Azure portal for the new permissions to take effect.

出现 Unable to start the portal. See if settings are specified correctly (...) 错误I'm seeing the Unable to start the portal. See if settings are specified correctly (...) error

https://<management-endpoint-hostname>/subscriptions/xxx/resourceGroups/xxx/providers/Microsoft.ApiManagement/service/xxx/contentTypes/document/contentItems/configuration?api-version=2018-06-01-preview 发出 GET 调用失败时会显示此错误。This error is shown when a GET call to https://<management-endpoint-hostname>/subscriptions/xxx/resourceGroups/xxx/providers/Microsoft.ApiManagement/service/xxx/contentTypes/document/contentItems/configuration?api-version=2018-06-01-preview fails. 该调用是在浏览器中通过门户的管理界面发出的。The call is issued from the browser by the administrative interface of the portal.

如果 API 管理服务位于 VNet 中,请参阅前面的 VNet 连接问题。If your API Management service is in a VNet - refer to the VNet connectivity question above.

调用失败也可能是 TLS/SSL 证书引起的,该证书已分配到自定义域,且不受浏览器信任。The call failure may also be caused by an TLS/SSL certificate, which is assigned to a custom domain and is not trusted by the browser. 作为缓解措施,可以删除管理终结点自定义域 - API 管理将回退到包含受信任证书的默认终结点。As a mitigation, you can remove the management endpoint custom domain - API Management will fall back to the default endpoint with a trusted certificate.

门户对浏览器的支持是什么?What's the browser support for the portal?

浏览者Browser 支持Supported
Apple SafariApple Safari 1Yes1
Google ChromeGoogle Chrome 1Yes1
Microsoft EdgeMicrosoft Edge 1Yes1
Microsoft Internet ExplorerMicrosoft Internet Explorer No
Mozilla FirefoxMozilla Firefox 1Yes1

1 在两个最新的生产版本中受支持。1 Supported in the two latest production versions.

后续步骤Next steps

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

浏览其他资源:Browse other resources: