REST API を使用して資産を作成する
このチュートリアルでは、ユーザーがMicrosoft Purview データ カタログで検索および参照できる資産をMicrosoft Purview データ マップで作成する方法について説明します。
注意
無料版の Microsoft Purview を使用している場合は、データ キュレーター ロール グループのユーザーのみがこれらの資産にアクセスできます。
サービス プリンシパルと認証トークンが既にある場合は、 REST API を使用して資産を作成する手順に 直接進むことができます。それ以外の場合は、このガイドに従って REST API を呼び出します。
- Azure サブスクリプションをお持ちでない場合は、開始 する前に無料アカウントを作成 してください。
- 既存の Microsoft Purview アカウントが必要です。 そうでない場合は、organizationが無料バージョンの Microsoft Purview にアクセスできるかどうかをチェックするか、このクイック スタートを使用して Microsoft Purview アカウントを作成します。
REST API クライアントが Microsoft Purview にアクセスしてエンティティを作成するには、クライアントにサービス プリンシパル (アプリケーション)、および Microsoft Purview が認識し、信頼するように構成されている ID が必要です。
既存のサービス プリンシパル (アプリケーション ID) を使用しているお客様は、エラー率が高くなっています。 そのため、API を呼び出すための新しいサービス プリンシパルを作成することをお勧めします。
新しいサービス プリンシパルを作成するには:
Azure portal にサインインし
ポータルで、 Azure Active Directory を検索して選択します。
[Azure Active Directory] ページで、左側のウィンドウから [アプリの登録] を選択します。
[新規登録] を選択します。
[アプリケーションの登録] ページ で、次の手順を実行 します。
- アプリケーションの 名前 (サービス プリンシパル名) を入力します。
- [この組織のディレクトリ内のアカウントのみ ( <テナントの名前>のみ - シングル テナント)] を選択します。
- [ リダイレクト URI (省略可能)] で、[ Web ] を選択し、値を入力します。 この値は有効なエンドポイントである必要はありません。
https://exampleURI.com
やりましょう。 - [登録] を選択します。
新しいサービス プリンシパル ページで、後で保存する [表示名 ] と [アプリケーション (クライアント) ID] の 値をコピーします。
アプリケーション ID は、
client_id
サンプル コードの値です。
サービス プリンシパル (アプリケーション) を使用するには、サービス プリンシパルのパスワードを知っている必要があります。
- アプリの登録の一覧でサービス プリンシパル (アプリケーション) を選択します。
- 左側のウィンドウで [証明書 & シークレット ] を選択します。
- [新しいクライアント シークレット] を選択します。
- [ クライアント シークレットの追加] ページで 、[ 説明] を入力し、[ 有効期限] で有効期限を選択し、[ 追加] を選択します。
- [ クライアント シークレット ] ページで、新しいシークレットの [値 ] 列の文字列がパスワードです。 この値を保存します。
新しいサービス プリンシパルが作成されたら、サービス プリンシパルが Microsoft Purview アカウントにアクセスできるようにアクセス許可を割り当てる必要があります。 割り当てる必要があるアクセス許可は、 従来の Microsoft Purview エクスペリエンス と 新しい Microsoft Purview ポータルのどちらを使用しているかによって異なります。
使用しているエクスペリエンスのタブを選択します。
Microsoft Purview ガバナンス ポータルに移動します。
左側のメニューで [データ マップ] を選択します。
[コレクション] を選択します。
[コレクション] メニューでルート コレクションを選択します。 これは一覧の最上位のコレクションであり、Microsoft Purview アカウントと同じ名前になります。
注意
ルート コレクションではなく、任意のサブコレクションにサービス プリンシパルのアクセス許可を割り当てることもできます。 ただし、すべての API はそのコレクション (およびアクセス許可を継承するサブコレクション) にスコープが設定され、別のコレクションの API を呼び出そうとしているユーザーはエラーを受け取ります。
[ ロールの割り当て ] タブを選択します。
前に作成したサービス プリンシパルにデータ キュレーター ロールを割り当てます。 詳細な手順については、「 Microsoft Purview ガバナンス ポータルを使用して Azure ロールを割り当てる」を参照してください。
アクセス許可を割り当てた後、認証トークンを収集する必要があります。
アクセス トークンを取得するには、次の URL に POST 要求を送信します。
https://login.microsoftonline.com/{your-tenant-id}/oauth2/token
テナント ID は、Azure portalで [テナントのプロパティ] を検索することで確認できます。 ID は、テナントのプロパティ ページで使用できます。
次のパラメーターを上記の URL に渡す必要があります。
- client_id: Azure Active Directory に登録され、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 = "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>>" }
ヒント
というエラー メッセージが表示される場合: クロスオリジン トークンの引き換えは、"シングルページ アプリケーション" クライアントタイプに対してのみ許可されます。
- 要求ヘッダーを確認し、要求に 'origin' ヘッダー が含まれていない ことを確認します。
- リダイレクト URI がサービス プリンシパルの Web に設定されていることを確認します。
- Postman のようなアプリケーションを使用している場合は、ソフトウェアが最新の状態であることを確認してください。
データ プレーン API を呼び出すには、上記のアクセス トークンを使用します。
トークンを取得し、認証できるようになったので、資産を作成する準備ができました。
重要
要求 URL エンドポイントは、使用している Microsoft Purview エクスペリエンス (従来の Microsoft Purview エクスペリエンスまたは新しい Microsoft Purview ポータル) によって異なります
Azure リソースのエンティティを作成するために使用できる例を次に示します。 この例では、Azure Storage アカウントについて説明しますが、他の Azure ソースで使用できます。
重要
Azure リソースにこの例を使用するには、ペイロード内の次の値を置き換えます。
- Typename
- Owner
- qualifiedName
- name
- エキスパート ID
- エキスパート情報
- 所有者 ID
- 所有者情報
- Createdby
- 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
- 所有者情報
- Createdby
- 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
}
}