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

아티클
01/08/2025

POWER BI Refresh Dataset REST API를 사용하여 REST 호출을 지원하는 프로그래밍 언어를 사용하여 의미 체계 모델 새로 고침 작업을 수행할 수 있습니다.

크고 복잡한 분할된 모델에 최적화된 새로 고침은 일반적으로 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에 리소스 및 작업을 추가할 수 있습니다. 다음 다이어그램에서 그룹, 데이터 세트및 새로 고침은/는 컬렉션입니다. 그룹, 데이터 세트, 새로 고침는 개체입니다.

비동기 새로 고침 흐름을 보여 주는 다이어그램

요구 사항

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

Power BI 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 동사를 사용하여 컬렉션에 새 새로 고침 개체를 추가합니다. 응답의 위치 헤더에는 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,
    "timeout": "02:00:00",
    "objects": [
        {
            "table": "DimCustomer",
            "partition": "DimCustomer"
        },
        {
            "table": "DimDate"
        }
    ]
}

메모

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

매개 변수

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

이름	유형	기본값	묘사
`type`	열거형	`automatic`	수행할 처리 유형입니다. 형식은 `full`, `clearValues`, `calculate`, `dataOnly`, `automatic`및 `defragment`TMSL 새로 고침 명령 형식과 일치합니다. `add` 형식은 지원되지 않습니다.
`commitMode`	열거형	`transactional`	일괄 처리로 개체를 커밋할지 아니면 완료된 경우에만 커밋할지를 결정합니다. 모드는 `transactional`과 `partialBatch`입니다. `partialBatch` 사용하는 경우 새로 고침 작업은 한 트랜잭션 내에서 발생하지 않습니다. 각 명령은 개별적으로 커밋됩니다. 오류가 발생하면 모델이 비어 있거나 데이터의 하위 집합만 포함할 수 있습니다. 오류를 방지하고 작업이 시작되기 전에 모델에 있던 데이터를 유지하려면 `commitMode = transactional`사용하여 작업을 실행합니다.
`maxParallelism`	Int	`10`	처리 명령을 병렬로 실행할 수 있는 최대 스레드 수를 결정합니다. 이 값은 TMSL `MaxParallelism` 명령이나 다른 메서드를 사용하여 설정할 수 있는 `Sequence` 속성과 일치합니다.
`retryCount`	Int	`0`	작업이 실패하기 전에 다시 시도한 횟수입니다.
`objects`	배열	전체 모델	처리할 개체의 배열입니다. 각 개체에는 전체 테이블을 처리할 때 `table` 또는 파티션을 처리할 때 `table` 및 `partition` 포함됩니다. 개체를 지정하지 않으면 전체 모델이 새로 고쳐집니다.
`applyRefreshPolicy`	부울(Boolean)	`true`	증분 새로 고침 정책이 정의된 경우 정책을 적용할지 여부를 결정합니다. 모드가 `true` 또는 `false`. 정책이 적용되지 않으면 전체 프로세스는 파티션 정의를 변경하지 않고 테이블의 모든 파티션을 완전히 새로 고칩니다. `commitMode`이 `transactional`인 경우 `applyRefreshPolicy`는 `true` 또는 `false`가 될 수 있습니다. `commitMode`가 `partialBatch`일 경우, `applyRefreshPolicy`의 `true`가 지원되지 않으므로 `applyRefreshPolicy`는 `false`로 설정해야 합니다.
`effectiveDate`	날짜	현재 날짜	증분 새로 고침 정책이 적용되는 경우, `effectiveDate` 매개 변수는 현재 날짜를 대체합니다. 지정하지 않으면 현재 날짜는 '새로 고침'표준 시간대 구성을 사용하여 결정됩니다.
`timeout`	문자열	05:00:00(5시간)	`timeout` 지정하면 의미 체계 모델의 각 데이터 새로 고침 시도가 해당 시간 제한을 준수합니다. 단일 새로 고침 요청에는 `retryCount` 지정된 경우 여러 번의 시도가 포함될 수 있으며, 이로 인해 총 새로 고침 기간이 지정된 시간 제한을 초과할 수 있습니다. 예를 들어 `timeout`를 1시간으로 설정하고 `retryCount`을 2로 설정하면 총 새로 고침 시간이 최대 3시간이 될 수 있습니다. 사용자는 `timeout` 조정하여 더 빠른 오류 검색을 위해 새로 고침 기간을 단축하거나 더 복잡한 데이터 새로 고침을 위해 기본 5시간 이상으로 확장할 수 있습니다. 그러나 재시도를 포함하여 총 새로 고침 기간은 24시간을 초과할 수 없습니다.

