Power BI REST API를 사용하여 향상된 새로 고침

아티클
01/08/2024

REST 호출을 지원하는 모든 프로그래밍 언어를 사용하여 Power BI 의미 체계 모델 새로 고침 REST API에서 데이터 세트 새로 고침 작업을 수행할 수 있습니다.

크고 복잡한 분할된 모델에 대한 새로 고침 최적화는 일반적으로 TOM(테이블 형식 개체 모델), PowerShell cmdlet 또는 TMSL(테이블 형식 모델 스크립팅 언어)을 사용하여 프로그래밍 메서드를 사용하여 호출되었습니다. 그러나 이러한 메서드에는 신뢰할 수 없는 장기 실행 HTTP 연결이 필요합니다.

Power BI 데이터 세트 새로 고침 REST API는 모델 새로 고침 작업을 비동기적으로 수행할 수 있으므로 클라이언트 애플리케이션와의 장기 실행 HTTP 연결이 필요하지 않습니다. 표준 새로 고침 작업에 비해 REST API를 사용하는 향상된 새로 고침은 더 많은 사용자 지정 옵션과 대형 모델에 유용한 다음과 같은 기능을 제공합니다.

일괄 처리된 커밋
테이블 및 파티션 수준 새로 고침
증분 새로 고침 정책 적용
GET 세부 정보 새로 고침
새로 고침 취소

참고 항목

이전에는 REST API를 사용한 비동기 새로 고침 기능을 향상된 새로 고침이라고 지칭했습니다. 그러나 데이터 세트 새로 고침 REST API를 사용하는 표준 새로 고침 기능도 기본적으로 비동기적으로 실행됩니다.
향상된 Power BI REST API 새로 고침 작업은 타일 캐시를 자동으로 새로 고치지 않습니다. 사용자가 보고서에 액세스하는 경우에만 타일 캐시를 새로 고칩니다.

기준 URL

기본 URL에는 다음과 같은 형식이 사용됩니다.

https://api.powerbi.com/v1.0/myorg/groups/{groupId}/datasets/{datasetId}/refreshes

매개 변수에 따라 기본 URL에 리소스 및 작업을 추가할 수 있습니다. 다음 다이어그램에서 Groups, Datasets 및 Refreshes는 컬렉션입니다. Group, Dataset 및 Refresh는 개체입니다.

Diagram that shows asynchronous refresh flow.

요구 사항

REST API를 사용하려면 다음 요구 사항이 필요합니다.

Power BI Premium, 사용자 단위 Premium 또는 Power BI Embedded의 의미 체계 모델
요청 URL에 사용할 그룹 ID 및 데이터 세트 ID
Dataset.ReadWrite.All 권한 범위

새로 고침 횟수는 Pro 및 Premium 모델의 API 기반 새로 고침의 일반적인 제한 사항에 따라 제한됩니다.

인증

모든 호출은 인증 헤더에서 유효한 Microsoft Entra ID OAuth 2 토큰으로 인증해야 합니다. 토큰은 다음과 같은 요구 사항을 충족해야 합니다.

사용자 토큰 또는 애플리케이션 서비스 주체입니다.
대상 그룹이 https://api.powerbi.com으로 올바르게 설정되도록 합니다.
모델에 대한 충분한 권한이 있는 사용자 또는 애플리케이션에서 사용합니다.

참고 항목

REST API 수정 사항은 현재 모델 새로 고침에 대해 정의되어 있지 않습니다.

POST /refreshes

새로 고침을 수행하려면 /refreshes 컬렉션에 POST 동사를 사용하여 새 refresh 개체를 컬렉션에 추가합니다. 응답의 Location 헤더에는 requestId가 포함됩니다. 작업이 비동기적이므로 클라이언트 애플리케이션이 연결을 끊고 필요한 경우 requestId를 사용하여 나중에 상태를 확인할 수 있습니다.

다음 코드는 샘플 요청을 보여 줍니다.

POST https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/datasets/cfafbeb1-8037-4d0c-896e-a46fb27ff229/refreshes

요청 본문은 다음 예제와 비슷할 수 있습니다.

{
    "type": "Full",
    "commitMode": "transactional",
    "maxParallelism": 2,
    "retryCount": 2,
    "objects": [
        {
            "table": "DimCustomer",
            "partition": "DimCustomer"
        },
        {
            "table": "DimDate"
        }
    ]
}

참고 항목

이 서비스는 모델에 대해 한 번에 하나의 새로 고침 작업만 허용합니다. 현재 실행 중인 새로 고침이 있는데 다른 요청이 제출되면 400 Bad Request HTTP 상태 코드가 반환됩니다.

매개 변수

