영어로 읽기

다음을 통해 공유


REST API를 사용하여 자산 만들기

이 자습서에서는 사용자가 Microsoft Purview 통합 카탈로그 검색하고 검색할 수 있는 Microsoft Purview 데이터 맵 자산을 만드는 방법을 알아봅니다.

참고

무료 버전의 Microsoft Purview를 사용하는 경우 데이터 큐레이터 역할 그룹의 사용자만 이러한 자산에 액세스할 수 있습니다.

서비스 주체 및 인증 토큰이 이미 있는 경우 REST API를 사용하여 자산을 만드는 단계로 직접 건너뛸 수 있습니다. 그렇지 않으면 이 가이드에 따라 REST API를 호출합니다.

필수 구성 요소

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

REST API 클라이언트가 Microsoft Purview에 액세스하여 엔터티를 만들려면 클라이언트에 서비스 주체(애플리케이션)와 Microsoft Purview가 인식하고 신뢰하도록 구성된 ID가 있어야 합니다.

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

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

  1. Azure 포털에 로그인합니다.

  2. 포털에서 Microsoft Entra ID 검색하고 선택합니다.

  3. Microsoft Entra ID 페이지의 왼쪽 창에서 앱 등록 선택합니다.

  4. 새 등록을 선택합니다.

  5. 애플리케이션 등록 페이지에서 다음을 수행합니다.

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

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

서비스 주체(애플리케이션)를 사용하려면 서비스 주체의 암호를 알고 있어야 합니다.

  1. 앱 등록 목록에서 서비스 주체(애플리케이션)를 선택합니다.
  2. 왼쪽 창에서 인증서 & 비밀을 선택합니다.
  3. 새 클라이언트 비밀을 선택합니다.
  4. 클라이언트 비밀 추가 페이지에서 설명을 입력하고 만료에서 만료 시간을 선택한 다음 추가 선택합니다.
  5. 클라이언트 비밀 페이지에서 새 비밀의 열에 있는 문자열은 암호입니다. 이 값을 저장합니다.

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

새 서비스 주체가 만들어지면 서비스 주체가 Microsoft Purview 계정에 액세스할 수 있도록 권한을 할당해야 합니다. 할당해야 하는 권한은 클래식 Microsoft Purview 환경 또는 새 Microsoft Purview 포털을 사용하는지에 따라 달라집니다.

사용 중인 환경에 대한 탭을 선택합니다.

  1. Microsoft Purview 거버넌스 포털로 이동합니다.

  2. 왼쪽 메뉴에서 데이터 맵을 선택합니다.

  3. 컬렉션을 선택합니다.

  4. 컬렉션 메뉴에서 루트 컬렉션을 선택합니다. 이 컬렉션은 목록의 최상위 컬렉션이며 Microsoft Purview 계정과 동일한 이름을 갖습니다.

    참고

    루트 컬렉션 대신 모든 하위 컬렉션에 서비스 주체 권한을 할당할 수도 있습니다. 그러나 모든 API는 해당 컬렉션(및 사용 권한을 상속하는 하위 컬렉션)으로 범위가 지정되며, 다른 컬렉션에 대해 API를 호출하려는 사용자는 오류가 발생합니다.

  5. 역할 할당 탭을 선택합니다.

  6. 데이터 큐레이터 역할을 이전에 만든 서비스 주체에 할당합니다. 자세한 단계는 Microsoft Purview 거버넌스 포털을 사용하여 Azure 역할 할당을 참조하세요.

권한을 할당한 후에는 인증 토큰을 수집해야 합니다.

  1. 다음 URL에 POST 요청을 보내 액세스 토큰을 가져옵니다.

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

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

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

    • client_id: Microsoft Entra ID 등록된 애플리케이션의 클라이언트 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가 서비스 주체에서 으로 설정되어 있는지 확인합니다.
    • POST 요청을 보내는 데 사용하는 애플리케이션에 대한 소프트웨어가 최신 상태인지 확인합니다.
  2. 위의 액세스 토큰을 사용하여 데이터 평면 API를 호출합니다.

