Power BI REST API 入門：用自己的帳號登入，不必自行註冊 Entra ID App

| Power BI | 4 Reads

Copyright Notice: This article is an original work licensed under the CC 4.0 BY-NC-ND license. If you wish to repost this article, please include the original source link and this copyright notice.
Source link: https://v2know.com/article/1430

以前一聽到 Power BI REST API，我就會想到：是不是又要註冊 Microsoft Entra ID App、建立 Service Principal、設定憑證或 Client Secret，才能開始使用？如果只是想把 Workspace 裡幾十份 RDL 的資料來源換一個伺服器地址，準備工作看起來似乎比修改本身還麻煩。

這次才知道，透過微軟官方 PowerShell 模組，以自己的 Power BI 帳號互動式登入，就可以呼叫支援使用者身分的 REST API，不必自行註冊 App，也不必建立自己的 Service Principal。對有人操作的日常維護來說，這是一條很實用的入門路徑。

Power BI REST API 是什麼？

REST API 是讓程式透過 HTTP 請求操作 Power BI Service 的介面。網頁操作靠點選按鈕，腳本則向指定網址提交請求，例如讀取 Workspace 的報表清單，或更新已發佈 RDL 的資料來源。

閱讀 API 文件時，主要看三件事：請求網址、HTTP 方法，以及要提交的資料。GET 通常用來讀取；POST 可以用來執行文件指定的操作。要傳送的資料常以 JSON 表示。API 能做什麼，仍以個別端點的功能及權限要求為準。

為什麼不用自己註冊 Entra ID App？

關鍵在於官方 PowerShell 模組已經提供登入功能。Connect-PowerBIServiceAccount 的官方文件明確說明：使用者帳號登入會使用微軟的第一方應用程式（First-Party application）進行驗證。

也就是說，背後仍然有 Entra ID 和應用程式參與驗證，但這條路徑使用的是微軟提供的應用程式。使用者完成登入後，模組便能以該帳號的身分呼叫 API。這與「自己開發一個應用程式，因此自行註冊 App」的準備工作不同。詳見 Connect-PowerBIServiceAccount 官方文件。

這裡要保留一個前提：能登入不代表擁有全部 API 或全部 Workspace 的操作權限。帳號權限、API 支援的驗證方式，以及組織的登入與同意政策仍然適用。若遇到管理員同意或存取限制，需要處理相應政策，不能靠換一個呼叫工具繞過。

已經安裝 MicrosoftPowerBIMgmt，還要安裝 Profile 嗎？

MicrosoftPowerBIMgmt 是完整套件，會安裝多個功能子模組；MicrosoftPowerBIMgmt.Profile 是其中負責登入及 REST 呼叫等功能的子模組。微軟提供完整套件與個別子模組兩種安裝方式，見 Power BI PowerShell 模組說明。

目前狀況接下來怎麼做
已安裝 MicrosoftPowerBIMgmt，登入指令可用直接登入，不用再單獨安裝 Profile
尚未安裝，想使用完整 Power BI 指令集安裝 MicrosoftPowerBIMgmt
尚未安裝，只需要登入及 REST 呼叫可以單獨安裝 MicrosoftPowerBIMgmt.Profile

尚未安裝完整套件時，可以在 PowerShell 執行：

Install-Module MicrosoftPowerBIMgmt -Scope CurrentUser

若只需要 Profile 子模組，則選擇下面這一行即可，不需要兩種安裝方式都執行：

Install-Module MicrosoftPowerBIMgmt.Profile -Scope CurrentUser

-Scope CurrentUser 表示安裝給目前的 Windows 使用者，與 Power BI 的 Workspace 權限無關。Install-Module 是安裝工具；Connect-PowerBIServiceAccount 才是登入服務。已經裝好的工具不用在每次登入前重新安裝。

截至 2026 年 10 月 16 日，微軟的模組總覽文件要求使用 MicrosoftPowerBIMgmt 1.3.84 或以上版本，以配合更新後的登入設定。舊版登入失敗時，應先檢查版本；這項版本要求日後也可能調整。

登入後，先做一次唯讀 REST 呼叫

在同一個 PowerShell 工作階段登入：

Connect-PowerBIServiceAccount

完成互動式登入後，就能使用 Invoke-PowerBIRestMethod。下面的範例會讀取指定 Workspace 的報表清單；請將字串換成實際的 Workspace GUID：

$workspaceId = '填入 Workspace GUID'

$result = Invoke-PowerBIRestMethod -Url "groups/$workspaceId/reports" -Method Get
$reports = $result | ConvertFrom-Json
$reports.value | Select-Object id, name, reportType

Invoke-PowerBIRestMethod 會沿用目前登入的身分，並接受相對網址。上例的網址對應到 https://api.powerbi.com/v1.0/myorg/groups/{workspaceId}/reports，不需要自己把 Access Token 寫進腳本。見 REST 呼叫指令文件及 Get Reports In Group。

