教學課程：使用「對客戶進行內嵌」範例應用程式內嵌 Power BI 內容

適用於： 應用程式擁有資料 使用者擁有資料

內嵌式分析和 Power BI Embedded (Azure 供應項目) 可讓您將 Power BI 的內容 (例如報表、儀表板和磚) 內嵌到應用程式中。

在本教學課程中，您會了解如何：

• 設定您的內嵌環境。
• 設定「對客戶進行內嵌」(也稱為「應用程式擁有資料」) 範例應用程式。

若要使用您的應用程式，使用者不需要登入 Power BI 或擁有 Power BI 授權。

如果您是獨立軟體廠商 (ISV) 或開發人員，而且想要為協力廠商建立應用程式，建議使用「對客戶進行內嵌」方法來內嵌您的 Power BI 內容。

重要

如果您要內嵌國家/地區雲端的內容，本教學課程的前幾個步驟會有所不同。 如需詳細資訊，請參閱內嵌國家/地區雲端的內容 (部分機器翻譯)。

程式碼範例規格

本教學課程包含使用下列其中一種架構，設定「對客戶進行內嵌」範例應用程式的指示：

• .NET Framework
• .NET Core
• Java
• Node JS
• Python

程式碼範例支援下列瀏覽器：

• Microsoft Edge
• Google Chrome
• Mozilla Firefox

必要條件

開始進行本教學課程之前，請確認您具有下列 Power BI 和程式碼相依性：

• Power BI 相依性

  • 您自己的 Microsoft Entra 租用戶。

  • 若要對 Power BI 驗證您的應用程式，您需要下列其中一項：

    • 服務主體 - Microsoft Entra 服務主體物件，允許 Microsoft Entra ID 驗證您的應用程式。

    • Power BI Pro 授權 - 這會是您的主要使用者，而您的應用程式會使用此授權向 Power BI 驗證。

    • Power BI Premium Per User (PPU) 授權 - 這是您的主要使用者，而您的應用程式會使用此授權向 Power BI 驗證。

    注意

    若要移至實際執行環境，您將需要容量。

• 程式碼相依性

.NET Core

• .NET Core 3.1 SDK (或更高版本)

• 整合式開發環境 (IDE)。 建議您使用下列其中一個環境：

  • Visual Studio

  • Visual Studio Code

.NET Framework

• .NET Framework 4.8

• Visual Studio

Java

• JDK (或 JRE)

• Eclipse IDE - 確認您擁有 Eclipse for Java EE Developers (企業版)

• Apache Tomcat Binary Distributions

Node JS

• Node.js

• 整合式開發環境 (IDE)。 建議您使用下列其中一個環境：

  • Visual Studio

  • Visual Studio Code

Python

• Python 3 (或更高版本)

  注意

  • 如果您是第一次安裝 Python，請選取 [Add Python to PATH] \(將 Python 新增至 PATH\) 選項，將安裝新增至 PATH 變數。
  • 如果您已安裝 Python，請確認 PATH 變數包含其安裝路徑。 如需詳細資訊，請參閱附錄：設定環境變數 (英文 )Python 文件 (此連結所指為 Python 3)。

• 整合式開發環境 (IDE)。 建議您使用下列其中一個環境：

  • Visual Studio

  • Visual Studio Code

方法

若要建立「對客戶進行內嵌」範例應用程式，請遵循下列步驟：

1. 選取您的驗證方法。

2. 註冊 Microsoft Entra 應用程式 (部分機器翻譯)。

3. 建立 Power BI 工作區。

4. 建立及發佈 Power BI 報表。

5. 取得內嵌參數值。

6. 服務主體 API 存取

7. 啟用工作區存取。

8. 內嵌內容。

步驟 1 - 選取您的驗證方法

您的內嵌解決方案會根據所選取的驗證方法而有所不同。 因此，請務必了解驗證方法之間的差異，並決定哪一種方法最適合您的解決方案。

下表描述服務主體 (部分機器翻譯) 與主要使用者驗證方法之間的一些主要差異。

