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

  • 아티클

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을 사용하면, 다음 매개 변수에 따라 리소스 및 작업을 추가할 수 있습니다.

Diagram that shows asynchronous refresh logic.

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

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

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

인증

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

  • 토큰은 사용자 토큰 또는 애플리케이션 서비스 사용자여야 합니다.

  • 토큰에는 올바른 대상이 https://*.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 형식은 지원되지 않습니다. 자동
CommitMode 열거형 개체가 일괄로 커밋될지 또는 완료될 때만 커밋될지를 결정합니다. 모드에는 default, 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# 코드 샘플입니다.

코드 샘플을 사용하려면

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

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

서비스 사용자

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

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

참고 항목

샘플
REST API