實際例子：修改已上傳 RDL 的伺服器地址

以傳統 SQL Server 資料來源為例，RDL 裡的 Data Source 儲存連線資訊；Dataset 則定義查詢和欄位，並引用 Data Source。因此，「修改 Dataset 連到哪個伺服器」通常實際上是在修改 Data Source。

另外，Power BI REST API 裡的 Datasets 主要指語意模型。RDL 並不會因為內部有 Dataset，就成為一個 Workspace 語意模型。這次要使用的是 Reports 下的 Update Datasources In Group：

POST https://api.powerbi.com/v1.0/myorg/groups/{groupId}/reports/{reportId}/Default.UpdateDatasources

假設 RDL 的資料來源名稱是 DS_Main，目前連到 SQL-OLD，要改成 SQL-NEW，資料庫仍是 SalesDB。登入後，可用以下範例更新單份 RDL。這段會修改線上設定，執行前要填入正確的 GUID 及資料來源資訊：

$workspaceId = '填入 Workspace GUID'
$reportId = '填入 RDL Report GUID'

$body = @{
    updateDetails = @(
        @{
            datasourceName = 'DS_Main'
            connectionDetails = @{
                server = 'SQL-NEW'
                database = 'SalesDB'
            }
        }
    )
} | ConvertTo-Json -Depth 5

$updateUrl = "groups/$workspaceId/reports/$reportId/Default.UpdateDatasources"
Invoke-PowerBIRestMethod -Url $updateUrl -Method Post -Body $body -ErrorAction Stop

datasourceName 要填 RDL 內的 Data Source 名稱，不是 Dataset 名稱，也不是 Gateway 連線名稱。此端點提供 server、database 等指定連線欄位，並不是任意改寫整條連線字串。

執行前需確認官方文件列出的限制：

  • 呼叫者必須是資料來源擁有者。
  • 新舊資料來源必須具有相同結構（schema）。
  • 不能改變資料來源類型。
  • 此更新端點不支援 ODBC。

以上範例是針對 SQL Server 的說明，不能直接推廣到每一種 RDL 連線。若 RDL 連的是 Power BI 語意模型、Power Query 連線或其他類型，需要另外確認適用的操作。

批量可以做，但要逐份處理並驗證

更新端點一次指定一份報表，而 updateDetails 可以包含該報表的多個資料來源。跨報表的批量修改，可以用腳本迴圈逐份呼叫。實務上，我會把流程安排為：

  1. 讀取目標 Workspace 的報表清單，篩出 PaginatedReport。
  2. 查詢目前連線，列出確實指向舊伺服器的目標。
  3. 確認每份 RDL 的 Data Source 名稱，建立「報表 ID、資料來源名稱、新伺服器、新資料庫」對照清單。
  4. 先選一份報表試改，完成連線及執行驗證後，再處理其餘目標。
  5. 逐份記錄成功與失敗，重新查詢設定，並驗證代表性報表能否正常執行。

查詢來源可用 Get Datasources In Group。不過，官方回傳範例沒有提供 RDL 的 Data Source 名稱，不應假設清單裡一定有可直接拿來更新的 datasourceName。名稱可以從原始 RDL 確認；需要時，也能透過 Export Report In Group 匯出 RDL 後讀取其定義。

更新連線地址，也不代表 Gateway 與認證已全部設定完成。若新伺服器需要透過內部網路 Gateway 存取，要準備可用的 Gateway 連線及認證，並確認綁定；必要時可使用 Bind To Gateway In Group。API 接受了修改請求之後，仍需要實際執行報表驗證。

什麼時候才需要考慮 Service Principal？

如果是自己在電腦前執行一次維護或批次作業，使用者登入很適合入門。若程式要在伺服器上長期執行、每天定時運作，沒有人在旁邊完成互動式登入，Service Principal 就是值得考慮的常見方案。它使用應用程式身分驗證，通常還要處理憑證或 Secret、租戶設定，以及 Workspace 授權；可參考微軟的 Service Principal 設定文件。

App 與 Service Principal 也有關聯：App 定義應用程式的身分設定，Service Principal 則代表它在某個租戶中的實例。透過 Entra 管理介面註冊 App 時，通常會自動建立本租戶的 Service Principal；若用 Microsoft Graph 建立 App，建立 Service Principal 則是另一個步驟。詳見 應用程式與 Service Principal 的關係。

對我這次的需求而言，最有用的新知識是：想開始使用 Power BI REST API，可以先用官方 PowerShell 模組登入自己的帳號，再學習需要的端點。遇到幾十份報表重複修改同一類設定時，這條路徑就能把原本的手動工作變成可檢查、可記錄的批次流程。

This article was last edited at