考量	服務主體	主要使用者
機制	Microsoft Entra 應用程式的服務主體物件可讓 Microsoft Entra ID 針對 Power BI 驗證您的內嵌解決方案應用程式。	您的 Microsoft Entra 應用程式會使用 Power BI 使用者的認證 (使用者名稱和密碼) 針對 Power BI 進行驗證。
安全性	「服務主體」是 Microsoft Entra ID 建議的授權方法。 如果您使用服務主體，則您可以使用應用程式祕密或憑證進行驗證。 本教學課程僅說明搭配應用程式祕密使用服務主體。 若要使用「服務主體」和「憑證」進行內嵌，請參閱搭配憑證的服務主體一文。	一般認為此驗證方法不像「服務主體」那麼安全。 您必須小心處理「主要使用者」認證 (使用者名稱和密碼)。 例如，請勿在內嵌應用程式中將其公開，且應該經常變更密碼。
Microsoft Entra ID 委派的權限	非必要。	您的「主要使用者」或系統管理員必須授與同意，才能讓您的應用程式存取 Power BI REST API 權限 (也稱為範圍)。 例如，Report.ReadWrite.All。
Power BI 服務存取	您無法使用「服務主體」來存取 Power BI 服務。	您可以使用「主要使用者」認證來存取 Power BI 服務。
授權	不需要 Pro 授權。 您可以從任何自己是成員或系統管理員的工作區使用內容。	需要 Power BI Pro 或 Premium Per User (PPU) 授權。

步驟 2 - 註冊 Microsoft Entra 應用程式

向 Microsoft Entra ID 註冊應用程式可讓您：

• 建立應用程式的身分識別
• 讓您的應用程式存取 Power BI REST API
• 如果您使用「主要使用者」 - 指定應用程式的 Power BI REST 權限

若要向 Microsoft Entra ID 註冊應用程式，請依照註冊您的應用程式中的指示進行。

注意

在註冊應用程式之前，您必須決定要使用哪種驗證方法：「服務主體」或「主要使用者」。

步驟 3 - 建立 Power BI 工作區

Microsoft Fabric 會將您的報表、儀表板和磚保留在工作區中。 若要內嵌這些項目，您必須建立這些項目，並將其上傳至工作區。

提示

如果您已經有工作區，就可以略過此步驟。

若要建立工作區，請執行下列動作：

1. 登入 Fabric。

2. 選取工作區。

3. 選取 [+ 新增工作區]。

4. 為工作區命名，然後選取 [儲存]。

步驟4 - 建立及發佈 Power BI 報表

下一步是建立報表並將其上傳至您的工作區。 您可以使用 Power BI Desktop 以建立自己的報表，然後將其發佈至您的工作區。 或者，也可以將範例報表上傳至您的工作區。

提示

如果您已經有包含報表的工作區，就可以略過此步驟。

若要下載範例報表並將其發佈至您的工作區，請遵循下列步驟：

1. 開啟 GitHub Power BI Desktop 範例資料夾。

2. 選取 [Code] \(程式碼\)，然後選取 [Download zip] \(下載 ZIP\)。

   

3. 解壓縮下載的 ZIP 並巡覽至 Samples Reports 資料夾。

4. 選取要內嵌的報表，然後將其發佈到您的工作區。

步驟 5 - 取得內嵌參數值

若要內嵌內容，您必須取得特定的參數值。 下表會顯示必要的值，並指出這些值是適用於「服務主體」驗證方法、「主要使用者」驗證方法，或這兩種方法。

在內嵌內容之前，請確定您擁有下列所有值。 某些值可能會根據您使用的驗證方法而有所不同。

參數	服務主體	主要使用者
用戶端識別碼
工作區識別碼
Report ID \(報表識別碼\)
用戶端密碼
租用戶識別碼		僅限 Node JS 的必要項目
Power BI 使用者名稱
Power BI 密碼

Client ID

提示

適用於： 服務主體 主要使用者

若要取得用戶端識別碼 GUID (也稱為「應用程式識別碼」)，請遵循下列步驟：

1. 登入 Microsoft Azure。

2. 搜尋應用程式註冊，然後選取 [應用程式註冊] 連結。

3. 選取您用於內嵌 Power BI 內容的 Microsoft Entra 應用程式。

4. 從 [概觀] 區段中，複製 [應用程式 (用戶端) 識別碼] GUID。

工作區識別碼

提示

適用於： 服務主體 主要使用者

若要取得工作區識別碼 GUID，請遵循下列步驟：

1. 登入 Power BI 服務。