향상된 새로 고침 작업을 수행하려면 요청 본문에 하나 이상의 매개 변수를 지정해야 합니다. 지정된 매개 변수는 기본값 또는 선택적 값을 지정할 수 있습니다. 요청에 매개 변수를 지정하면 다른 모든 매개 변수가 기본값을 사용하여 작업에 적용됩니다. 요청에서 매개 변수를 지정하지 않으면 모든 매개 변수가 기본값을 사용하고 표준 새로 고침 작업이 발생합니다.

이름	Type	기본값	설명
`type`	열거형	`automatic`	평가할 처리 유형입니다. 형식은 TMSL 새로 고침 명령 형식(`full`, `clearValues`, `calculate`, `dataOnly`, `automatic`, `defragment`)에 맞춰 조정됩니다. `add` 형식은 지원되지 않습니다.
`commitMode`	열거형	`transactional`	개체를 일괄로 커밋할지 아니면 완료된 경우에만 커밋할지를 결정합니다. 모드는 `transactional` 또는 `partialBatch`입니다. 새로 고침 작업을 사용하는 `partialBatch` 경우 한 트랜잭션 내에서 발생하지 않습니다. 각 명령은 개별적으로 커밋됩니다. 오류가 발생하면 모델이 비어 있거나 데이터의 하위 집합만 포함할 수 있습니다. 오류를 방지하고 작업이 시작되기 전에 모델에 있던 데이터를 유지하려면 작업을 실행합니다 `commitMode = transactional`.
`maxParallelism`	정수	`10`	처리 명령을 병렬로 실행할 수 있는 최대 스레드 수를 결정합니다. 이 값은 TMSL `Sequence` 명령에 설정되거나 다른 메서드를 사용하여 설정할 수 있는 `MaxParallelism` 속성에 맞춰 조정됩니다.
`retryCount`	정수	`0`	작업이 실패하기 전에 다시 시도할 횟수입니다.
`objects`	배열	전체 모델	처리할 개체의 배열입니다. 각 개체에는 전체 테이블을 처리하는 경우 `table`이 포함되거나, 파티션을 처리하는 경우 `table` 및 `partition`이 포함됩니다. 개체를 지정하지 않으면 전체 모델이 새로 고쳐집니다.
`applyRefreshPolicy`	부울	`true`	증분 새로 고침 정책이 정의된 경우 정책 적용 여부를 결정합니다. 모드는 `true` 또는 `false`입니다. 정책이 적용되지 않으면 전체 프로세스에서 파티션 정의가 변경되지 않은 상태로 유지되고, 테이블의 모든 파티션이 완전히 새로 고쳐집니다. `commitMode`가 `transactional`이면, `applyRefreshPolicy`가 `true` 또는 `false`일 수 있습니다. `commitMode`가 `partialBatch`이면, `applyRefreshPolicytrue`는 지원되지 않고 `applyRefreshPolicy`는 `false`로 설정해야 합니다.
`effectiveDate`	날짜	현재 날짜	증분 새로 고침 정책이 적용되면 `effectiveDate` 매개 변수는 현재 날짜를 재정의합니다. 지정하지 않으면 UTC를 사용하여 현재 요일을 확인합니다.

응답

202 Accepted

응답에는 호출자에게 생성 및 수락한 새로 고침 작업을 가리키는 Location 응답-헤더 필드가 포함됩니다. Location은 요청이 생성한 새 리소스의 위치로, 여기에는 일부 향상된 새로 고침 작업에 필요한 requestId가 포함됩니다. 예를 들어 다음 응답에서는 requestId가 87f31ef7-1e3a-4006-9b0b-191693e79e9e 응답의 마지막 식별자입니다.

x-ms-request-id: 87f31ef7-1e3a-4006-9b0b-191693e79e9e
Location: https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/datasets/cfafbeb1-8037-4d0c-896e-a46fb27ff229/refreshes/87f31ef7-1e3a-4006-9b0b-191693e79e9e

GET /refreshes

/refreshes 컬렉션에 GET 동사를 사용하여 이전, 현재 및 보류 중인 새로 고침 작업을 나열합니다.

응답 본문은 다음 예제와 같이 표시될 수 있습니다.

