執行 DAX 查詢 REST API 的最佳實務

請遵循以下建議，在生產工作負載中充分發揮 Execute DAX Queries REST API 的效能。

選擇合適的端點

備註

執行 DAX 查詢 API 僅適用於位於 Power BI 容量（Premium、Fabric 或 Embedded）上的語意模型。 不支援沒有容量指派的語意模型。

Power BI 提供兩個 REST API 用於執行 DAX 查詢。 選擇最適合您客戶能力的方案：

  • 執行 DAX 查詢 （Arrow） — 只要您的客戶端應用程式能使用二進位 Arrow IPC 串流，就使用。 Arrow 提供更小的有效載荷、無損型別精確度，以及零複製反序列化，支援像 pandas、Polars 和 Apache Spark 等欄位框架。 此 API 也支援進階參數如 queryTimeout 和 resultsetRowcountLimit。 需要 Premium 或 Fabric 容量。
  • Execute Queries （JSON） — 當您的消費者是低程式碼/無程式碼平台、Power Automate流程，或任何只能解析 JSON 的工具時，請使用此。 此 API 支援 Pro、PPU 及 Premium/Fabric 容量，但每個查詢有 100,000 列及 1,000,000 個值的硬性限制。

一般來說，如果你的結果集超過幾百筆資料列、需要匯入分析管線，或者需要保持精確的類型準確性，請使用 Arrow 的 DAX 查詢 API 來執行。

優化 Arrow 端點的 DAX 查詢

高效的 DAX 同時降低了查詢執行時間與回應有效載荷大小：

  • 只回傳你需要的欄位就好。 使用 SELECTCOLUMNS 或明確的欄位列表，而不是回傳整個資料表。 每新增一欄會使結構（schema）和記錄批次的大小增加。
  • 偏好使用SUMMARIZECOLUMNS 而非 ADDCOLUMNS 並搭配 FILTER。 SUMMARIZECOLUMNS 在 VertiPaq 引擎中產生更有效率的查詢計畫。
  • 用 TOPN 來限制行數。 當你只需要頂尖結果時，就 TOPN 把極限推到引擎裡，而不是把所有資料列都轉移到客戶端過濾。
  • 避免在查詢中使用複雜的計算欄位。 度量和彙總沒問題，但在大型資料表上進行列層級計算會大幅拖慢執行速度。
  • 將多個 EVALUATE 語句合併在一個請求中。 執行 DAX 查詢 API 支援在同一EVALUATE字串內包含多個query語句，每個語句回傳獨立的結果集。 這樣可以避免分開 HTTP 往返所帶來的額外開銷。

有效管理認證

  • 快取並重複使用代幣。 使用 MSAL 內建的 Token 快取，避免每次請求都需呼叫 Microsoft Entra ID。 對於機密用戶端流程，當您重複使用相同的ConfidentialClientApplication實例時，MSAL 會自動快取記號。
  • 使用機密客戶憑證來提供服務。 對於無人值守的中階服務，請使用用戶端憑證（用戶端秘密或憑證）代替委派的使用者憑證。 這避免了對已登入使用者會話的依賴。
  • 優先選擇在 Azure 中使用托管身份識別。 當你的服務在 Azure（App Service、Functions、AKS）執行時，請使用受管理身份來完全消除憑證管理。
  • 優雅地處理代幣到期。 存取權代幣通常在一小時後過期。 請先查看 401 Unauthorized 回應並在重試前刷新標記。

處理錯誤與重試

執行 DAX 查詢 API 可透過兩種方式回傳錯誤：

  1. HTTP 層級錯誤 — 標準 HTTP 狀態碼，帶有 JSON 錯誤主體。 常見代碼：

    狀態碼 Meaning Action
    400 錯誤請求（DAX 無效，缺少參數） 修正請求——不要重試。
    401 未授權（過期或無效的令牌） 重新整理代幣並重試一次。
    403 禁止（權限不足） 確認呼叫者在語意模型上擁有建置與讀取權限。
    429 請求太多（被限速） 等待Retry-After 標頭中的時間長度後，再重試。
    500 / 502 / 503 暫時性伺服器錯誤 使用指數退避進行重試。

  2. 串流層級錯誤 — 在 HTTP 200 中，錯誤數據列集被嵌入於 Arrow 回應中。 請檢查 Arrow 架構的元資料 IsError=true ，閱讀 FaultCode 和 FaultString 元資料的值，以及錯誤列以獲得詳細的位置資訊。

對於瞬態錯誤，請實作帶有抖動的指數退避。 從一秒開始，每次重試加倍，時間上限為30秒。 限制重試次數為三到四次。

控制結果集大小

大型結果集會同時佔用服務容量與呼叫用戶端的記憶體。 每個請求都受限於容量的記憶體限制。

為了讓結果集易於管理：

  • 在請求文中設定 resultsetRowcountLimit 。 這會強制每個結果集的伺服器端列數限制。 如果你知道消費者只需要 10,000 筆資料，就明確設定限制。
  • 在你的 DAX 查詢中使用 TOPN。 TOPN 限制引擎層級的列數，比截斷客戶端更有效率。
  • 流程記錄批次是增量式的。 箭頭回應會被拆分成最多 100,000 列的記錄批次。 在Python中，處理大量結果時，以 reader.read_next_batch() 來遍歷批次，而非呼叫 reader.read_all()，以保持記憶體使用量不變。

確保您的中階層服務安全

如果您建立一個中介層服務，用於轉發 DAX 查詢給下游消費者：

  • 驗證來電者身份。 在將查詢轉發至 Power BI 之前，請先用 Microsoft Entra ID 或其他身份提供者驗證收到的請求。 切勿將執行 DAX 查詢端點暴露為開放代理。
  • 強制最低特權。 只授予服務主體所需的權限（針對特定語意模型的建置與閱讀）。 不要用工作區管理員或租戶管理員角色來存取 API。
  • 不要把憑證嵌入程式碼裡。 將客戶端秘密儲存在 Azure Key Vault 或使用受管理身份。 定期輪換秘密。
  • 清理 DAX 輸入。 如果你的中階系統接受呼叫者的 DAX 查詢文字，請驗證輸入以避免注入意外操作。
  • 請謹慎使用這個 effectiveUsername 參數。 此參數代表特定使用者套用 Row-Level 安全性。 確保呼叫身分被授權模仿指定的使用者。

監視與記錄

追蹤您的 API 使用狀況與效能：

  • 日誌查詢元資料 — 記錄每個請求的查詢文字、回應大小、HTTP 狀態及持續時間。 這有助於辨識查詢緩慢和意外的錯誤突增。
  • 監控限速率 — 以請求總數的百分比追蹤 429 回應。 上升趨勢顯示你需要減少請求頻率或分散負載。
  • 衡量反序列化時間 — 對於 Arrow 回應，將讀取與實體化記錄批次的時間與 HTTP 往返時間分開記錄。 這有助於區分網路延遲與用戶端處理。
  • Use Application Insights 或等效 — 如果您的中階系統運行於 Azure，啟用 Application Insights 以取得相依追蹤、故障警示及端對端分散式追蹤。
  • 追蹤令牌快取命中率 — 低快取命中率意味著頻繁的令牌擷取呼叫，增加延遲，且是 MSAL 快取設定錯誤的徵兆。

相關內容

  • 上次更新時間：