2. 開啟您想要內嵌的報表。

3. 複製 URL 中的 GUID。 GUID 是 /groups/ 與 /reports/ 之間的數字。

   

或者，您可以選取工作區名稱旁 [詳細資料] ，在 [管理入口網站] 設定中找到工作區識別碼。

報表識別碼

提示

適用於： 服務主體 主要使用者

若要取得報表識別碼 GUID，請遵循下列步驟：

1. 登入 Power BI 服務。

2. 開啟您想要內嵌的報表。

3. 複製 URL 中的 GUID。 GUID 是 /reports/ 與 /ReportSection 之間的數字。

   

用戶端密碼

提示

適用於： 服務主體 主要使用者

若要取得用戶端密碼，請遵循下列步驟：

1. 登入 Microsoft Azure。

2. 搜尋應用程式註冊，然後選取 [應用程式註冊] 連結。

3. 選取您用於內嵌 Power BI 內容的 Microsoft Entra 應用程式。

4. 在 [管理] 下，選取 [憑證和密碼]。

5. 在 [用戶端祕密] 下，選取 [新增用戶端祕密]。

6. 在 [新增用戶端祕密] 快顯視窗中，提供應用程式祕密的描述、選擇應用程式祕密何時到期，然後選取 [新增]。

7. 從 [用戶端祕密] 區段中，複製新建立的應用程式祕密中 [值] 資料行的字串。 用戶端祕密值是您的「用戶端識別碼」。

注意

請務必在用戶端密碼值第一次出現時將其複製。 在瀏覽完此頁面之後，用戶端密碼便會隱藏，您將無法擷取其值。

租用戶識別碼

提示

適用於： 服務主體 主要使用者

若要取得租用戶識別碼 GUID，請遵循下列步驟：

1. 登入 Microsoft Azure。

2. 搜尋應用程式註冊，然後選取 [應用程式註冊] 連結。

3. 選取您用於內嵌 Power BI 內容的 Microsoft Entra 應用程式。

4. 從 [概觀] 區段中，複製 [目錄 (租用戶) 識別碼] GUID。

Power BI 使用者名稱及密碼

提示

適用於： 服務主體 主要使用者

針對您要作為主要使用者的 Power BI 使用者，取得其「使用者名稱」和「密碼」。 這是 Power BI 服務中您用來建立工作區並將報表上傳到其中的相同使用者。

步驟 6 - 服務主體 API 存取

提示

適用於： 服務主體 主要使用者

只有當您使用「服務主體」驗證方法時，此步驟才有意義。 如果您使用「主要使用者」，請略過此步驟，並繼續進行步驟 7 - 啟用工作區存取。

若要讓 Microsoft Entra 應用程式能夠存取 Power BI 內容和 API，Power BI 系統管理員必須在 Power BI 系統管理員入口網站中啟用服務主體存取權。 如果您不是租用戶的系統管理員，請讓租用戶的系統管理員為您啟用「租用戶設定」。

1. 在「Power BI 服務」中，選取 [設定]>[設定]>[系統管理員入口網站]。

   

2. 選取 [租用戶設定]，然後向下捲動至 [開發人員設定] 區段。

3. 展開 [服務主體可以使用 Fabric API]，然後啟用此選項。

   

注意

使用「服務主體」時，建議您使用「安全性群組」來限制其對租用戶設定的存取權。 若要深入了解這項功能，請參閱服務主體一文中的下列小節：

• 建立 Microsoft Entra 安全性群組 (部分機器翻譯)
• 啟用 Power BI 服務系統管理員設定

步驟 7 - 啟用工作區存取

若要啟用 AMicrosoft Entra 應用程式存取物件 (例如 Power BI 服務中的報表、儀表板和語意模型)，請將「服務主體」或「主要使用者」新增為您工作區的「成員」或「系統管理員」。

1. 登入 Fabric。

2. 捲動至您想要為其啟用存取權的工作區，並選取 [管理存取]。

   

3. 在 [存取] 窗格中，視您使用的驗證方法而定，將「服務主體」或「主要使用者」複製到 [輸入電子郵件地址] 文字方塊。

   注意

   如果您使用「服務主體」，其名稱就是您提供給 Microsoft Entra 應用程式的名稱。

4. 選取 [新增]。

步驟 8 - 內嵌您的內容

