자습서: REST API 사용

아티클
08/23/2023

이 자습서에서는 Microsoft Purview 데이터 평면 REST API를 사용하는 방법을 알아봅니다. Microsoft Purview에 데이터를 제출하거나, 자동화된 프로세스의 일부로 Microsoft Purview를 포함하거나, Microsoft Purview에서 고유한 사용자 환경을 빌드하려는 사용자는 REST API를 사용하여 이 작업을 수행할 수 있습니다.

Azure 구독이 없는 경우 시작하기 전에 체험 계정을 만듭니 다.

필수 구성 요소

시작하려면 기존 Microsoft Purview 계정이 있어야 합니다. 카탈로그가 없는 경우 Microsoft Purview 계정을 만들기 위한 빠른 시작을 참조하세요.

서비스 주체 만들기(애플리케이션)

REST API 클라이언트가 Microsoft Purview 데이터 평면 API에 액세스하려면 클라이언트에 서비스 주체(애플리케이션)와 Microsoft Purview가 인식하고 신뢰하도록 구성된 ID가 있어야 합니다. REST API를 호출하면 해당 서비스 주체의 ID가 권한 부여에 사용됩니다.

기존 서비스 주체(애플리케이션 ID)를 사용한 고객은 높은 실패율을 보였습니다. 따라서 API를 호출하기 위한 새 서비스 주체를 만드는 것이 좋습니다.

새 서비스 주체를 만들려면 다음을 수행합니다.

Azure 포털에 로그인합니다.
포털에서 Azure Active Directory를 검색하여 선택합니다.
Azure Active Directory 페이지의 왼쪽 창에서 앱 등록 선택합니다.
새 등록을 선택합니다.
애플리케이션 등록 페이지에서 다음을 수행합니다.
1. 애플리케이션의 이름 (서비스 주체 이름)을 입력합니다.
2. 이 조직 디렉터리에서만 계정을 선택합니다(<테넌트의 이름>만 - 단일 테넌트).
3. 리디렉션 URI(선택 사항)에 웹을 선택하고 값을 입력합니다. 이 값은 유효한 엔드포인트일 필요는 없습니다. https://exampleURI.com 알았어.
4. 등록을 선택하세요.
새 서비스 주체 페이지에서 표시 이름 및 애플리케이션(클라이언트) ID 의 값을 복사하여 나중에 저장할 수 있습니다.

애플리케이션 ID는 샘플 코드의 값입니다 client_id .

서비스 주체(애플리케이션)를 사용하려면 다음을 통해 찾을 수 있는 서비스 주체의 암호를 알아야 합니다.

Azure Portal Azure Active Directory를 검색하여 선택한 다음, 왼쪽 창에서 앱 등록 선택합니다.
목록에서 서비스 주체(애플리케이션)를 선택합니다.
왼쪽 창에서 인증서 & 비밀을 선택합니다.
새 클라이언트 비밀을 선택합니다.
클라이언트 비밀 추가 페이지에서 설명을 입력하고 만료에서 만료 시간을 선택한 다음 추가를 선택합니다.

클라이언트 비밀 페이지에서 새 비밀의 값 열에 있는 문자열은 암호입니다. 이 값을 저장합니다.

서비스 주체를 사용하여 인증 설정

새 서비스 주체가 만들어지면 purview 계정의 데이터 평면 역할을 위에서 만든 서비스 주체에 할당해야 합니다. 아래 단계에 따라 서비스 주체와 Purview 계정 간에 트러스트를 설정하는 올바른 역할을 할당합니다.

Microsoft Purview 거버넌스 포털로 이동합니다.
왼쪽 메뉴에서 데이터 맵을 선택합니다.
컬렉션을 선택합니다.
컬렉션 메뉴에서 루트 컬렉션을 선택합니다. 이 컬렉션은 목록의 최상위 컬렉션이며 Microsoft Purview 계정과 동일한 이름을 갖습니다.

참고

루트 컬렉션 대신 모든 하위 컬렉션에 서비스 주체 권한을 할당할 수도 있습니다. 그러나 모든 API는 해당 컬렉션(및 사용 권한을 상속하는 하위 컬렉션)으로 범위가 지정되며, 다른 컬렉션에 대해 API를 호출하려는 사용자는 오류가 발생합니다.
역할 할당 탭을 선택합니다.
Microsoft Purview의 다양한 데이터 평면에 액세스하기 위해 이전에 만든 서비스 주체에 다음 역할을 할당합니다. 자세한 단계는 Microsoft Purview 거버넌스 포털을 사용하여 Azure 역할 할당을 참조하세요.
- 카탈로그 데이터 평면에 액세스하는 데이터 큐레이터 역할입니다.
- 데이터 검사 데이터 평면에 액세스하는 데이터 원본 관리자 역할입니다.
- 계정 데이터 평면 및 메타데이터 정책 데이터 평면에 액세스하는 컬렉션 관리 역할입니다.
- DevOps 정책 API에 액세스하는 정책 작성자 역할
참고

컬렉션 관리 역할의 멤버만 Microsoft Purview에서 데이터 평면 역할을 할당할 수 있습니다. Microsoft Purview 역할에 대한 자세한 내용은 Microsoft Purview의 Access Control 참조하세요.

토큰 가져오기

다음 URL로 POST 요청을 보내 액세스 토큰을 가져올 수 있습니다.

https://login.microsoftonline.com/{your-tenant-id}/oauth2/token

Azure Portal 테넌트 속성을 검색하여 테넌트 ID를 찾을 수 있습니다. ID는 테넌트 속성 페이지에서 사용할 수 있습니다.

다음 매개 변수를 위의 URL로 전달해야 합니다.

client_id: Azure Active Directory에 등록된 애플리케이션의 클라이언트 ID이며 Microsoft Purview 계정에 대한 데이터 평면 역할에 할당됩니다.
client_secret: 위의 애플리케이션에 대해 만들어진 클라이언트 암호입니다.
grant_type: 'client_credentials'이어야 합니다.
resource: 'https://purview.azure.net'

PowerShell의 샘플 POST 요청은 다음과 같습니다.

$tenantID = "12a345bc-67d1-ef89-abcd-efg12345abcde"

$url = "https://login.microsoftonline.com/$tenantID/oauth2/token"
$params = @{ client_id = "a1234bcd-5678-9012-abcd-abcd1234abcd"; client_secret = "abcd~a1234bcd56789012abcdabcd1234abcd"; grant_type = "client_credentials"; resource = ‘https://purview.azure.net’ }

Invoke-WebRequest $url -Method Post -Body $params -UseBasicParsing | ConvertFrom-Json

샘플 응답 토큰:

    {
        "token_type": "Bearer",
        "expires_in": "86399",
        "ext_expires_in": "86399",
        "expires_on": "1621038348",
        "not_before": "1620951648",
        "resource": "https://purview.azure.net",
        "access_token": "<<access token>>"
    }

팁

다음과 같은 오류 메시지가 표시되면 '단일 페이지 애플리케이션' 클라이언트 유형에 대해서만 원본 간 토큰 사용이 허용됩니다.

요청 헤더를 확인하고 요청에 '원본' 헤더가 포함되어 있지 않은지 확인합니다.
리디렉션 URI가 서비스 주체에서 웹 으로 설정되어 있는지 확인합니다.
Postman과 같은 애플리케이션을 사용하는 경우 소프트웨어가 최신 상태인지 확인합니다.

위의 액세스 토큰을 사용하여 데이터 평면 API를 호출합니다.

다음 단계

Microsoft Purview 데이터 평면 REST API 데이터 원본 관리