共用方式為

為您的內嵌應用程式進行疑難排解

  • 發行項

本此說明在內嵌來自 Power BI 的內容時，可能會遇到的一些常見問題。

疑難排解工具

Fiddler 追蹤

Fiddler 是 Telerik 所提供的免費工具，可監視 HTTP 流量。 您可以從用戶端電腦使用 Power BI API 來查看流量。 此工具可能會顯示錯誤與其他相關資訊。

此螢幕擷取畫面顯示 Fiddler 工具輸出視窗，其中顯示 Power BI API HTTP 流量。

在瀏覽器中按 F12 進行前端偵錯

F12 按鍵會在您的瀏覽器中啟動開發人員視窗。 此工具可讓您查看網路流量，並了解其他重要資訊。

此螢幕擷取畫面顯示網頁瀏覽器開發人員視窗 [網路] 索引標籤，其中顯示網路流量。

從 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;
}

我們建議您記錄要求識別碼 (與錯誤詳細資料以作為疑難排解之用)。 聯繫 Microsoft 支援服務時，請提供要求識別碼。

應用程式註冊

應用程式註冊失敗

如果您沒有註冊應用程式的足夠權限，則會在 Azure 入口網站中顯示錯誤訊息或在 Power BI 應用程式註冊頁面顯示通知。 若要註冊應用程式，您必須是 Microsoft Entra 租用戶的系統管理員，或必須允許非系統管理員的使用者進行應用程式註冊。

註冊新應用程式時，Power BI 服務未在 Azure 入口網站中顯示

至少須有一個使用者註冊 Power BI。 如果 API 清單中未列出 [Power BI 服務]，代表尚無使用者註冊 Power BI。

應用程式物件識別碼和主體物件識別碼之間的差異為何？

當您註冊 Microsoft Entra 應用程式時，會有兩個稱為物件識別碼的參數。 本節說明每個參數的用途，以及如何取得。

應用程式物件識別碼

應用程式物件識別碼，也稱為物件識別碼，是 Microsoft Entra 應用程式物件的唯一識別碼。

若要取得應用程式物件識別碼，請瀏覽至 Microsoft Entra 應用程式，然後從 [概觀] 中複製該識別碼。

此螢幕擷取畫面顯示 Azure 入口網站視窗，其中顯示 Microsoft Entra 應用程式 [概觀] 刀鋒視窗中的物件識別碼。

主體物件識別碼

主體物件識別碼，亦簡稱為物件識別碼，是與 Microsoft Entra 應用程式相關聯的服務主體物件的唯一識別碼。

若要取得主體物件識別碼，請瀏覽至您的 Microsoft Entra 應用程式，然後在 [概觀] 的 [本機目錄中的受控應用程式] 中選取應用程式連結。

此螢幕擷取畫面顯示 Azure 入口網站視窗，其中顯示 Microsoft Entra 應用程式 [概觀] 刀鋒視窗中的 [本機目錄中的受控應用程式] 選項。

在 [屬性] 區段中，複製 [物件識別碼]。

此螢幕擷取畫面顯示 Azure 入口網站視窗，其中顯示 Microsoft Entra 應用程式 [概觀] 刀鋒視窗 [屬性] 區段中的主體物件識別碼。

驗證

驗證因 AADSTS70002 或 AADSTS50053 而失敗

(AADSTS70002: 驗證認證時發生錯誤。AADSTS50053: 使用不正確的使用者識別碼或密碼，嘗試登入太多次)

如果您是使用 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。
  • 使用者沒有正確的權限。

若要確認問題，請嘗試下列步驟：

  • 執行 get dataset。 屬性 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 入口網站視窗登入對話方塊，其中顯示同意測試權限錯誤。

管理使用者可以成功登入並授與同意。

根本原因：

已停用租用戶的使用者同意。

可能有數個修正程式：

  • 啟用整個租用戶的使用者同意 (所有使用者、所有應用程式)：
  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 參數中指定租用戶識別碼。

  • 在組織的租用戶中用於驗證的 URL：

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

  • 用於驗證來賓 Microsoft Entra 使用者的 URL：

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

若要尋找您的租用戶識別碼，您可以使用尋找 Microsoft Entra 租用戶識別碼和主要網域名稱中的指示。

如需詳細資訊，請參閱讓應用程式成為多租用戶。

資料來源

ISV 希望相同的資料來源有不同的認證

一位主使用者可以有資料來源的一組認證。 若要使用其他認證，請建立更多主使用者。 接著，將不同的認證指派給每個主使用者的內容，然後使用該使用者的 Microsoft Entra 權杖內嵌。

