REST API를 사용한 비동기 새로 고침

아티클
08/08/2024

REST 호출을 지원하는 프로그래밍 언어를 사용하면 쿼리 스케일 아웃을 위한 읽기 전용 복제본 동기화를 포함하여 Azure Analysis Services 테이블 형식 모델에서 비동기 데이터 새로 고침 작업을 수행할 수 있습니다.

데이터 새로 고침 작업은 데이터 볼륨, 파티션을 사용한 최적화 수준 등을 포함한 여러 요인에 따라 다소 시간이 걸릴 수 있습니다. 일반적으로 이러한 작업은 TOM(테이블 형식 개체 모델) PowerShell cmdlet 또는 TMSL(테이블 형식 모델 스크립팅 언어) 등을 사용하는 기존 메서드로 호출되었습니다. 그러나 이러한 메서드는 종종 신뢰할 수 없는, 장기 실행 HTTP 연결을 요구할 수 있습니다.

Azure Analysis Services용 REST API에서는 데이터 새로 고침 작업을 비동기적으로 실행할 수 있습니다. REST API를 사용하면 클라이언트 애플리케이션에서의 장기 실행 HTTP 연결이 필요하지 않습니다. 안정성을 위한 기타 기본 제공 기능(예: 자동 다시 시도 및 일괄 처리 커밋)도 있습니다.

기준 URL

기준 URL은 다음 형식을 따릅니다.

https://<rollout>.asazure.windows.net/servers/<serverName>/models/<resource>/

예를 들어 이름이 AdventureWorks이고, 미국 서부 Azure 지역의 myserver 서버에 있는 모델을 가정합니다. 서버 이름은 다음과 같습니다.

asazure://westus.asazure.windows.net/myserver

이 서버 이름의 기준 URL은 다음과 같습니다.

https://westus.asazure.windows.net/servers/myserver/models/AdventureWorks/

기준 URL을 사용하면, 다음 매개 변수에 따라 리소스 및 작업을 추가할 수 있습니다.

비동기 새로 고침 논리를 보여 주는 다이어그램.

s로 끝나는 모든 항목은 컬렉션입니다.
()로 끝나는 모든 항목은 함수입니다.
다른 모든 항목은 리소스/개체입니다.

예를 들어 새로 고침 컬렉션에서 POST 동사를 사용하여 새로 고침 작업을 수행할 수 있습니다.

https://westus.asazure.windows.net/servers/myserver/models/AdventureWorks/refreshes

인증

모든 호출은 Authorization 헤더의 유효한 Microsoft Entra ID(OAuth 2) 토큰으로 인증되어야 하며 다음 요구 사항을 충족해야 합니다.

토큰은 사용자 토큰 또는 애플리케이션 서비스 사용자여야 합니다.
토큰에는 대상 그룹이 정확히 https://*.asazure.windows.net으로 설정되어 있어야 합니다. *은 자리 표시자나 와일드카드가 아니며 대상 그룹은 하위 도메인으로 * 문자를 가지고 있어야 합니다. https://customersubdomain.asazure.windows.net과 같은 사용자 지정 대상 그룹은 지원되지 않습니다. 잘못된 대상 그룹을 지정하면 인증이 실패합니다.
사용자 또는 애플리케이션은 서버 또는 모델에서 요청된 호출을 수행하기 위한 충분한 권한이 있어야 합니다. 사용 권한 수준은 서버의 모델 또는 관리 그룹 내 역할에 의해 결정됩니다.

Important

현재 서버 관리자 역할 권한이 필요합니다.

POST /refreshes

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

모델에 대해 한 번에 하나의 새로 고침 작업만 허용됩니다. 현재 실행 중인 새로 고침 작업이 있으며 다른 작업이 제출되면 409 충돌 HTTP 상태 코드가 반환됩니다.

본문은 다음과 같을 수 있습니다.

{
    "Type": "Full",
    "CommitMode": "transactional",
    "MaxParallelism": 2,
    "RetryCount": 2,
    "Objects": [
        {
            "table": "DimCustomer",
            "partition": "DimCustomer"
        },
        {
            "table": "DimDate"
        }
    ]
}

매개 변수

매개 변수를 지정하지 않으면 기본값이 적용됩니다.

속성	형식	설명	기본값
`Type`	열거형	평가할 처리 유형입니다. 형식은 TMSL 새로 고침 명령 형식(`full`, `clearValues`, `calculate`, `dataOnly`, `automatic` 및 `defragment`)에 맞춰 정렬됩니다. `add` 형식은 지원되지 않습니다.	`automatic`
`CommitMode`	열거형	개체를 일괄 처리로 커밋할지 아니면 전체 작업이 완료될 때만 커밋할지 결정합니다. 모드로는 `transactional`, `partialBatch`가 있습니다.	`transactional`
`MaxParallelism`	정수	이 값은 처리 명령을 동시에 실행할 최대 스레드 수를 결정합니다. 이 값은 TMSL 시퀀스 명령에 설정될 수 있는 MaxParallelism 속성에 맞춰 정렬되거나 다른 메서드를 사용하여 정렬됩니다.	10
`RetryCount`	정수	실패하기 전에 작업이 다시 시도되는 횟수를 나타냅니다.	0
`Objects`	배열	처리해야 하는 개체의 배열입니다. 각 개체에 전체 테이블을 처리할 때는 "table"이, 파티션을 처리할 때는 "partition"이 포함됩니다. 개체를 지정하지 않으면 전체 모델이 새로 고쳐집니다.	전체 모델 처리

