你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

API 管理开发人员门户 - 常见问题

项目
12/03/2024

适用范围：开发人员 | 基本 | 基本 v2 | 标准 | 标准 v2 | 高级 | 高级 v2

如果需要门户中不支持的功能，该怎么办？

有下列选项：

对于较小的自定义项，请使用内置小组件添加自定义 HTML。目前，自定义 HTML 代码小组件在 API 管理的 v2 层中不可用。
对于较大的自定义项，请创建自定义小组件并将其上传到托管开发人员门户。目前，自定义小组件在 API 管理的 v2 层中不可用。
仅当需要对开发人员门户代码库的核心进行修改时，才自托管开发人员门户。
在 GitHub 存储库中打开功能请求。

详细了解如何自定义和扩展开发人员门户的功能。

能否在一个 API 管理服务中有多个开发人员门户？

可以有一个托管门户和多个自承载门户。所有门户的内容都存储在同一个 API 管理服务中，因此它们是相同的。如果希望门户的外观和功能不同，可以使用自己的自定义小组件对其进行自承载，以便在运行时上动态自定义页面（例如基于 URL）。

门户是否支持 Azure 资源管理器模板，和/或是否与 API 管理 DevOps 资源工具包兼容？

否。

门户的内容是否随 API 管理中的备份/还原功能一起保存？

否。

是否需要为托管门户依赖项启用额外的 VNet 连接？

大多数情况下是不需要的。

如果 API 管理服务位于内部 VNet 中，则只能从网络内部访问开发人员门户。管理终结点的主机名必须解析成用于访问门户管理界面的计算机中的服务的内部 VIP。请确保管理终结点已在 DNS 中注册。如果配置不当，将会出现以下错误：Unable to start the portal. See if settings are specified correctly in the configuration (...)。

如果 API 管理服务位于内部 VNet 中，并且是通过 Internet 上的应用程序网关访问它，请确保启用与开发人员门户和“API 管理”的管理终结点的连接。可能需要禁用 Web 应用程序防火墙规则。有关更多详细信息，请参阅此文档文章。

我分配了自定义 API 管理域，但发布的门户不起作用

更新域后，需要重新发布门户才能使更改生效。

我添加了一个标识提供者，但门户中未显示它

配置标识提供者（例如 Azure AD、AAD B2C）之后，需要重新发布门户才能使更改生效。请确保开发人员门户页包含 OAuth 按钮小组件。

我已设置委派，但门户不使用它

设置委托后，需要重新发布门户才能使更改生效。

我的其他 API 管理配置更改未传播到开发人员门户中

大多数配置更改（例如 VNet、登录和产品条款）都需要重新发布门户。

使用交互式控制台时出现 CORS 错误

交互式控制台从浏览器发出客户端 API 请求。通过在 API 上添加 CORS 策略来解决 CORS 问题，或者将门户配置为使用 CORS 代理。有关详细信息，请参阅在 API 管理开发人员门户中为交互式控制台启用 CORS。

在环境中使用自定义 HTML 代码小组件的情况下，当与小组件加载的 IFrame 交互时，可能会出现 CORS 错误。出现此问题的原因是 IFrame 提供的内容来自与开发人员门户不同的源。若要避免此问题，可以使用自定义小组件。

编辑开发人员门户需要哪些权限？

如果在管理模式下打开门户时出现 Oops. Something went wrong. Please try again later. 错误，则原因可能是缺少所需的权限 (Azure RBAC)。

门户需要 /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ApiManagement/service/<apim-service-name>/users/1 范围的 Microsoft.ApiManagement/service/users/token/action 权限。

可以使用以下 PowerShell 脚本创建拥有所需权限的角色。请记得更改 <subscription-id> 参数。

#New Portals Admin Role 
Import-Module Az 
Connect-AzAccount 
$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)”部分将其授予任何用户。将此角色分配给用户会在服务范围分配权限。该用户可以代表服务中的任何用户生成 SAS 令牌。最起码需要将此角色分配给服务的管理员。以下 PowerShell 命令演示如何在最低范围将角色分配给用户 user1，以避免向该用户授予不必要的权限：

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 门户，才能使新权限生效。

出现 `Unable to start the portal. See if settings are specified correctly (...)` 错误

对 https://<management-endpoint-hostname>/subscriptions/xxx/resourceGroups/xxx/providers/Microsoft.ApiManagement/service/xxx/contentTypes/document/contentItems/configuration?api-version=2018-06-01-preview 发出 GET 调用失败时会显示此错误。该调用是在浏览器中通过门户的管理界面发出的。

如果 API 管理服务处于 VNet 中，请参阅 VNet 连接问题。

