教學課程：使用客戶的應用程式內嵌範例內嵌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 相依性

  • 您自己的 Azure Active Directory 租用戶。

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

    • 服務主體 - Azure Active Directory (Azure AD) 服務主體物件，可讓 Azure AD 驗證您的應用程式。

    • 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

• .NET Framework 4.8

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

  • Visual Studio

  • Visual Studio Code

Python

• Python 3 (或更高版本)

  注意

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

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

  • Visual Studio

  • Visual Studio Code

方法

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

1. 選取您的驗證方法。

2. 註冊 Azure AD 應用程式。

3. 建立 Power BI 工作區。

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

5. 取得內嵌參數值。

6. 服務主體 API 存取

7. 啟用工作區存取。

8. 內嵌內容。

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

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

下表描述服務主體與主要使用者驗證方法之間的一些主要差異。

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

步驟 2 - 註冊 Azure AD 應用程式

向 Azure AD 註冊應用程式可讓您：

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

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

注意

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

步驟 3 - 建立 Power BI 工作區

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

提示

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

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

1. 登入 Power BI。

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 - 取得內嵌參數值

若要內嵌內容，您需要取得特定參數值。 下表顯示必要值，並指出它們是否適用于 服務主體 驗證方法、 主要使用者 驗證方法或兩者。

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

參數	服務主體	主要使用者
用戶端識別碼
Workspace ID \(工作區識別碼\)
Report ID \(報表識別碼\)
用戶端密碼
租用戶識別碼
Power BI 使用者名稱
Power BI 密碼

用戶端識別碼

提示

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

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

1. 登入 Microsoft Azure。

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

3. 選取您用來內嵌Power BI內容Azure AD應用程式。

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內容Azure AD應用程式。

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

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

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

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

注意

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

租用戶識別碼

提示

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

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

1. 登入 Microsoft Azure。

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

3. 選取您用來內嵌 Power BI 內容的 Azure AD 應用程式。

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

Power BI 使用者名稱及密碼

提示

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

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

步驟 6 - 服務主體 API 存取

提示

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

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

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

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

   

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

3. 展開 [允許服務主體使用 Power BI API]，並啟用此選項。

   

注意

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

• 建立 Azure AD 安全性群組
• 啟用 Power BI 服務系統管理員設定

步驟 7 - 啟用工作區存取

若要啟用 Azure AD 應用程式存取物件，例如 Power BI 服務中的報表、儀表板和資料集，請將 服務主體 或 主要使用者新增為工作區 的成員 或 管理員 。

1. 登入 Power BI 服務。

2. 捲動至您想要啟用存取權的工作區，然後從 [更多] 功能表中，選取 [工作區存取權]。

   

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

   注意

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

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

   注意

   客戶範例應用程式的 內嵌 僅支援上面所列的架構。 React範例應用程式僅支援組織解決方案的內嵌。

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

.NET Core

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

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

   • 如果您使用 Visual Studio Code，請開啟 AppOwnsData 資料夾。

7. 開啟 appsettings.json。

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

   參數	服務主體	主要使用者
   AuthenticationMode	ServicePrincipal	MasterUser
   ClientId	您的 Azure AD 應用程式用戶端識別碼	您的 Azure AD 應用程式用戶端識別碼
   TenantId	您的 Azure AD 租用戶識別碼	N/A
   PbiUsername	N/A	您的「主要使用者」使用者名稱，請參閱 Power BI 使用者名稱和密碼
   PbiPassword	N/A	您的「主要使用者」密碼，請參閱 Power BI 使用者名稱和密碼
   ClientSecret	您的 Azure AD 用戶端祕密	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	您的 Azure AD 應用程式用戶端識別碼	您的 Azure AD 應用程式用戶端識別碼
   workspaceId	內嵌報表所在工作區的識別碼，請參閱工作區識別碼	內嵌報表所在工作區的識別碼，請參閱工作區識別碼
   reportId	所要內嵌報表的識別碼，請參閱報表識別碼	所要內嵌報表的識別碼，請參閱報表識別碼
   pbiUsername	N/A	您的「主要使用者」使用者名稱，請參閱 Power BI 使用者名稱和密碼
   pbiPassword	N/A	您的「主要使用者」密碼，請參閱 Power BI 使用者名稱和密碼
   applicationSecret	您的 Azure AD 用戶端祕密	N/A
   tenant	您的 Azure AD 租用戶識別碼	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] \(完成\)。 您就能夠在 [Servers] \(伺服器\) 索引標籤中看到 Tomcat 伺服器。

8. 在 Eclipse 中開啟專案：

   重要

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

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

   b. 在 [從檔案系統或封存匯入專案] 視窗中，選取 [目錄 ]，然後開啟 [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	您的 Azure AD 應用程式用戶端識別碼	您的 Azure AD 應用程式用戶端識別碼
    pbiUsername	N/A	您的「主要使用者」使用者名稱，請參閱 Power BI 使用者名稱和密碼
    pbiPassword	N/A	您的「主要使用者」密碼，請參閱 Power BI 使用者名稱和密碼
    tenantId	您的 Azure AD 租用戶識別碼	N/A
    appSecret	您的 Azure AD 用戶端祕密	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	您的 Azure AD 應用程式用戶端識別碼	您的 Azure AD 應用程式用戶端識別碼
   workspaceId	內嵌報表所在工作區的識別碼，請參閱工作區識別碼	內嵌報表所在工作區的識別碼，請參閱工作區識別碼
   reportId	所要內嵌報表的識別碼，請參閱報表識別碼	所要內嵌報表的識別碼，請參閱報表識別碼
   pbiUsername	N/A	您的「主要使用者」使用者名稱，請參閱 Power BI 使用者名稱和密碼
   pbiPassword	N/A	您的「主要使用者」密碼，請參閱 Power BI 使用者名稱和密碼
   clientSecret	您的 Azure AD 用戶端祕密	N/A
   tenantId	您的 Azure AD 租用戶識別碼	N/A

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	您的 Azure AD 租用戶識別碼	N/A
    CLIENT_ID	您的 Azure AD 應用程式用戶端識別碼	您的 Azure AD 應用程式用戶端識別碼
    CLIENT_SECRET	您的 Azure AD 用戶端祕密	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。

開發您的應用程式

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

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

後續步驟

移至生產環境

為組織內嵌

內嵌編頁報表

詢問 Power BI 社群