Power BI Embedded 範例應用程式可讓您建立「對客戶進行內嵌」 Power BI 應用程式。

請遵循下列步驟來修改「對客戶進行內嵌」範例應用程式，以內嵌您的 Power BI 報表。

1. 開啟 Power BI 開發人員範例資料夾。

2. 選取 [Code] \(程式碼\)，然後選取 [Download zip] \(下載 ZIP\)。

   

3. 解壓縮下載的 ZIP 並巡覽至 PowerBI-Developer-Samples-master 資料夾。

4. 視您想要讓應用程式使用的語言而定，開啟下列其中一個資料夾：

   • .NET Core
   • .NET Framework
   • Java
   • Node JS
   • Python

   注意

   「對客戶進行內嵌」範例應用程式只支援上述架構。 「回應」範例應用程式僅支援對組織進行內嵌解決方案。

5. 開啟對客戶進行內嵌資料夾。

.NET Core

6. 使用下列其中一種方法，開啟「對客戶進行內嵌範例應用程式」：

   • 如果您使用的是 Visual Studio，請開啟 AppOwnsData.sln 檔案。

   • 如果您使用的是 Visual Studio Code (英文)，請開啟 [AppOwnsData] 資料夾。

7. 開啟 appsettings.json。

8. 根據您的驗證方法，填入下列參數值：

   參數	服務主體	主要使用者
   AuthenticationMode	ServicePrincipal	MasterUser
   ClientId	您的 Microsoft Entra 應用程式用戶端識別碼 (部分機器翻譯)	您的 Microsoft Entra 應用程式用戶端識別碼 (部分機器翻譯)
   TenantId	您的 Microsoft Entra 租用戶識別碼 (部分機器翻譯)	N/A
   PbiUsername	N/A	您的「主要使用者」使用者名稱，請參閱 Power BI 使用者名稱和密碼
   PbiPassword	N/A	您的「主要使用者」密碼，請參閱 Power BI 使用者名稱和密碼
   ClientSecret	您的 Microsoft Entra ID 用戶端密碼 (部分機器翻譯)	N/A
   WorkspaceId	內嵌報表所在工作區的識別碼，請參閱工作區識別碼	內嵌報表所在工作區的識別碼，請參閱工作區識別碼
   ReportId	所要內嵌報表的識別碼，請參閱報表識別碼	所要內嵌報表的識別碼，請參閱報表識別碼

9. 選取適當的選項來執行專案：

   • 如果您使用 Visual Studio，請選取 [IIS Express] (播放)。

   • 如果您使用 Visual Studio Code (英文)，請選取 [執行] > [開始偵錯]。

.NET Framework

6. 使用 Visual Studio，開啟 AppOwnsData.sln 檔案。

7. 開啟 Web.config。

8. 根據您的驗證方法，填入下列參數值：

   參數	服務主體	主要使用者
   authenticationType	ServicePrincipal	MasterUser
   applicationId	您的 Microsoft Entra 應用程式用戶端識別碼 (部分機器翻譯)	您的 Microsoft Entra 應用程式用戶端識別碼 (部分機器翻譯)
   workspaceId	內嵌報表所在工作區的識別碼，請參閱工作區識別碼	內嵌報表所在工作區的識別碼，請參閱工作區識別碼
   reportId	所要內嵌報表的識別碼，請參閱報表識別碼	所要內嵌報表的識別碼，請參閱報表識別碼
   pbiUsername	N/A	您的「主要使用者」使用者名稱，請參閱 Power BI 使用者名稱和密碼
   pbiPassword	N/A	您的「主要使用者」密碼，請參閱 Power BI 使用者名稱和密碼
   applicationSecret	您的 Microsoft Entra ID 用戶端密碼 (部分機器翻譯)	N/A
   tenant	您的 Microsoft Entra 租用戶識別碼 (部分機器翻譯)	N/A

9. 選取 [IIS Express] (播放) 以執行專案。

Java

6. 開啟 Eclipse，並遵循下方所述的指示。

   注意

   適用於 Java「對客戶進行內嵌範例應用程式」的指示，請參閱 Eclipse IDE for Java EE Developers (企業版)。 如果您使用不同的應用程式，則必須自行設定。