调用失败也可能是 TLS/SSL 证书引起的，该证书已分配到自定义域，且不受浏览器信任。作为缓解措施，你可以删除管理终结点自定义域。 API 管理将回退到具有受信任证书的默认终结点。

门户对浏览器的支持是什么？

浏览者	支持
Apple Safari	是¹
Google Chrome	是¹
Microsoft Edge	是¹
Microsoft Internet Explorer	否
Mozilla Firefox	是¹

¹ 在两个最新的生产版本中受支持。

自承载门户的本地开发不再正常工作

如果本地版本的开发人员门户无法保存或检索来自存储帐户或 API 管理实例的信息，则 SAS 令牌可能已过期。可以通过生成新令牌来解决该问题。有关说明，请参阅自承载开发人员门户的相关教程。

如果不需要开发人员门户中默认启用的注册功能，可以通过以下步骤禁用它：

在 Azure 门户，导航到 API 管理实例。
在菜单的“开发人员门户”下，选择“标识” 。
删除列表中显示的每个标识提供者。选择每个提供者，选择上下文菜单（“...”），然后选择“删除” 。
导航到开发人员门户管理界面。
删除门户内容中的“注册”链接和导航项。有关自定义门户内容的信息，请参阅教程：访问和自定义开发人员门户。
修改“注册”页面内容以删除用于输入标识数据的字段，以防用户直接导航到该数据。

可以选择性地删除“注册”页。目前可使用 contentItem REST API 来列出和删除此页面。
保存更改并重新发布门户。

如何删除预配到 API 管理服务的开发人员门户内容？

在开发人员门户 GitHub 存储库中的 scripts.v3/cleanup.bat 脚本中提供所需参数，然后运行该脚本

cd scripts.v3
.\cleanup.bat
cd ..

如何对自承载开发人员门户启用单一登录 (SSO) 身份验证？

在其他身份验证方法中，开发人员门户支持单一登录 (SSO)。若要使用此方法进行身份验证，需要通过在查询参数中使用令牌来调用 /signin-sso：

https://contoso.com/signin-sso?token=[user-specific token]

生成用户令牌

可以使用 API 管理 REST API 的获取共享访问令牌操作来生成特定于用户的令牌（包括管理令牌）。

注意

令牌必须进行 URL 编码。

详细了解开发人员门户：

浏览其他资源：

包含源代码的 GitHub 存储库

通过

API 管理开发人员门户 - 常见问题

如果需要门户中不支持的功能，该怎么办？

能否在一个 API 管理服务中有多个开发人员门户？

门户是否支持 Azure 资源管理器模板，和/或是否与 API 管理 DevOps 资源工具包兼容？

门户的内容是否随 API 管理中的备份/还原功能一起保存？

是否需要为托管门户依赖项启用额外的 VNet 连接？

我分配了自定义 API 管理域，但发布的门户不起作用

我添加了一个标识提供者，但门户中未显示它

我已设置委派，但门户不使用它

我的其他 API 管理配置更改未传播到开发人员门户中

使用交互式控制台时出现 CORS 错误

在使用自定义 HTML 代码小组件时出现 CORS 错误

编辑开发人员门户需要哪些权限？

出现 `Unable to start the portal. See if settings are specified correctly (...)` 错误

门户对浏览器的支持是什么？

自承载门户的本地开发不再正常工作

如何删除预配到 API 管理服务的开发人员门户内容？

如何对自承载开发人员门户启用单一登录 (SSO) 身份验证？

生成用户令牌

反馈

其他资源

通过

API 管理开发人员门户 - 常见问题

如果需要门户中不支持的功能，该怎么办？

能否在一个 API 管理服务中有多个开发人员门户？

门户是否支持 Azure 资源管理器模板，和/或是否与 API 管理 DevOps 资源工具包兼容？

门户的内容是否随 API 管理中的备份/还原功能一起保存？

是否需要为托管门户依赖项启用额外的 VNet 连接？

我分配了自定义 API 管理域，但发布的门户不起作用

我添加了一个标识提供者，但门户中未显示它

我已设置委派，但门户不使用它

我的其他 API 管理配置更改未传播到开发人员门户中

使用交互式控制台时出现 CORS 错误

在使用自定义 HTML 代码小组件时出现 CORS 错误

编辑开发人员门户需要哪些权限？

出现 Unable to start the portal. See if settings are specified correctly (...) 错误

门户对浏览器的支持是什么？

自承载门户的本地开发不再正常工作

如何在开发人员门户中禁用注册？

如何删除预配到 API 管理服务的开发人员门户内容？

如何对自承载开发人员门户启用单一登录 (SSO) 身份验证？

生成用户令牌

相关内容

反馈

其他资源

出现 `Unable to start the portal. See if settings are specified correctly (...)` 错误