CommitMode에 대해 partialBatch를 지정하면 몇 시간이 걸릴 수 있는 대규모 데이터 세트의 초기 로드를 수행할 때 유용합니다. 하나 이상의 일괄 처리를 성공적으로 커밋한 후 새로 고침 작업이 실패하면, 성공적으로 커밋된 일괄 처리는 커밋된 상태로 유지됩니다(성공적으로 커밋된 일괄 처리는 롤백되지 않음).

참고 항목

작성 당시의 일괄 처리 크기는 MaxParallelism 값이지만, 이 값은 변경될 수 있습니다.

상태 값

상태 값	설명
`notStarted`	작업이 아직 시작되지 않았습니다.
`inProgress`	작업이 진행 중입니다.
`timedOut`	사용자가 지정한 시간 제한에 따라 작업 시간이 초과되었습니다.
`cancelled`	사용자 또는 시스템에서 작업을 취소했습니다.
`failed`	작업이 실패했습니다.
`succeeded`	작업이 성공했습니다.

GET /refreshes/<refreshId>

새로 고침 작업의 상태를 확인하려면 새로 고침 ID에 GET 동사를 사용합니다. 응답 본문의 예는 다음과 같습니다. 작업이 진행 중인 경우 상태에 inProgress가 반환됩니다.

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

GET /refreshes

모델에 대한 새로 고침 작업 내역 목록을 가져오려면 /refreshes 컬렉션에 GET 동사를 사용합니다. 응답 본문의 예는 다음과 같습니다.

참고 항목

작성 당시, 지난 30일 간의 새로 고침 작업이 저장되고 반환되지만, 이 값은 달라질 수 있습니다.

[
    {
        "refreshId": "1344a272-7893-4afa-a4b3-3fb87222fdac",
        "startTime": "2017-12-07T02:06:57.1838734Z",
        "endTime": "2017-12-07T02:07:00.4929675Z",
        "status": "succeeded"
    },
    {
        "refreshId": "474fc5a0-3d69-4c5d-adb4-8a846fa5580b",
        "startTime": "2017-12-07T01:05:54.157324Z",
        "endTime": "2017-12-07T01:05:57.353371Z",
        "status": "succeeded"
    }
]

DELETE /refreshes/<refreshId>

진행 중인 새로 고침 작업을 취소하려면 새로 고침 ID에 DELETE 동사를 사용합니다.

POST /sync

새로 고침 작업을 수행했으면, 쿼리 스케일 아웃을 위해 새 데이터를 복제본과 동기화해야 할 수 있습니다. 모델에 대한 동기화 작업을 수행하려면 /sync 함수에 POST 동사를 사용합니다. 응답의 Location 헤더에는 동기화 작업 ID가 포함됩니다.

GET /sync status

동기화 작업의 상태를 확인하려면 작업 ID를 매개 변수로 전달하여 GET 동사를 사용합니다. 응답 본문의 예는 다음과 같습니다.

{
    "operationId": "cd5e16c6-6d4e-4347-86a0-762bdf5b4875",
    "database": "AdventureWorks2",
    "UpdatedAt": "2017-12-09T02:44:26.18",
    "StartedAt": "2017-12-09T02:44:20.743",
    "syncstate": 2,
    "details": null
}

syncstate의 값:

0: 복제 중. 데이터베이스 파일을 대상 폴더에 복제하고 있습니다.
1: 리하이드레이션 중. 데이터베이스가 읽기 전용 서버 인스턴스에서 리하이드레이션되고 있습니다.
2: 완료됨. 동기화 작업이 완료되었습니다.
3: 실패. 동기화 작업이 실패했습니다.
4: 종료하는 중 동기화 작업이 완료되었으나 정리 단계를 수행하고 있습니다.

코드 샘플

다음은 GitHub의 RestApiSample을 시작하기 위한 C# 코드 샘플입니다.

코드 샘플을 사용하려면

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

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

서비스 사용자

자세한 내용은 서비스 주체 만들기 - Azure Portal 및 서버 관리자 역할에 서비스 주체 추가를 참조하고, 서비스 주체를 설정하여 Azure AS에서 필요한 권한을 할당하는 방법에 대한 단계를 따르세요. 그리고 다음 추가 단계를 완료합니다.

코드 예제에서 string authority = …를 찾은 후 common을 조직의 테넌트 ID로 바꿉니다.
ClientCredential 클래스가 자격 증명 개체를 인스턴스화하는 데 사용되도록 주석 처리하거나 주석 처리를 해제합니다. <App ID> 및 <App Key> 값이 안전한 방식으로 액세스되는지 확인하고, 그렇지 않은 경우 서비스 주체에 대해 인증서 기반 인증을 사용합니다.
예제를 실행합니다.

참고 항목

샘플
REST API

다음을 통해 공유

REST API를 사용한 비동기 새로 고침

기준 URL

인증

POST /refreshes

매개 변수

상태 값

GET /refreshes/<refreshId>

GET /refreshes

DELETE /refreshes/<refreshId>

POST /sync

GET /sync status

코드 샘플

코드 샘플을 사용하려면

서비스 사용자

참고 항목

피드백

추가 리소스