嵌入式应用程序疑难解答

  • 项目

本文介绍了从 Power BI 嵌入内容时可能会遇到的一些常见问题。

故障排除工具

Fiddler 跟踪

Fiddler 是 Telerik 提供的一个免费工具，可以监视 HTTP 流量。 可以从客户端计算机通过 Power BI API 进行通信。 此工具可能会显示错误和其他相关信息。

Fiddler 工具输出窗口的屏幕截图，其中显示了 Power BI API HTTP 流量。

浏览器中用于前端调试的 F12

F12 键在你的浏览器中启动开发人员窗口。 通过此工具可以查看网络流量和其他有价值的信息。

Web 浏览器开发人员窗口的“网络”选项卡的屏幕截图，其中显示了网络流量。

从 Power BI 响应中提取错误详细信息

下面的代码片段展示了如何从 HTTP 异常中提取错误详细信息：

public static string GetExceptionText(this HttpOperationException exc)
{
    var errorText = string.Format("Request: {0}\r\nStatus: {1} ({2})\r\nResponse: {3}",
    exc.Request.Content, exc.Response.StatusCode, (int)exc.Response.StatusCode, exc.Response.Content);
    if (exc.Response.Headers.ContainsKey("RequestId"))
    {
        var requestId = exc.Response.Headers["RequestId"].FirstOrDefault();
        errorText += string.Format("\r\nRequestId: {0}", requestId);
    }

    return errorText;
}

建议记录请求 ID（以及错误详细信息以供排查问题）。 请在联系 Microsoft 支持部门时提供请求 ID。

应用注册

应用注册失败

如果你没有足够的权限来注册应用，则 Azure 门户或 Power BI 应用注册页面中的错误消息将通知你。 要注册应用程序，必须是 Microsoft Entra 租户中的管理员，或者必须为非管理员用户启用应用程序注册。

注册新应用时 Power BI 服务没有显示在 Azure 门户中

至少一个用户必须注册 Power BI。 如果没有看到 API 列表中列出 Power BI 服务，则表示没有用户注册 Power BI。

应用程序对象 ID 与主体对象 ID 之间有何区别？

注册 Microsoft Entra 应用时，有两个称为对象 ID 的参数。 本节介绍每个参数的用途以及如何获取该参数。

应用程序对象 ID

应用程序对象 ID（也可简称为对象 ID）是 Microsoft Entra 应用程序对象的唯一 ID。

要获取应用程序对象 ID，请导航到 Microsoft Entra 应用，然后从“概述”中复制它。

Azure 门户窗口的屏幕截图，其中显示了 Microsoft Entra 应用程序的“概述”边栏选项卡中的对象 ID。

主体对象 ID

主体对象 ID（也可简称为对象 ID）是与 Microsoft Entra 应用程序关联的服务主体对象的唯一 ID。

要获取主体对象 ID，请导航到 Microsoft Entra 应用，并从“概述”中选择“本地目录中的托管应用程序”中的应用链接。

Azure 门户窗口的屏幕截图，其中显示了 Microsoft Entra 应用程序的“概述”边栏选项卡中的“本地目录中的托管应用程序”选项。

在“属性”部分，复制“对象 ID”。

Azure 门户窗口的屏幕截图，其中显示了 Microsoft Entra 应用程序的“概述”边栏选项卡中，“属性”部分中的主体对象 ID。

身份验证

身份验证失败并显示 AADSTS70002 或 AADSTS50053

(AADSTS70002:验证凭据时出错。AADSTS50053:使用不正确的用户 ID 或密码尝试登录的次数过多)

如果你使用的是 Power BI Embedded 和 Microsoft Entra 直接身份验证，则在尝试登录时可能会收到上述类似消息，因为直接身份验证未启用。

可以使用组织或服务主体范围内的 Microsoft Entra 策略重新启用直接身份验证。

建议仅逐个应用地启用此策略。