7. 將 Tomcat 伺服器新增至 Eclipse：

   a. 選取 [Window] \(視窗\)>[Show View] \(顯示檢視\)>[Servers] \(伺服器\)。

   b. 在 [Servers] \(伺服器\) 索引標籤中，選取 [No servers are available.Click this link to create new server] \(沒有可用的伺服器。按一下此連結以建立新的伺服器\)。

   c. 在 [Define a New Server] \(定義新的伺服器\) 視窗中，展開 [Apache]，然後選取您要在電腦上執行的 Tomcat 伺服器。 例如，Tomcat v9.0 Server。

   d. 選取 [下一步]。

   e. 在 [Tomcat Server] \(Tomcat 伺服器\) 視窗中，選取 [Browse] \(瀏覽\)，然後巡覽至包含 Tomcat 伺服器的資料夾。

   f. 在 [Tomcat Server] \(Tomcat 伺服器\) 視窗中，選取 [Installed JREs] \(安裝的 JRE\)。

   .g 在 [Installed JREs] \(安裝的 JRE\) 視窗中，選取可用的 jre，然後選取 [Apply and Close] \(套用並關閉\)。

   h. 在 [Tomcat Server] \(Tomcat 伺服器\) 視窗中，選取 [Finish] \(完成\)。 您能夠在 [伺服器] 索引標籤中看到 Tomcat 伺服器。

8. 在 Eclipse 中開啟專案：

   重要

   如果您的路徑名稱太長，Eclipse 可能會發生問題。 若要避免這個問題，請確認範例應用程式資料夾在電腦資料夾結構中的巢狀層級並未太深。

   a. 選取 [File] \(檔案\)，然後選取 [Open Projects from File System] \(從檔案系統開啟專案\)。

   b. 在 [I從檔案系統或封存匯入專案] 視窗中，選取 [目錄] 並開啟 [AppOwnsData] 資料夾。

   c. 選取 [完成]。

9. 將 Tomcat 伺服器新增至專案：

   a. 在 [Package Explorer] \(套件總管\) 窗格中，以滑鼠右鍵按一下 AppOwnsData，然後選取 [Properties] \(屬性\)。

   b. 在 [AppOwnsData 的屬性] 視窗中，選取 [目標執行階段]，然後選取 [Apache Tomcat]。 此選項會包含您所使用的 Apache Tomcat 版本，例如 Apache Tomcat v9.0。

   c. 選取 [套用並關閉]。

10. 填入必要的參數

    a. 在 [Package explorer] \(套件總管\) 中，展開 AppOwnsData 專案。

    b. 展開 [Java Resources] \(Java 資源\)。

    c. 展開 src。

    d. 展開 com.embedsample.appoensdata.config。

    e. 開啟 Config.java。

    f. 根據您的驗證方法，填入下列參數值：

    參數	服務主體	主要使用者
    authenticationType	ServicePrincipal	MasterUser
    workspaceId	內嵌報表所在工作區的識別碼，請參閱工作區識別碼	內嵌報表所在工作區的識別碼，請參閱工作區識別碼
    reportId	所要內嵌報表的識別碼，請參閱報表識別碼	所要內嵌報表的識別碼，請參閱報表識別碼
    clientId	您的 Microsoft Entra 應用程式用戶端識別碼 (部分機器翻譯)	您的 Microsoft Entra 應用程式用戶端識別碼 (部分機器翻譯)
    pbiUsername	N/A	您的「主要使用者」使用者名稱，請參閱 Power BI 使用者名稱和密碼
    pbiPassword	N/A	您的「主要使用者」密碼，請參閱 Power BI 使用者名稱和密碼
    tenantId	您的 Microsoft Entra 租用戶識別碼 (部分機器翻譯)	N/A
    appSecret	您的 Microsoft Entra ID 用戶端密碼 (部分機器翻譯)	N/A

11. 執行專案

    a. 在 [套件總管] 中，以滑鼠右鍵按一下 AppOwnesData。

    b. 選取 [執行身分]>[對伺服器執行]。

    c. 在 [對伺服器執行] 視窗上，選取 [選擇現有的伺服器]，然後選取 [Tomcat] 伺服器。

    d. 選取 [完成]。

Node JS

6. 使用您慣用的 IDE，開啟應用程式擁有資料資料夾。 建議您使用下列其中一項：

   • Visual Studio

   • Visual Studio Code