使用 IError 物件為您的內嵌應用程式進行疑難排解

使用 error 事件從 JavaScript SDK 傳回的 IError 物件，針對您的應用程式進行偵錯並深入了解錯誤原因。

取得 IError 物件之後，您應該看看符合您使用之內嵌類型的適當常見錯誤表格。 比較 IError 屬性與該表格中的屬性，並尋找可能的失敗原因。

針對 Power BI 內嵌時的典型錯誤

訊息 詳細訊息 錯誤碼 可能的原因
TokenExpired 存取權杖到期，使用新的存取權杖重新提交 403 過期的權杖
PowerBIEntityNotFound 取得報表失敗 404
  • 錯誤的報表識別碼
  • 報表不存在
    		•
    參數無效 未指定 powerbiToken 參數 N/A
  • 未提供任何存取權杖
  • 未提供任何報表識別碼
    		•
    LoadReportFailed 無法初始化 - 無法解析叢集 403
  • 錯誤的存取權杖
  • 內嵌類型與權杖類型不符
    		•
    PowerBINotAuthorizedException 取得報表失敗 401
  • 錯誤的群組識別碼
  • 未經授權的群組
    		•
    TokenExpired 存取權杖到期，使用新的存取權杖重新提交。 無法轉譯下述標題的報表視覺效果：視覺效果標題 N/A
  • 查詢資料
  • 過期的權杖
    		•
    OpenConnectionError 無法顯示視覺效果。 無法轉譯下述標題的報表視覺效果：視覺效果標題 N/A 當與容量關聯的報表已在工作階段中開啟時，已暫停或刪除的容量
    ExplorationContainer_FailedToLoadModel_DefaultDetails 無法載入與此報表關聯的模型結構描述。 確定您可以連線到伺服器，然後再試一次。 N/A
  • 容量已暫停
  • 容量已刪除
    		•

    針對非 Power BI 使用者內嵌的典型錯誤 (使用內嵌權杖)

    訊息 詳細訊息 錯誤碼 原因
    TokenExpired 存取權杖到期，使用新的存取權杖重新提交 403 過期的權杖
    LoadReportFailed 取得報表失敗 404
  • 錯誤的報表識別碼
  • 報表不存在
    		•
    LoadReportFailed 取得報表失敗 403 報表識別碼與權杖不相符
    LoadReportFailed 取得報表失敗 500 報表提供的識別碼不是 GUID
    參數無效 未指定 powerbiToken 參數 N/A
  • 未提供任何存取權杖
  • 未提供任何報表識別碼
    		•
    LoadReportFailed 無法初始化 - 無法解析叢集 403 錯誤的權杖類型或錯誤的權杖
    PowerBINotAuthorizedException 取得報表失敗 401 錯誤/未經授權的群組識別碼
    TokenExpired 存取權杖到期，使用新的存取權杖重新提交。 無法轉譯下述標題的報表視覺效果：視覺效果標題 N/A
  • 查詢資料
  • 過期的權杖
    		•
    OpenConnectionError 無法顯示視覺效果。 無法轉譯下述標題的報表視覺效果：視覺效果標題 N/A 當與容量關聯的報表已在工作階段中開啟時，已暫停或刪除的容量
    ExplorationContainer_FailedToLoadModel_DefaultDetails 無法載入與此報表關聯的模型結構描述。 確定您可以連線到伺服器，然後再試一次。 N/A
  • 容量已暫停
  • 容量已刪除
    		•

    取得報表失敗 - 錯誤 401 - 自行解決

    在使用者擁有資料案例中，有時使用者會收到 401 錯誤，此錯誤會在使用者存取 Power BI 入口網站之後自行解決。 發生 401 錯誤時，請在應用程式中新增 RefreshUser 權限呼叫，如更新使用者權限所述。

    語意模型

    管理使用者可以看到哪一部分的資料

    任何具有語意模型讀取權限的使用者，都可以查看整個結構描述 (資料表、資料行和量值) 和所有資料。 您無法控制在相同語意模型中分開檢視原始和彙總資料的權限。

    若要管理使用者可以檢視哪一部分的資料，請使用下列其中一種方法：

    內容轉譯

    若要解決內嵌 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 帳戶。

    使用對組織進行內嵌的應用程式範例

    若您使用為組織進行內嵌體驗，請儲存並解壓縮 PowerBI-Developer-Samples.zip 檔案。 接著開啟 PowerBI-Developer-Samples-master\User 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>

    此錯誤是由於為網頁伺服器應用程式指定的重新導向 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 社群