REST API를 사용하여 자산 만들기

이제 토큰이 있고 인증할 수 있으므로 자산을 만들 준비가 되었습니다.

중요

요청 URL 엔드포인트는 사용 중인 Microsoft Purview 환경(클래식 Microsoft Purview 환경 또는 새 Microsoft Purview 포털)에 따라 달라집니다.

Azure 자산 만들기

다음은 Azure 리소스에 대한 엔터티를 만드는 데 사용할 수 있는 예제입니다. 이 예제에서는 Azure Storage 계정을 다루지만 다른 Azure 원본에 사용할 수 있습니다.

중요

Azure 리소스에 이 예제를 사용하려면 페이로드에서 다음 값을 바꿉니다.

  • typeName
  • 소유자
  • qualifiedName
  • 이름
  • 전문가 ID
  • 전문가 정보
  • 소유자 ID
  • 소유자 정보
  • Createdby
  • Updatedby

요청 URL: https://{accountName}.purview.azure.com/catalog/api/atlas/v2/entity

메서드: POST

인증: 이전 단계의 토큰을 전달자 토큰으로 사용합니다.

페이로드 예제:

{
  "referredEntities": {},
  "entity": {
    "typeName": "azure_storage_account",
    "attributes": {
      "owner": "ExampleOwner",
      "modifiedTime": 0,
      "createTime": 0,
      "qualifiedName": "https://exampleaccount.core.windows.net",
      "name": "ExampleStorageAccount",
      "description": null,
      "publicAccessLevel": null
    },
    "contacts": {
      "Expert": [
        {
          "id": "30435ff9-9b96-44af-a5a9-e05c8b1ae2d2",
          "info": "Example Expert Info"
        }
      ],
      "Owner": [
        {
          "id": " 30435ff9-9b96-44af-a5a9-e05c8b1ae2d2",
          "info": "Example Owner Info"
        }
      ]
    },
    "status": "ACTIVE",
    "createdBy": "ExampleCreator",
    "updatedBy": "ExampleUpdator",
    "version": 0
  }
}

다중 클라우드 자산 만들기

다음은 다중 클라우드 리소스에 대한 엔터티를 만드는 데 사용할 수 있는 예제입니다. 이 예제에서는 Snowflake 리소스를 만들지만 다른 소스에 사용할 수 있습니다.

중요

Azure 리소스에 이 예제를 사용하려면 페이로드에서 다음 값을 바꿉니다.

  • typeName
  • 소유자
  • qualifiedName
  • 이름
  • 전문가 ID
  • 전문가 정보
  • 소유자 ID
  • 소유자 정보
  • Createdby
  • Updatedby

요청 URL: https://{accountName}.purview.azure.com/catalog/api/atlas/v2/entity

메서드: POST

인증: 이전 단계의 토큰을 전달자 토큰으로 사용합니다.

페이로드 예제:

{
  "referredEntities": {},
  "entity": {
    "typeName": "snowflake_table",
    "attributes": {
      "owner": "ExampleOwner",
      "modifiedTime": 0,
      "createTime": 0,
      "qualifiedName": "snowflake://microsoft_partner.east-us-2.azure.snowflakecomputing.com/databases/AZUREPURVIEW_TESTDB/schemas/COMPANY/tables/PROJECT_INFO",
      "name": "PROJECT_INFO",
      "description": null,
      "type": "TABLE"
    },
    "contacts": {
      "Expert": [
        {
          "id": "30435ff9-9b96-44af-a5a9-e05c8b1ae2d2",
          "info": "Example Expert Info"
        }
      ],
      "Owner": [
        {
          "id": "4b27e65f-6a15-4925-a4ef-2e640445079b",
          "info": "Example Owner Info"
        }
      ]
    },
    "status": "ACTIVE",
    "createdBy": "ExampleCreator",
    "updatedBy": "ExampleUpdator",
    "version": 0
  }
}

다음 단계