응답

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",
        "status": "Unknown"
    }
    {
        "requestId": "85a82498-2209-428c-b273-f87b3a1eb905",
        "refreshType": "ViaEnhancedApi",
        "startTime": "2020-12-07T01:05:54.157324Z",
        "status": "Unknown",
        "extendedStatus": "NotStarted"
    }
]

메모

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

응답 속성

이름	유형	묘사
`requestId`	Guid(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>을(를) 사용하여 새로 고침 작업 세부 정보를 조회하는 것을 지원하지 않습니다.
세부 정보 가져오기 및 취소는 향상된 새로 고침에만 사용되는 새로운 작업입니다. 표준 새로 고침은 이러한 작업을 지원하지 않습니다.

파워 BI 임베디드

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

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

새로 고침 작업 시간 제한

retryCount 지정된 경우 새로 고침 작업에 여러 번의 시도가 포함될 수 있습니다. 각 시도의 기본 제한 시간은 5시간이며 timeout 매개 변수를 사용하여 조정할 수 있습니다. 재시도를 포함한 총 새로 고침 기간은 24시간을 초과하면 안됩니다.

retryCount이(가) 숫자를 지정하면 새로 고침 작업이 시간 제한과 함께 시작됩니다. 서비스는 성공하거나, retryCount 제한에 도달하거나, 첫 번째 시도에서 최대 24시간에 도달할 때까지 이 작업을 다시 시도합니다.

timeout 조정하여 더 빠른 오류 검색을 위해 새로 고침 기간을 단축하거나 더 복잡한 데이터 새로 고침을 위해 기본 5시간 이상으로 확장할 수 있습니다.

데이터 세트 REST API 새로 고침을 사용하여 의미 체계 모델 새로 고침을 계획할 때, 시간 제한 설정 및 retryCount 매개 변수를 고려합니다. 초기 시도가 실패하고 retryCount가 1 이상으로 설정된 경우 새로 고침이 시간 제한을 초과할 수 있습니다. "retryCount"를 사용하여 새로 고침을 요청하는 경우: 1이고 4시간 후에 첫 번째 시도가 실패하면 두 번째 시도가 시작됩니다. 3시간 후에 성공하면 새로 고침의 총 시간은 7시간입니다.

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

코드 샘플

C# 코드 샘플을 시작하려면 GitHub에서 RestApiSample 참조하세요.

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

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

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

다음을 통해 공유

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

기본 URL

요구 사항

인증

POST /refreshes

매개 변수

응답

GET /refreshes

응답 속성

반환된 새로 고침 작업 수 제한

GET /refreshes/<requestId>

DELETE /refreshes/<requestId>

고려 사항 및 제한 사항

표준 새로 고침 작업

파워 BI 임베디드

의미 체계 모델 제거

새로 고침 작업 시간 제한

코드 샘플

피드백

추가 리소스

다음을 통해 공유

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

기본 URL

요구 사항

인증

POST /refreshes

매개 변수

응답

GET /refreshes

응답 속성

반환된 새로 고침 작업 수 제한

GET /refreshes/<requestId>

DELETE /refreshes/<requestId>

고려 사항 및 제한 사항

표준 새로 고침 작업

파워 BI 임베디드

의미 체계 모델 제거

새로 고침 작업 시간 제한

코드 샘플

관련 콘텐츠

피드백

추가 리소스