[
    {
        "requestId": "1344a272-7893-4afa-a4b3-3fb87222fdac",
        "refreshType": "ViaEnhancedApi",
        "startTime": "2020-12-07T02:06:57.1838734Z",
        "endTime": "2020-12-07T02:07:00.4929675Z",
        "status": "Completed",
        "extendedStatus": "Completed"
    },
    {
        "requestId": "474fc5a0-3d69-4c5d-adb4-8a846fa5580b",
        "startTime": "2020-12-07T01:05:54.157324Z",
        "refreshType": "ViaEnhancedApi",
        "endTime": "2020-12-07T01:05:57.353371Z",
        "status": "Unknown"
    }
    {
        "requestId": "85a82498-2209-428c-b273-f87b3a1eb905",
        "refreshType": "ViaEnhancedApi",
        "startTime": "2020-12-07T01:05:54.157324Z",
        "endTime": "2020-12-07T01:05:57.353371Z",
        "status": "Unknown",
        "extendedStatus": "NotStarted"
    }
]

참고 항목

Power BI는 짧은 기간 동안 너무 많은 요청이 있는 경우 요청을 삭제할 수 있습니다. Power BI 새로 고침을 수행하고, 다음 요청을 큐에 대기시키고, 다른 모든 요청을 삭제합니다. 기본적으로 삭제된 요청에 대한 상태는 쿼리할 수 없습니다.

응답 속성

이름	형식	설명
`requestId`	GUID	새로 고침 요청의 식별자입니다. 개별 새로 고침 작업 상태를 쿼리하거나 진행 중인 새로 고침 작업을 취소하려면 `requestId`가 필요합니다.
`refreshType`	문자열	`OnDemand`는 새로 고침이 Power BI 포털을 통해 대화형으로 트리거되었음을 나타냅니다. `Scheduled`는 모델 새로 고침 일정에 따라 새로 고침이 트리거되었음을 나타냅니다. `ViaApi`는 API 호출이 새로 고침을 트리거했음을 나타냅니다. `ViaEnhancedApi`는 API 호출이 향상된 새로 고침을 트리거했음을 나타냅니다.
`startTime`	문자열	새로 고침 시작 날짜 및 시간입니다.
`endTime`	문자열	새로 고침 종료 날짜 및 시간입니다.
`status`	문자열	`Completed`는 새로 고침 작업이 성공적으로 완료되었음을 나타냅니다. `Failed`는 새로 고침 작업이 실패했음을 나타냅니다. `Unknown`은 완료 상태를 확인할 수 없음을 나타냅니다. 이 상태를 사용하면 `endTime`은 비어 있습니다. `Disabled`는 선택적 새로 고침으로 인해 새로 고침이 사용하지 않도록 설정되었음을 나타냅니다. `Cancelled`는 새로 고침이 성공적으로 취소되었음을 나타냅니다.
`extendedStatus`	문자열	`status` 속성을 보강하여 추가 정보를 제공합니다.

참고 항목

Azure Analysis Services에서 완료된 status 결과는 succeeded입니다. Azure Analysis Services 솔루션을 Power BI로 마이그레이션하는 경우 솔루션을 수정해야 할 수 있습니다.

반환되는 새로 고침 작업 수 제한

Power BI REST API는 선택적 $top 매개 변수를 사용하여 새로 고침 기록에서 요청된 항목 수 제한을 지원합니다. 지정하지 않으면 기본값은 사용 가능한 모든 항목입니다.

GET https://api.powerbi.com/v1.0/myorg/groups/{groupId}/datasets/{datasetId}/refreshes?$top={$top}

GET /refreshes/<requestId>

새로 고침 작업의 상태를 확인하려면 requestId를 지정하여 새로 고침 개체에 GET 동사를 사용합니다. 작업이 진행 중인 경우 status는 다음 예제 응답 본문과 같이 InProgress를 반환합니다.

{
    "startTime": "2020-12-07T02:06:57.1838734Z",
    "endTime": "2020-12-07T02:07:00.4929675Z",
    "type": "Full",
    "status": "InProgress",
    "currentRefreshType": "Full",
    "objects": [
        {
            "table": "DimCustomer",
            "partition": "DimCustomer",
            "status": "InProgress"
        },
        {
            "table": "DimDate",
            "partition": "DimDate",
            "status": "InProgress"
        }
    ]
}

DELETE /refreshes/<requestId>

진행 중인 향상된 새로 고침 작업을 취소하려면 requestId를 지정하여 새로 고침 개체에 DELETE 동사를 사용합니다.

예를 들면 다음과 같습니다.

DELETE https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/datasets/cfafbeb1-8037-4d0c-896e-a46fb27ff229/refreshes/1344a272-7893-4afa-a4b3-3fb87222fdac

고려 사항 및 제한 사항

새로 고침 작업에는 다음과 같은 고려 사항 및 제한 사항이 있습니다.

표준 새로 고침 작업

