次の方法で共有

Microsoft Purview - REST API を使用してカスタム系列を構築する

  • [アーティクル]

この記事では、Microsoft Purview データ カタログの REST API を使用してデータ系列エントリを作成する手順について説明します。 Microsoft Purview で自動的に生成された系列が不完全または不足しているシナリオでは、系列を Microsoft Purview ポータルで手動で 作成するか、REST API を使用してカスタム構築できます。 この記事では、手動系列の既知の制限を克服し、より多くのオプションを提供できる REST API の使用に焦点を当てます。

背景

データセット間の系列を表示する機能は、Microsoft Purview の重要なプラットフォーム機能の 1 つです。 Data Factory、Data Share、Power BI などのシステムは、データの移動に伴う系列をキャプチャします。 特定の状況では、Microsoft Purview の自動生成された系列は、実用的な視覚化とエンタープライズ レポートのために不完全または欠落しています。 このようなシナリオでは、カスタム系列レポートは Apache Atlas フックと REST API によってサポートされます。

REST API を使用してカスタム系列を構築すると、次の記事で説明されているように、手動系列の制限を克服できます。

この記事の残りの部分では、Microsoft Purview REST API を使用して Microsoft Purview でカスタム系列を構築してレポートする方法について説明します。

前提条件

シナリオ

カスタム系列の構築が必要になる場合は、次の 2 つのユース ケースがあります。

A. 作成された新しいエンティティを作成し、それらを系列にリンクする

B. 既存のエンティティまたは系列を別の既存のエンティティまたは系列にリンクする

たとえば、エンティティ A & B の間で系列を報告する必要がありますが、A & B は現在存在しません。

エンティティ A & B を作成するには、Microsoft Purview REST API: Entity - Bulk Create or Update - REST API を呼び出します

POST https://{accountname}.purview.azure.com/datamap/api/atlas/v2/entity/bulk?api-version=2023-09-01

sample_entity_json = '{"entity": {"status": "ACTIVE","version": 0,"name": ENTITY_A"}.......{"entity": ........}}'
#Send POST JSON containing entities to be created
CreateOrUpdateEntitesUrl = 'https://<purview_account_name>.purview.azure.com/datamap/api/atlas/v2/entity/bulk'
EntitiesResponse = requests.post(CreateOrUpdateEntitesUrl, json = json.loads(sample_entity_json) ,headers=headers)
entitiesRes = json.loads(EntitiesResponse.text)

API 応答 "201 Created" は、エンティティが正常に作成され、それぞれの GUID が出力 JSON に含まれていることを示します。

エンティティ A & B が作成されたら、手順 B に移動して、同じ REST API を使用して系列チェーン内のエンティティをリンクします。

  • リンクするエンティティの数が時間やリソースを集中的に消費しない場合 (たとえば、20 から 30 個未満のエンティティなど)、Microsoft Purview ポータルで系列を手動で接続できます。 手動で系列接続を作成する手順については、手動の系列ユーザー ガイドに従います。
  • 大量の系列接続を行う場合は、プロセスを自動化する必要があります。または、Microsoft Purview ポータルを使用した手動系列が実現できない場合は、カスタム系列をリンクして構築する API プロセスに進みます。

カスタム系列 JSON ペイロード:

次に示すように、ペイロードを使用して POST /entity/bulkEntity - Bulk Create または Update - REST API を実行します。

POST https://{accountname}.purview.azure.com/datamap/api/atlas/v2/entity/bulk?api-version=2023-09-01

sample_entity_json = '{
  "entities": [
    {
      "status": "ACTIVE",
      "version": 1,
      "typeName": "Process",
      "attributes": {
        "inputs": [
          {
            "guid": "24558fd8-9cdc-47de-9310-56a58108bab0",
            “guid”: “27163581-9aca-212a-782a-213612639abc”
          }
        ],
        "outputs": [
          {
            "guid": "e33c694a-2c4f-4cae-8c27-06f6f6f60000"
          }
        ],
        "qualifiedName": "cassandra://query",
        "name": "query"
      }
    }
  ]
}'

#In this code snippet, we send the JSON as POST request containing the two GUIDs as input and "output" GUID as output. This creates lineage with 2 directional inputs and 1 directional output.
#Note: using the same API and SDK code you can create lineage with any number of inputs, any number of processes in between, any number of typedefs and any number of outputs.
#The API/SDK method is the most flexible and versatile menthod of creating lineage.
 
CreateLineageEntitesUrl = 'https://<purview_account_name>.purview.azure.com/datamap/api/atlas/v2/entity/bulk'
EntitiesResponse = requests.post(CreateLineageEntitesUrl, json = json.loads(sample_entity_json),headers=headers)
entitiesRes = json.loads(EntitiesResponse.text)

この JSON ペイロードは、カスタム系列を作成します。 これは、"入力" JSON で GUID が提供されている既存の資産に対して機能します。 例: "guid": "24558fd8-9cdc-47de-9310-56a58108bab0" と "27163581-9aca-212a-782a-213612639 abc" は系列の方向入力を指し、"guid": "e33c694a-2c4f-4cae-8c27-06f6f6f60000" は、Purview によって自動的にスキャンされた既存の資産であった系列の方向出力を指します。 2 つの資産の間に系列を作成しました。

注:

資産がまだ存在しない場合は、系列リレーションシップを作成する前に、この手順の前に一括エンティティ作成 API を実行して、それらのエンティティを作成する必要があります。 POST /entity/bulk API と Python コード スニペットを使用した一括エンティティ作成プロセスについては、 手順 A で説明します。

シナリオの結果

API 応答 "201 Created" は、系列グラフリンケージの作成が成功し、作成された GUID が出力 JSON に含まれていることを示します。 系列は、Microsoft Purview ポータルに表示されます。

  • シナリオ A: API を介して作成された資産からのカスタム構築系列:

    シナリオ A: API を介して作成されたアセットからのカスタム構築系列を示すスクリーンショット。

  • シナリオ B: API を介してリンクされた既存の資産からのカスタム構築系列。

    注:

    系列が既存のエンティティから作成されている場合は、既存の系列グラフはそのまま残り、新しいリンケージが作成され、追加で表示されることを確認します。

    シナリオ B: API を介してリンクされた既存の資産からのカスタム構築系列を示すスクリーンショット。