REST API を使用して資産を作成する

重要

Microsoft Purview データ ガバナンス機能のみの廃止

Microsoft Purview 統合カタログと従来の Microsoft Purview データ ガバナンス機能 (旧称 Azure Purview) は廃止されます。 Microsoft Purview 全体は廃止されません。 Microsoft Purview のデータ セキュリティとコンプライアンス機能は、この発表の影響を受けず、Microsoft は引き続き投資します。

Microsoft は、Microsoft Fabric のデータ ガバナンス 機能を統合しています。 新しい Microsoft Purview データ ガバナンス アカウントは作成できなくなり、既存のデータ ガバナンス機能は 2027 年 11 月 12 日までメンテナンス モードのままになります。

廃止のタイムライン、移行ガイダンス、推奨される次の手順については、 Microsoft Purview データ ガバナンスの廃止のお知らせを参照してください。

このチュートリアルでは、ユーザーが Microsoft Purview 統合カタログで検索および参照できるアセットを Microsoft Purview データ マップで作成する方法について説明します。

注:

無料バージョンの Microsoft Purview を使用している場合、データキュレーターの役割グループ内のユーザーのみがこれらのアセットにアクセスできます。

既にサービス プリンシパルと認証トークンがある場合は、直接手順に進み、 REST API を使用してアセットを作成できます。 それ以外の場合は、このガイドに従って REST API を呼び出します。

前提条件

サービス プリンシパル (アプリケーション) の作成

REST API クライアントが Microsoft Purview にアクセスしてエンティティを作成するには、クライアントにサービス プリンシパル (アプリケーション) と、Microsoft Purview が認識し、信頼するように構成されている ID が必要です。

既存のサービス プリンシパル (アプリケーション ID) を使用していたお客様は、失敗率が高くなっています。 そのため、API を呼び出すための新しいサービス プリンシパルを作成することをお勧めします。

新しいサービス プリンシパルを作成するには、次の手順を実行します。

  1. Azure portal にサインインし

  2. ポータルから、 Microsoft Entra ID を検索して選択します。

  3. [Microsoft Entra ID] ページで、左側のウィンドウから [アプリの登録] を選択します。

  4. [新規登録] を選択します。

  5. [ アプリケーションの登録 ] ページで、次の操作を行います。

    1. アプリケーション の名前 (サービス プリンシパル名) を入力します。
    2. [ この組織ディレクトリ内のアカウントのみ] (<テナントの名前> のみ - シングル テナント) を選択します。
    3. [ リダイレクト URI (省略可能)] で、[ Web ] を選択し、値を入力します。 この値は、有効なエンドポイントである必要はありません。 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

    テナント ID は、Azure portal で「 テナント プロパティ 」を検索して確認できます。 ID は、テナントのプロパティ ページで入手できます。

    上記の URL には、次のパラメーターを渡す必要があります。

    • client_id: Microsoft Entra ID に登録され、Microsoft Purview アカウントのデータ プレーン ロールに割り当てられているアプリケーションのクライアント ID。
    • 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 = "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 がサービス プリンシパルの Web に設定されていることを確認します。
    • POST 要求の送信に使用しているアプリケーションのソフトウェアが最新であることを確認してください。
  2. 上記のアクセス トークンを使用して、データ プレーン API を呼び出します。

REST API を使用して資産を作成する

トークンを取得して認証できるようになったので、アセットを作成する準備が整いました。

重要

要求 URL エンドポイントは、使用している Microsoft Purview エクスペリエンス (従来の Microsoft Purview エクスペリエンスまたは新しい Microsoft Purview ポータル) によって異なります

Azure 資産を作成する

Azure リソースのエンティティの作成に使用できる例を次に示します。 この例では Azure Storage アカウントについて説明しますが、これを他の任意の Azure ソースに使用できます。

重要

Azure リソースにこの例を使用するには、ペイロード内の次の値を置き換えます。

  • typeName
  • Owner
  • qualifiedName
  • name
  • エキスパート ID
  • エキスパート情報
  • 所有者 ID
  • 所有者情報
  • 作成者
  • Updatedby

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

方法: 投稿

認証: 前の手順のトークンをベアラー トークンとして使用します。

ペイロードの例:

{
  "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
  • Owner
  • qualifiedName
  • name
  • type
  • エキスパート ID
  • エキスパート情報
  • 所有者 ID
  • 所有者情報
  • 作成者
  • Updatedby

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

方法: 投稿

認証: 前の手順のトークンをベアラー トークンとして使用します。

ペイロードの例:

{
  "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
  }
}

次の手順