DELETE /refreshes/<requestId>를 사용하여 예약된 또는 주문형 수동 모델 새로 고침을 취소할 수 없습니다.
예약 및 주문형 수동 모델 새로 고침은 GET /refreshes/<requestId>를 사용하여 새로 고침 작업 세부 정보 가져오기를 지원하지 않습니다.
세부 정보 가져오기 및 취소는 향상된 새로 고침에 대한 새로운 작업입니다. 표준 새로 고침은 이러한 작업을 지원하지 않습니다.

Power BI Embedded

Power BI 포털에서 또는 PowerShell을 사용하여 용량을 수동으로 일시 중지하거나 시스템 중단이 발생하는 경우 진행 중인 향상된 새로 고침 작업의 상태는 최대 6시간 동안 InProgress로 유지됩니다. 용량이 6시간 내에 다시 시작되면 새로 고침 작업이 자동으로 다시 시작됩니다. 6시간 이상 경과한 후 용량이 다시 시작되면 새로 고침 작업을 수행할 때 시간 제한 오류가 반환될 수 있습니다. 그러면 새로 고침 작업을 다시 시작해야 합니다.

의미 체계 모델 제거

Power BI는 동적 메모리 관리를 사용하여 용량 메모리를 최적화합니다. 새로 고침 작업을 수행하는 동안 모델이 메모리에서 제거되면 다음과 같은 오류가 반환될 수 있습니다.

{
    "messages": [
        {
            "code": "0xC11C0020",
            "message": "Session cancelled because it is connected to a database that has been evicted to free up memory for other operations",
            "type": "Error"
        }
    ]
}

해결 방법은 새로 고침 작업을 다시 실행하는 것입니다. 동적 메모리 관리 및 모델 제거에 대한 자세한 내용은 모델 제거를 참조하세요.

새로 고침 작업 시간 제한

단일 새로 고침 작업의 최대 시간은 5시간입니다. 새로 고침 작업이 5시간 제한 내에서 성공적으로 완료되지 않고 요청 본문에서 retryCount가 지정되지 않았거나 0(기본값)으로 지정된 경우 시간 제한 오류가 반환됩니다.

retryCount가 1 또는 다른 숫자를 지정하면 5시간 제한이 있는 새 새로 고침 작업이 시작됩니다. 이 다시 시도 작업이 실패하면 서비스는 retryCount에서 지정한 최대 다시 시도 횟수까지 또는 첫 번째 새로 고침 요청이 시작되고 24시간의 향상된 새로 고침 처리 시간 제한까지 계속해서 새로 고침 작업을 다시 시도합니다.

모델 새로 고침 REST API를 사용하여 향상된 데이터 세트 새로 고침 솔루션을 계획할 때는 이러한 시간 제한 및 retryCount 매개 변수를 고려해야 합니다. 초기 새로 고침 작업이 실패하고 retryCount가 1 이상을 지정하면 새로 고침 완료가 5시간을 초과할 수 있습니다.

예를 들어 "retryCount": 1을 사용하여 새로 고침 작업을 요청하고 초기 다시 시도 작업이 시작 시간으로부터 4시간 동안 실패하면 해당 요청에 대한 두 번째 새로 고침 작업이 시작됩니다. 두 번째 새로 고침 작업이 3시간 후에 성공하면 새로 고침 요청을 성공적으로 실행하는 데 걸리는 총 시간은 7시간입니다.

새로 고침 작업이 정기적으로 실패하거나, 5시간의 시간 제한을 초과하거나, 원하는 성공적인 새로 고침 작업 시간을 초과하는 경우 데이터 원본에서 새로 고치는 데이터의 양을 줄이는 것이 좋습니다. 새로 고침을 여러 요청(예: 각 테이블에 대한 요청)으로 분할할 수 있습니다. commitMode 매개 변수에서 partialBatch를 지정할 수도 있습니다.

코드 샘플

시작하기 위한 C# 코드 샘플은 GitHub에서 RestApiSample을 참조하세요.

코드 샘플을 사용하려면 다음을 수행합니다.

리포지토리를 복제하거나 다운로드합니다.
RestApiSample 솔루션을 엽니다.
줄 client.BaseAddress = …를 찾아 기본 URL을 지정합니다.

이 코드 샘플에서는 서비스 주체 인증을 사용합니다.

Power BI REST API를 사용하여 향상된 새로 고침

기준 URL

요구 사항

인증

POST /refreshes

매개 변수

응답

GET /refreshes

응답 속성

반환되는 새로 고침 작업 수 제한

GET /refreshes/<requestId>

DELETE /refreshes/<requestId>

고려 사항 및 제한 사항

표준 새로 고침 작업

Power BI Embedded

의미 체계 모델 제거

새로 고침 작업 시간 제한

코드 샘플

관련 콘텐츠

추가 리소스