Datasets - Execute Dax Queries

서비스:: Power BI REST APIs

API 버전:: v1.0

제공된 데이터 세트에 대해 DAX(데이터 분석 식) 쿼리를 실행합니다. 데이터 세트는 내 작업 영역에 있어야 합니다. 응답은 Apache 화살표 형식으로 반환됩니다.

사용 권한 또는 쿼리 오류로 인해 다음이 발생합니다.

응답 오류(예: 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)입니다.

Permissions

통합 설정 아래에 있는 테넌트 설정 데이터 세트 쿼리 실행 REST API를 사용하도록 설정해야 합니다.

사용자에게 데이터 세트 읽기 및 빌드 권한이 있어야 합니다. 자세한 내용은 데이터 세트 액세스 권한 관리를 참조하세요.

필수 범위

Dataset.ReadWrite.All 또는 Dataset.Read.All

Limitations

이 API는 용량에 호스트되는 데이터 세트에만 사용할 수 있습니다.
Azure Analysis Services에서 호스트되거나 온-프레미스 Azure Analysis Services 모델에 대한 라이브 연결이 있는 데이터 세트는 지원되지 않습니다.
API 호출당 하나의 쿼리이지만 쿼리에는 여러 평가 문이 있을 수 있습니다.
쿼리되는 데이터 세트에 관계없이 사용자당 분당 120개의 쿼리 요청이 제한됩니다.
서비스 주체를 사용하려면 관리자 테넌트 설정에서 서비스 주체가 개발자 설정에서 Power BI API를 사용하도록 설정되었는지 확인합니다. RLS를 사용하는 의미 체계 모델에 대한 자세한 내용은 RLS 제한 사항을 참조하세요.
현재 DAX 쿼리 및 INFO 함수만 지원됩니다. MDX 및 DMV 쿼리는 지원되지 않습니다.

응답 형식

응답 본문에는 하나 이상의 연결된 Apache 화살표 IPC 스트림이 포함됩니다. 각 스트림은 자체 스키마 및 레코드 일괄 처리를 사용하여 자체 포함됩니다. 응답을 처리하려면 Apache Arrow 클라이언트 라이브러리를 사용합니다.

응답에는 스키마 수준 메타데이터(화살표 스키마의 키-값 쌍)로 식별되는 다음 행 집합 형식이 포함될 수 있습니다.

데이터 행 집합: 쿼리 결과를 포함합니다. 특수 메타데이터 키가 없습니다. 열 이름과 형식은 DAX 쿼리에 의해 결정됩니다.
오류 행 집합: 스키마 메타데이터에서 식별 IsError = true 됩니다. 열( ErrorCode, , ErrorMessageErrorDescription및 원본 위치 필드)을 포함합니다. 스키마 메타데이터에는 (16진수 오류 코드) 및 FaultString (오류 메시지)도 포함 FaultCode 됩니다.

응답의 레코드 일괄 처리는 압축을 LZ4_FRAME 사용합니다. pyarrow 라이브러리는 이를 자동으로 처리합니다. .NET 경우 Apache.Arrow.Compression NuGet 패키지를 설치합니다.

Important

쿼리 오류는 화살표 스트림에 오류 행 집합이 있는 HTTP 200을 반환합니다. 성공적인 HTTP 상태 코드에서도 항상 스키마 메타데이터 IsError 를 확인합니다.

다음 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 스트림 구문 분석, 오류 검색 및 LZ4 압축 해제를 처리하는 이 SDK에서 DaxQueryArrowResponseReader 클래스를 사용합니다.

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

URI 매개 변수

Name	In(다음 안에)	필수	형식	Description
datasetId	path	True	string (uuid)	데이터 세트 ID

요청 본문

Name	필수	형식	Description
query	True	string	쿼리 텍스트입니다.
applicationContext		string	작업에 대한 추가 정보를 포함하는 JSON 구조체입니다.
culture		string	로캘별 쿼리 서식을 제어하는 문화권 코드(예: `en-US`. 지원되는 문화권 코드에 대한 자세한 내용은 지원 언어 및 Power BI 국가/지역을 참조하세요.
customData		string	동적 RLS에서 사용할 사용자 지정 데이터입니다. 예를 들어 `North America` 모델의 `CUSTOMDATA()` 함수에서 참조할 수 있습니다.
effectiveUsername		string	쿼리에 대한 유효한 사용자 이름입니다.
memoryLimit		integer (int64)	쿼리에 대한 메모리 제한(KB)입니다.
queryTimeout		integer	쿼리 시간 제한(초)입니다.
resultSetRowCountLimit		integer	반환할 최대 행 수입니다. 기본값은 1,000,000개 행입니다.
roles		string[]	사용자에게 할당된 역할입니다.
schemaOnly		boolean	쿼리에서 스키마만 반환해야 하는지 여부입니다.

응답

Name	형식	Description
200 OK	string	쿼리가 성공적으로 실행되었습니다. Apache 화살표 형식의 이진 데이터를 반환합니다. Media Types: "application/vnd.apache.arrow.stream"

Name

형식

Description

200 OK

string

쿼리가 성공적으로 실행되었습니다. Apache 화살표 형식의 이진 데이터를 반환합니다.

Media Types: "application/vnd.apache.arrow.stream"

예제

Execute query with culture

Execute query with custom data

Execute query with effective username

Execute simple DAX query

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"
}

샘플 응답

상태 코드:: 200

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"
}

샘플 응답

상태 코드:: 200

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
}

샘플 응답

상태 코드:: 200

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
}

샘플 응답

상태 코드:: 200

정의

DatasetExecuteDaxQueriesRequest

Object

데이터 세트에 대해 쿼리를 실행하는 요청

Name	형식	Description
applicationContext	string	작업에 대한 추가 정보를 포함하는 JSON 구조체입니다.
culture	string	로캘별 쿼리 서식을 제어하는 문화권 코드(예: `en-US`. 지원되는 문화권 코드에 대한 자세한 내용은 지원 언어 및 Power BI 국가/지역을 참조하세요.
customData	string	동적 RLS에서 사용할 사용자 지정 데이터입니다. 예를 들어 `North America` 모델의 `CUSTOMDATA()` 함수에서 참조할 수 있습니다.
effectiveUsername	string	쿼리에 대한 유효한 사용자 이름입니다.
memoryLimit	integer (int64)	쿼리에 대한 메모리 제한(KB)입니다.
query	string	쿼리 텍스트입니다.
queryTimeout	integer	쿼리 시간 제한(초)입니다.
resultSetRowCountLimit	integer	반환할 최대 행 수입니다. 기본값은 1,000,000개 행입니다.
roles	string[]	사용자에게 할당된 역할입니다.
schemaOnly	boolean	쿼리에서 스키마만 반환해야 하는지 여부입니다.