Datasets - Execute Dax Queries

對所提供的語意模型執行資料分析表達式（DAX）查詢。 語意模型可以駐留在 My workspace 或其他工作空間，前提是呼叫者擁有所需的權限。 回覆以Apache Arrow格式回傳。

權限或查詢錯誤將導致：

• 回應錯誤，例如 XMLA endpoint feature is disabled. Turn on the tenant setting 'Allow XMLA endpoints and Analyze in Excel with on-premises semantic models' to enable this feature.。
• 一個成功的 HTTP 狀態碼（200），並有一個包含錯誤細節的記錄批次。

權限

必須在 整合設定底下找到 數據集執行查詢 REST API的租用戶設定。

用戶必須具有數據集讀取和建置許可權。 如需詳細資訊，請參閱 管理數據集訪問許可權。

必要範圍

Dataset.ReadWrite.All 或 Dataset.Read.All

Limitations

• 此 API 僅支援與 Power BI 服務 現代基礎架構相容的語意模型。 未支援的類別包括：
  • 管理監控工作區中的語意模型與使用量指標模型。
  • 仍使用 1103 相容性層級的語意模型。
  • 使用已棄用功能的語意模型，如推送語意模型、在 Power BI 服務 中由 CSV 檔案建立的模型，或內容包。
• 不支援裝載於 Azure Analysis Services 或與內部部署 Azure Analysis Services 模型有即時連線的數據集。
• 查詢限制：
  • 每次 API 呼叫一次查詢，但查詢可以包含多個 evaluate 語句。
  • 以下限制適用於所查詢的語意模型：
    • 全域限制為每位使用者每分鐘 120 次查詢請求。
    • Power BI Pro 與每位使用者的高級查詢（PPU）每分鐘限制為 40 筆查詢請求。
  • 目前僅支援 DAX 查詢與 INFO 函式。 不支援 MDX 和 DMV 查詢。
• 服務負責人與冒充限制：
  • 若要使用服務主體，請確定系統管理員租用戶設定 [允許服務主體在 開發人員設定 下使用Power BI API。 欲了解更多關於RLS語意模型的資訊，請參閱 RLS的限制。
  • 該 effectiveUsername 屬性僅能由包含語意模型的工作區管理員使用者使用。
  • roles使用者僅在指定角色成員或為包含語意模型的工作空間管理員時，才能使用此屬性。
  • 服務負責人不能是角色成員。 服務主體只有在成為包含語意模型的工作區管理員時才能使用 roles 。

回應格式

回應體包含一個或多個串接的 Apache Arrow IPC 串流。 每個串流都自包含，擁有自己的結構與記錄批次。 要處理回應，請使用 Apache Arrow 用戶端函式庫。

回應可能包含以下列集類型，透過結構層元資料（Arrow 架構中的鍵值對）來識別：

• 資料列集：包含查詢結果。 沒有特殊的元資料金鑰。 欄位名稱與類型由 DAX 查詢決定。
• 錯誤列集：由 IsError = true 結構中繼資料識別。 包含欄位 ErrorCode：、、 ErrorMessage、 ErrorDescription及來源位置欄位。 結構元資料還包括 FaultCode （十六進位錯誤代碼）和 FaultString （錯誤訊息）。

回應中的記錄批次會使用LZ4_FRAME壓縮。 Pyarrow 函式庫會自動處理這件事。 .NET方面，安裝 Apache.Arrow.Compression NuGet 套件。

以下Python範例展示了如何使用 pyarrow 讀取資料並檢查錯誤：

import io
import pyarrow as pa

# response = requests.post(url, headers=headers, json=request_body)
stream = io.BytesIO(response.content)
results = []

while stream.tell() < len(response.content):
    try:
        reader = pa.ipc.open_stream(stream)
        table = reader.read_all()
        metadata = {
            k.decode(): v.decode()
            for k, v in (reader.schema.metadata or {}).items()
        }
        if metadata.get("IsError") == "true":
            raise RuntimeError(
                f"Query error [{metadata.get('FaultCode')}]: "
                f"{metadata.get('FaultString')}"
            )
        else:
            results.append(table)
    except pa.ArrowInvalid:
        break

print(results[0].to_pandas())

對於.NET，請使用此 SDK 中的 DaxQueryArrowResponseReader 類別，該類別處理串流解析、錯誤偵測及 LZ4 解壓縮。

POST https://api.powerbi.com/v1.0/myorg/datasets/{datasetId}/executeDaxQueries

URI 參數

要求本文

回覆

範例

Execute query with culture

POST https://api.powerbi.com/v1.0/myorg/datasets/cfafbeb1-8037-4d0c-896e-a46fb27ff229/executeDaxQueries

{
  "query": "EVALUATE ROW(\"Formatted Date\", FORMAT(DATE(2024, 12, 31), \"Long Date\"))",
  "culture": "en-US"
}

Execute query with custom data

POST https://api.powerbi.com/v1.0/myorg/datasets/cfafbeb1-8037-4d0c-896e-a46fb27ff229/executeDaxQueries

{
  "query": "EVALUATE FILTER('Sales', 'Sales'[Region] = CUSTOMDATA())",
  "customData": "North America"
}

Execute query with effective username

POST https://api.powerbi.com/v1.0/myorg/datasets/cfafbeb1-8037-4d0c-896e-a46fb27ff229/executeDaxQueries

{
  "query": "EVALUATE SUMMARIZECOLUMNS('Sales'[Region], \"Total\", SUM('Sales'[Amount]))",
  "effectiveUsername": "user@contoso.com",
  "roles": [
    "SalesRole"
  ],
  "queryTimeout": 300
}

Execute simple DAX query

POST https://api.powerbi.com/v1.0/myorg/datasets/cfafbeb1-8037-4d0c-896e-a46fb27ff229/executeDaxQueries

{
  "query": "EVALUATE VALUES('Product'[Category])",
  "queryTimeout": 600,
  "schemaOnly": false,
  "resultSetRowCountLimit": 100000
}

定義

DatasetExecuteDaxQueriesRequest

對數據集執行查詢的要求