7. 藉由執行下列命令，開啟終端並安裝必要的相依性：npm install。

8. 展開 Config 資料夾，然後開啟 config.json。

9. 根據您的驗證方法，填入下列參數值：

   參數	服務主體	主要使用者
   authenticationMode	ServicePrincipal	MasterUser
   clientId	您的 Microsoft Entra 應用程式用戶端識別碼 (部分機器翻譯)	您的 Microsoft Entra 應用程式用戶端識別碼 (部分機器翻譯)
   workspaceId	內嵌報表所在工作區的識別碼，請參閱工作區識別碼	內嵌報表所在工作區的識別碼，請參閱工作區識別碼
   reportId	所要內嵌報表的識別碼，請參閱報表識別碼	所要內嵌報表的識別碼，請參閱報表識別碼
   pbiUsername	N/A	您的「主要使用者」使用者名稱，請參閱 Power BI 使用者名稱和密碼
   pbiPassword	N/A	您的「主要使用者」密碼，請參閱 Power BI 使用者名稱和密碼
   clientSecret	您的 Microsoft Entra ID 用戶端密碼 (部分機器翻譯)	N/A
   tenantId	您的 Microsoft Entra 租用戶識別碼 (部分機器翻譯)	您的 Microsoft Entra 租用戶識別碼 (部分機器翻譯)

10. 執行下列動作來執行專案：

    a. 在 IDE 終端中，執行 npm start。

    b. 在瀏覽器中開啟新索引標籤，然後瀏覽至 http://localhost:5300。

Python

6. 開啟 [PowerShell] 或 [命令提示字元]。

7. 確認您是在 Python>對客戶進行內嵌資料夾，且 requirements.txt 檔案位於該資料夾中，然後執行 pip3 install -r requirements.txt。

8. 使用您慣用的 IDE，開啟應用程式擁有資料資料夾。 建議您使用下列其中一個環境：

   • Visual Studio

   • Visual Studio Code

9. 開啟 config.py。

10. 根據您的驗證方法，填入下列參數值：

    參數	服務主體	主要使用者
    AUTHENTICATION_MODE	ServicePrincipal	MasterUser
    WORKSPACE_ID	內嵌報表所在工作區的識別碼，請參閱工作區識別碼	內嵌報表所在工作區的識別碼，請參閱工作區識別碼
    REPORT_ID	所要內嵌報表的識別碼，請參閱報表識別碼	所要內嵌報表的識別碼，請參閱報表識別碼
    TENANT_ID	您的 Microsoft Entra 租用戶識別碼 (部分機器翻譯)	N/A
    CLIENT_ID	您的 Microsoft Entra 應用程式用戶端識別碼 (部分機器翻譯)	您的 Microsoft Entra 應用程式用戶端識別碼 (部分機器翻譯)
    CLIENT_SECRET	您的 Microsoft Entra ID 用戶端密碼 (部分機器翻譯)	N/A
    POWER_BI_USER	N/A	您的「主要使用者」使用者名稱，請參閱 Power BI 使用者名稱和密碼
    POWER_BI_PASS	N/A	您的「主要使用者」密碼，請參閱 Power BI 使用者名稱和密碼

11. 儲存檔案。

12. 執行下列步驟來執行專案：

    a. 在 [PowerShell] 或 [命令提示字元] 中，巡覽至 Python>對客戶進行內嵌>AppOwnesData 資料夾，然後執行 flask run。

    b. 在瀏覽器中開啟新索引標籤，然後瀏覽至 http://localhost:5000。

開發您的應用程式

設定並執行「對客戶進行內嵌」範例應用程式之後，您就可以開始開發自己的應用程式。

試用 Power BI 內嵌式分析遊樂場，以開始開發並掌握所有新的 Power BI Embedded 功能和更新。

當您準備好時，請檢閱移至實際執行環境需求。 您也需要容量，並應檢閱容量規劃一文，以確定哪一個 SKU 最符合需求。

重要

如果您使用免費內嵌試用權杖進行開發，則必須購買生產容量。 在購買容量之前，免費試用版本橫幅將繼續出現在內嵌報表頂端。

相關內容

• 移至生產環境
• 為組織內嵌
• 內嵌編頁報表 (部分機器翻譯)

更多問題嗎？ 詢問 Power BI 社群 \(英文\)。