REST API を使用して資産を作成する
[アーティクル] 2023/08/23
2 人の共同作成者
フィードバック
この記事の内容
前提条件
サービス プリンシパル (アプリケーション) を作成する
サービス プリンシパルを使用して認証を設定する
REST API を使用して資産を作成する
次の手順
このチュートリアルでは、ユーザーがMicrosoft Purview データ カタログで検索および参照できる資産をMicrosoft Purview データ マップで作成する方法について説明します。
サービス プリンシパルと認証トークンが既にある場合は、 REST API を使用して資産を作成する手順に 直接進むことができます。それ以外の場合は、このガイドに従って REST API を呼び出します。
サービス プリンシパル (アプリケーション) を作成する
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 を呼び出すには、上記のアクセス トークンを使用します。
トークンを取得し、認証できるようになったので、資産を作成する準備ができました。
Azure リソースのエンティティを作成するために使用できる例を次に示します。
この例では、Azure Storage アカウントについて説明しますが、他の Azure ソースで使用できます。
重要
Azure リソースにこの例を使用するには、ペイロード内の次の値を置き換えます。
Typename
Owner
qualifiedName
name
エキスパート ID
エキスパート情報
所有者 ID
所有者情報
Createdby
Updatedby
要求 URL: https://{accountName}.purview.azure.com/catalog/api/atlas/v2/entity
要求 URL: https://api.purview-service.microsoft.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
要求 URL: https://api.purview-service.microsoft.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
}
}