중요
Microsoft Purview 통합 카탈로그 및 클래식 Microsoft Purview 데이터 거버넌스 기능(이전의 Azure Purview)은 사용 중지됩니다. Microsoft는 Microsoft Fabric에서 데이터 거버넌스 기능을 통합하고 있습니다. 더 이상 새 계정을 만들 수 없으며 기존 기능은 2027년 11월 12일까지 유지 관리 모드로 유지됩니다. 사용 중지 일정, 전환 지침 및 권장되는 다음 단계는 Microsoft Purview 데이터 거버넌스 사용 중지 공지를 참조하세요.
이 자습서에서는 Microsoft Purview 데이터 평면 API를 인증하는 방법을 알아봅니다. Microsoft Purview에 데이터를 제출하거나, 자동화된 프로세스의 일부로 Microsoft Purview를 포함하거나, Microsoft Purview에서 자체 사용자 환경을 빌드하려는 사용자는 누구나 API를 사용하여 그렇게 할 수 있습니다.
필수 구성 요소
- 시작하려면 기존 Microsoft Purview 계정이 있어야 합니다. 카탈로그가 없는 경우 Microsoft Purview 계정을 만들기 위한 빠른 시작을 참조하세요.
서비스 주체(애플리케이션) 만들기
API 클라이언트가 Microsoft Purview 데이터 평면 API에 액세스하려면 클라이언트에 서비스 주체(애플리케이션) 및 Microsoft Purview에서 인식하고 신뢰하도록 구성된 ID가 있어야 합니다. API를 호출하면 해당 서비스 주체의 ID가 권한 부여에 사용됩니다.
기존 서비스 주체(애플리케이션 ID)를 사용한 고객의 실패율이 높았습니다. 따라서 API를 호출하기 위한 새 서비스 주체를 만드는 것이 좋습니다.
새 서비스 주체를 만들려면:
Azure 포털에 로그인합니다.
포털에서 Microsoft Entra ID를 검색하고 선택합니다.
Microsoft Entra ID 페이지의 왼쪽 창에서 앱 등록을 선택합니다.
새 등록을 선택합니다.
애플리케이션 등록 페이지에서 다음을 수행합니다.
- 응용 프로그램의 이름 (서비스 사용자 이름)을 입력합니다.
-
이 애플리케이션을 사용하거나 이 API에 액세스할 수 있는 사용자는 누구입니까?에서 이 API를 사용할 것으로 예상되는 사용자 계정 유형을 선택합니다.
팁
현재 Microsoft Entra ID 테넌트의 사용자만 REST API를 사용할 것으로 예상되는 경우 이 조직 디렉터리의 계정만(<테넌트 이름>만 - 단일 테넌트)을 선택합니다. 그렇지 않으면 다른 옵션을 고려합니다.
-
리디렉션 URI(선택 사항)의 경우 웹을 선택하고 값을 입력합니다. 이 값이 유효한 끝점일 필요는 없습니다.
https://exampleURI.com할 것입니다. - 등록을 선택하세요.
새 서비스 주체 페이지에서 나중을 위해 저장할 표시 이름과 애플리케이션(클라이언트) ID 값을 복사합니다.
애플리케이션 ID는
client_id샘플 코드의 값입니다.
서비스 주체(응용 프로그램)를 사용하려면 다음을 통해 찾을 수 있는 서비스 주체의 암호를 알고 있어야 합니다.
Azure Portal에서 Microsoft Entra ID를 검색하여 선택한 다음, 왼쪽 창에서 앱 등록을 선택합니다.
목록에서 서비스 주체(애플리케이션)를 선택합니다.
왼쪽 창에서 인증서 & 비밀 을 선택합니다.
새 클라이언트 비밀을 선택합니다.
클라이언트 암호 추가 페이지에서 설명을 입력하고 만료 아래에서 만료 시간을 선택한 다음 추가를 선택합니다.
클라이언트 암호 페이지에서 새 암호의 값 열에 있는 문자열이 암호입니다. 이 값을 저장합니다.
서비스 주체를 사용하여 인증 설정
새 서비스 주체가 만들어지면 위에서 만든 서비스 주체에 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: Microsoft Entra ID에 등록되었으며 Microsoft Purview 계정의 데이터 평면 역할에 할당된 애플리케이션의 클라이언트 ID입니다.
- client_secret: 위의 애플리케이션에 대해 생성된 클라이언트 암호입니다.
- grant_type: 'client_credentials'여야 합니다.
- 리소스: 'https://purview.azure.net'
다음은 PowerShell의 샘플 POST 요청입니다.
$tenantID = "12a345bc-67d1-ef89-abcd-efg12345abcde"
$url = "https://login.microsoftonline.com/$tenantID/oauth2/token"
$params = @{ client_id = "00001111-aaaa-2222-bbbb-3333cccc4444"; 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>>"
}
팁
다음과 같은 오류 메시지가 나타나는 경우: 원본 간 토큰 사용은 '단일 페이지 애플리케이션' 클라이언트 유형에 대해서만 허용됩니다.
- 요청 헤더를 확인하고 요청에 'origin' 헤더 가 포함되어 있지 않은 지 확인합니다.
- 서비스 주체에서 리디렉션 URI가 웹 으로 설정되어 있는지 확인합니다.
- POST 요청을 보내는 데 사용하는 응용 프로그램에 대한 소프트웨어가 최신 상태인지 확인합니다.
위의 액세스 토큰을 사용하여 데이터 플레인 API를 호출합니다.