若要创建此策略，需要具有在其中创建和分配此策略的目录的全局管理员身份。 下面的示例脚本展示了如何创建策略并将其分配到此应用程序的 SP：

  1. 安装 Microsoft Graph PowerShell SDK。

  2. 逐行运行以下 PowerShell 命令（确保变量 $sp 的结果只有一个应用程序）。

    Connect-MgGraph -Scopes "Directory.Read.All","Policy.ReadWrite.ApplicationConfiguration"

$sp = Get-MgServicePrincipal -Filter "DisplayName eq 'Name_Of_Application'"

$policy = New-MgBetaPolicyActivityBasedTimeoutPolicy -Definition @("{`"AllowCloudPasswordValidation`":true}") `
   -DisplayName EnableDirectAuth -IsOrganizationDefault:$false

$params = @{
   "@odata.id" = "https://graph.microsoft.com/v1.0/policies/claimsMappingPolicies/$policy.Id"
}
New-MgBetaServicePrincipalClaimMappingPolicyByRef -ServicePrincipalId $sp.Id `
   -BodyParameter $params

分配策略后，请等待传播完成（大约 15 到 20 秒），然后再进行测试。

提供有效标识时生成令牌失败

由于以下各种原因，GenerateToken 可能会失败，并提供有效标识：

  • 语义模型不支持有效标识。
  • 未提供用户名。
  • 未提供角色。
  • 未提供 DatasetId。
  • 用户没有正确的权限。

若要确定问题，请尝试以下步骤：

  • 运行获取数据集。 属性 IsEffectiveIdentityRequired 是否为 true？
  • 任何 EffectiveIdentity 都需要用户名。
  • 如果 IsEffectiveIdentityRolesRequired 为 true，则角色是必需的。
  • 任何 EffectiveIdentity 都需要 DatasetId。
  • 对于 Analysis Services，主用户必须是网关管理员。

AADSTS90094:授予需要管理员权限

表现：

非管理员用户首次尝试登录到应用程序并授予许可时，会收到以下错误之一：

  •   ConsentTest needs permission to access resources in your organization that only an admin can grant. Ask an admin to grant permission to this app before you can use it.

  •   AADSTS90094: The grant requires admin permission.

    Azure 门户窗口登录对话框的屏幕截图，其中显示了 ConsentTest 权限错误。

管理员用户可以成功登录并授予许可。

根本原因：

对租户禁用用户同意。

可能会出现几个修补程序：

  • 对整个租户（所有用户和所有应用程序）启用用户同意：
  1. 在 Azure 门户中，导航到“Microsoft Entra ID”>“用户和组”>“用户设置”。
  2. 启用“用户可以同意应用代表他们访问公司数据”设置并保存更改。

Azure 门户的屏幕截图。

  • 管理员可以授予（整个租户或特定用户）访问应用程序的权限。

CS1061 错误

如果遇到以下错误，请下载 Microsoft.IdentityModel.Clients.ActiveDirectory：

'AuthenticationContext' does not contain a definition for 'AcquireToken' and no accessible 'AcquireToken' accepting a first argument of type 'AuthenticationContext' could be found (are you missing a using directive or an assembly reference?)

不同租户的 Microsoft Entra 令牌（来宾用户）

当你为组织嵌入时，若要允许 Microsoft Entra 来宾用户访问内容，你需要在 authorityUri 参数中指定租户 ID。

  • 用于在组织的租户中进行身份验证的 URL：

    https://login.microsoftonline.com/common/v2.0

  • 用于对来宾 Microsoft Entra 用户进行身份验证的 URL：

    https://login.microsoftonline.com/<tenant ID>

若要查找租户 ID，可以按照查找 Microsoft Entra 租户 ID 和主域名中的说明进行操作。

有关详细信息，请参阅使应用程序成为多租户。

数据源

ISV 希望相同的数据源有不同的凭据

数据源可以为一个主用户提供一组凭据。 如果你需要使用不同的凭据，请创建更多主用户。 然后，在每个主用户上下文中分配不同的凭据，并使用该用户的 Microsoft Entra 令牌嵌入。

使用 IError 对象对嵌入式应用程序进行故障排查

使用 JavaScript SDK 的 error 事件中返回的 IError 对象调试应用程序，并更好地了解错误的原因。

获取 IError 对象之后，应查找适合你使用的嵌入类型的对应常见错误表。 将 IError 属性 与表中的该属性进行比较，查找失败的可能原因。

为 Power BI 用户嵌入内容时的典型错误

消息 详细的消息 错误代码 可能的原因
TokenExpired 访问令牌已过期，请使用新的访问令牌重新提交 403 令牌已过期
PowerBIEntityNotFound 获取报表失败 404
  • 报表 ID 错误
  • 报表不存在
    		•
    参数无效 未指定 powerbiToken 参数 不可用
  • 未提供任何访问令牌
  • 未提供任何报表 ID
    		•
    LoadReportFailed 初始化失败，无法解析群集 403
  • 访问令牌错误
  • 嵌入类型与令牌类型不匹配
    		•
    PowerBINotAuthorizedException 获取报表失败 401
  • 组 ID 错误
  • 组未经授权
    		•
    TokenExpired 访问令牌已过期，请使用新的访问令牌重新提交。 无法呈现以下标题的报表视觉对象：视觉对象标题 不可用
  • 查询数据
  • 令牌已过期
    		•
    OpenConnectionError 无法显示视觉对象。 无法呈现以下标题的报表视觉对象：视觉对象标题 不适用 在会话中打开与容量相关的报表时，容量遭暂停或删除
    ExplorationContainer_FailedToLoadModel_DefaultDetails 无法加载与此报表关联的模型架构。 请确保你已连接到服务器，然后重试。 不可用
  • 容量已暂停
  • 容量已删除
    		•

    （使用嵌入令牌）为非 Power BI 用户嵌入内容时的典型错误

    消息 详细的消息 错误代码 原因
    TokenExpired 访问令牌已过期，请使用新的访问令牌重新提交 403 令牌已过期
    LoadReportFailed 获取报表失败 404
  • 报表 ID 错误
  • 报表不存在
    		•
    LoadReportFailed 获取报表失败 403 报表 ID 与令牌不匹配
    LoadReportFailed 获取报表失败 500 提供的报表 ID 不是 GUID
    参数无效 未指定 powerbiToken 参数 不可用
  • 未提供任何访问令牌
  • 未提供任何报表 ID
    		•
    LoadReportFailed 初始化失败，无法解析群集 403 令牌类型错误，或令牌不正确
    PowerBINotAuthorizedException 获取报表失败 401 组 ID 错误/未经授权
    TokenExpired 访问令牌已过期，请使用新的访问令牌重新提交。 无法呈现以下标题的报表视觉对象：视觉对象标题 不可用
  • 查询数据
  • 令牌已过期
    		•
    OpenConnectionError 无法显示视觉对象。 无法呈现以下标题的报表视觉对象：视觉对象标题 不适用 在会话中打开与容量相关的报表时，容量遭暂停或删除
    ExplorationContainer_FailedToLoadModel_DefaultDetails 无法加载与此报表关联的模型架构。 请确保你已连接到服务器，然后重试。 不可用
  • 容量已暂停
  • 容量已删除
    		•

    获取报告失败 - 错误 401 - 自行解决

    有时，“用户拥有数据”场景的用户会收到 401 错误，该错误会在用户访问 Power BI 门户后自行解决。 发生 401 错误时，请按照更新用户权限中的说明在应用中添加 RefreshUser Permissions 调用。

    语义模型

    管理用户可以看到的数据部分

    任何对语义模型具有读取权限的用户都可以查看整个架构（表、列和度量值）和所有数据。 不能单独控制对同一语义模型中原始数据和聚合数据的查看权限。

    若要管理用户可以查看的数据部分，请使用以下方法之一：

    • 使用 Power BI 行级安全性 (RLS) 的行级筛选。

    • 对象级安全性 (OLS)。

    • 将数据分隔到不同的语义模型中。 例如，可以创建一个仅包含聚合数据的语义模型，并向用户授予仅对该语义模型的访问权限。

    内容呈现

    若要解决嵌入式 Power BI 项（如报表和仪表板）的呈现问题，请查看本部分。

    验证是否在 Power BI 服务中加载 Power BI 项

    若要排除应用程序或嵌入 API 的问题，请验证是否可以在 Power BI 服务 (powerbi.com) 中查看该项。

    验证是否在 Power BI 嵌入式分析操场中加载 Power BI 项

    若要排除应用程序的问题，请验证是否可以在 Power BI 嵌入式分析操场中查看 Power BI 项。

    验证访问令牌是否未过期

    出于安全目的，访问令牌（Microsoft Entra 令牌或嵌入令牌）具有有限的生存期。 应持续监视访问令牌，并根据需要刷新它。 有关详细信息，请参阅刷新访问令牌。

    性能

    若要获取性能最佳的嵌入式内容，我们建议遵循 Power BI 嵌入式分析最佳做法。

    嵌入安装工具

    可使用嵌入安装程序工具快速下载示例应用程序。 然后，即可将你的应用程序与示例进行比较。

    先决条件

    请先验证你具备所有适当先决条件，然后再使用嵌入安装程序工具。 需要 Power BI Pro 帐户和 Microsoft Azure 订阅 。

    常见问题

    使用嵌入安装程序工具进行测试时，可能遇到的一些常见问题包括：

    使用“为客户嵌入”示例应用程序

    若要采用“为客户嵌入” 体验，请保存并解压缩 PowerBI-Developer-Samples.zip 文件。 然后打开 PowerBI-Developer-Samples-master\App Owns Data 文件夹并运行 PowerBIEmbedded_AppOwnsData.sln 文件 。

    • 选择“授予权限”（“授予权限”步骤）时，将收到以下错误 ：
    AADSTS70001: Application with identifier <client ID> wasn't found in the directory <directory ID>

    解决方案是关闭弹出窗口，等待几秒钟再重试。 可能需要多次重复此操作。 造成此问题的原因是，从完成应用程序注册过程到该应用程序对外部 API 可用之间存在时间间隔。

    • 运行示例应用时，将显示以下错误消息：
    Password is empty. Please fill password of Power BI username in web.config.

    由于未注入示例应用程序的唯一值是用户密码，因此会发生此错误。 在解决方案中打开 Web.config 文件，并使用用户密码填充 pbiPassword 字段。

    • 如果收到错误：
    AADSTS50079: The user is required to use multi-factor authentication.

    需要使用一个未启用 MFA 的 Microsoft Entra 帐户。

    将 Embed 用于组织示例应用程序

    若要采用“为组织嵌入”体验，请保存并解压缩 PowerBI-Developer-Samples.zip 文件。 然后打开 PowerBI-Developer-Samples-master\App Owns Data\integrate-report-web-app 文件夹并运行 pbi-saas-embed-report.sln 文件。

    • 运行“为组织嵌入”示例应用时，将收到以下错误：
    AADSTS50011: The reply URL specified in the request doesn't match the reply URLs configured for the application: <client ID>

    此错误是因为为 web-server 应用程序指定的重定向 URL 不同于示例的 URL。 如果想要注册示例应用程序，请使用 https://localhost:13526/ 作为重定向 URL。

    如果想要编辑已注册的应用程序，请更新已注册 Microsoft Entra 的应用程序，使应用程序可以向 Web API 提供访问权限。

    如果想要编辑 Power BI 用户配置文件或数据，请了解如何编辑 Power BI 数据。

    • 如果收到错误：
    AADSTS50079: The user is required to use multi-factor authentication.

    需要使用一个未启用 MFA 的 Microsoft Entra 帐户。

    有关详细信息，请参阅 Power BI Embedded 常见问题。

    如需进一步的帮助，请联系支持人员或通过 Azure 门户创建支持票证，并提供你遇到的错误消息。

    相关内容

    Power BI Embedded 常见问题

    更多问题？ 在 Power BI 社区提问