Azure API 管理开发人员门户概述Azure API Management developer portal overview

开发人员门户是一个自动生成的、完全可自定义的网站,其中包含 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 explains its architecture and provides answers to frequently asked questions.

API 管理开发人员门户

可用性Availability

重要

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

托管版本和自承载版本Managed and self-hosted versions

可通过两种方式构建开发人员门户:You can build your developer portal in two ways:

  • 托管版本 - 通过编辑和自定义 API 管理实例中内置的、可通过 URL <your-api-management-instance-name>.developer.azure-api.net 访问的门户。Managed version - by editing and customizing the portal, which is built into your API Management instance and is accessible through the URL <your-api-management-instance-name>.developer.azure-api.net. 请参阅此文档了解如何访问和自定义托管门户。Refer to this documentation article to learn how to access and customize the managed portal.
  • 自承载版本 - 通过在 API 管理实例外部部署和自承载门户。Self-hosted version - by deploying and self-hosting your portal outside of an API Management instance. 使用此方法可编辑门户的基本代码并扩展提供的核心功能,例如实现自定义小组件以便与第三方系统集成。This approach allows you to edit the portal's codebase and extend the provided core functionality - for example, implement custom widgets for integrations with third party systems. 在此方案中,你是门户的维护人员,负责将门户升级到最新版本。In this scenario, you are the portal's maintainer and you are responsible for upgrading the portal to the latest version. 有关详细信息和说明,请参阅包含门户源代码的 GitHub 存储库有关实现小组件的教程For details and instructions, refer to the GitHub repository with the source code of the portal and the tutorial on implementing a widget. 托管版本的教程演练了门户的管理面板,该面板在托管版本和自承载版本中很常见。The tutorial for the managed version walks through the portal's administrative panel, which is common for the managed and the self-hosted versions.

门户体系结构概念Portal architectural concepts

门户组件在逻辑上可以划分为两个类别:代码和内容。 The portal components can be logically divided into two categories: code and content.

代码在 GitHub 存储库中维护,包括:Code is maintained in the GitHub repository and includes:

  • 小组件 - 呈现视觉元素并组合了 HTML、JavaScript、样式功能、设置和内容映射。Widgets - which represent visual elements and combine HTML, JavaScript, styling ability, settings, and content mapping. 例如,图像、文本段落、表单、API 列表等。Examples are an image, a text paragraph, a form, a list of APIs etc.
  • 样式定义 - 指定如何设置小组件的样式Styling definitions - which specify how widgets can be styled
  • 引擎 - 基于门户内容生成静态网页,是以 JavaScript 编写的Engine - which generates static webpages from portal content and is written in JavaScript
  • 视觉编辑器 - 用于浏览器内部的自定义和创作体验Visual editor - which allows for in-browser customization and authoring experience

内容划分为两个子类别:门户内容和 API 管理内容。 Content is divided into two subcategories: portal content and API Management content.

门户内容特定于门户,包括:Portal content is specific to the portal and includes:

  • 页面 - 例如登陆页、API 教程和博客文章Pages - for example, landing page, API tutorials, blog posts
  • 媒体 - 图像、动画和其他基于文件的内容Media - images, animations, and other file-based content
  • 布局 - 与 URL 匹配的模板,定义页面显示方式Layouts - templates, which are matched against a URL and define how pages are displayed
  • 样式 - 样式定义值,例如字体、颜色和边框Styles - values for styling definitions, e.g. fonts, colors, borders
  • 设置 - 网站图标、网站元数据等配置Settings - configuration, e.g. favicon, website metadata

门户内容(媒体除外)以 JSON 文档的形式表示。Portal content, except for media, is expressed as JSON documents.

API 管理内容包括 API、操作、产品和订阅等实体。API Management content includes entities such as APIs, Operations, Products, Subscriptions.

门户基于 Paperbits 框架的改编分叉。The portal is based on an adapted fork of the Paperbits framework. 原始 Paperbits 功能已经过扩展,提供特定于 API 管理的小组件(例如 API 列表、产品列表)以及与 API 管理服务之间的连接器,可以保存和检索内容。The original Paperbits functionality has been extended to provide API Management-specific widgets (for example, a list of APIs, a list of Products) and a connector to API Management service for saving and retrieving content.

常见问题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 管理服务中预配了预览内容。By using the preview version of the developer portal, you provisioned the preview content in your API Management service. 为了提供更好的用户体验,默认内容已在正式版中进行重大修改。The default content has been significantly modified in the generally available version for better user experience. 正式版中还包括新的小组件。It also includes new widgets.

如果使用的是托管版本,请通过单击“操作”菜单部分中的“重置内容”来重置门户内容。 If you're using the managed version, reset the content of the portal by clicking Reset content in the Operations menu section. 确认此操作会删除门户的所有内容并预配新的默认内容。Confirming this operation will remove all the content of the portal and provision the new default content. 门户引擎已在 API 管理服务中自动更新。The portal's engine has been automatically updated in your API Management service.

重置门户内容

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

如果不想要重置门户内容,可以考虑在整个页面中使用新的可用小组件。If you don't want to reset the content of the portal, you may consider using newly available widgets throughout your pages. 现有的小组件已自动更新到最新版本。Existing widgets have been automatically updated to the latest versions.

如果门户是宣布推出正式版后预配的,则它应已具有新的默认内容。If your portal was provisioned after the general availability announcement, it should already feature the new default content. 你无需在自己的一端执行任何操作。No action is required from your side.

如何从旧开发人员门户迁移到开发人员门户?How can I migrate from the old developer portal to the developer portal?

这两个门户不兼容,需要手动迁移内容。Portals are incompatible and you need to migrate the content manually.

门户是否拥有旧门户的所有功能?Does the portal have all the features of the old portal?

开发人员门户不再支持“应用程序”和“问题” 。The developer portal no longer supports Applications and Issues.

目前尚不支持在交互式开发人员控制台中使用 OAuth 进行身份验证。Authentication with OAuth in the interactive developer console is not yet supported. 可以通过 GitHub 问题跟踪进度。You can track the progress through the GitHub issue.

旧门户是否已弃用?Has the old portal been deprecated?

旧的开发人员和发布者门户现在属于旧版功能 - 它们只会接收安全更新。The old developer and publisher portals are now legacy features - they will be receiving security updates only. 新功能只会在新开发人员门户中实现。New features will be implemented in the new developer portal only.

旧门户弃用时,我们会另行通告。Deprecation of the legacy portals will be announced separately. 若有问题、疑虑或意见,请提出相关的 GitHub 问题If you have questions, concerns, or comments, raise them in a dedicated GitHub issue.

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

可以打开功能请求自行实现缺失的功能”You can open a feature request or implement the missing functionality yourself. 如果自行实现此功能,则可以自承载开发人员门户,或在 GitHub 上提交拉取请求,以便在托管版本中包含所需更改。If you implement the functionality yourself, you can either self-host the developer portal or open a pull request on GitHub to include the changes in the managed version.

如何自动部署门户?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.

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

否。No.

是否需要为托管门户依赖项启用额外的 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.

我已分配一个自定义 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

配置标识提供者(例如 AAD、AAD B2C)之后,需要重新发布门户才能使更改生效。After you configure an identity provider (for example, AAD, AAD B2C), you need to republish the portal for the changes to take effect.

我已设置委托,但门户不使用它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 and 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.

API 管理开发人员门户

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

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

  1. 单击“在全局级别上手动应用”链接以查看生成的策略代码。Click on 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. 在“入站处理”部分中,单击 </> 图标 。Click on 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.

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

如果在管理模式下打开门户时出现 Oops. Something went wrong. Please try again later. 错误,则原因可能是缺少所需的权限 (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 (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 
$customRole.AssignableScopes.Clear() 
$customRole.AssignableScopes.Add('/subscriptions/<subscription-id>') 
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: