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

[アーティクル]
08/23/2023

このチュートリアルでは、ユーザーが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] ページで、左側のウィンドウから [アプリの登録] を選択します。
[新規登録] を選択します。
[アプリケーションの登録] ページ で、次の手順を実行 します。
1. アプリケーションの名前 (サービスプリンシパル名) を入力します。
2. [この組織のディレクトリ内のアカウントのみ ( <テナントの名前>のみ - シングルテナント)] を選択します。
3. [ リダイレクト URI (省略可能)] で、[ Web ] を選択し、値を入力します。この値は有効なエンドポイントである必要はありません。 https://exampleURI.com やりましょう。
4. [登録] を選択します。
新しいサービスプリンシパルページで、後で保存する [表示名 ] と [アプリケーション (クライアント) ID] の 値をコピーします。

アプリケーション ID は、 client_id サンプルコードの値です。

サービスプリンシパル (アプリケーション) を使用するには、サービスプリンシパルのパスワードを知っている必要があります。

アプリの登録の一覧でサービスプリンシパル (アプリケーション) を選択します。
左側のウィンドウで [証明書 & シークレット ] を選択します。
[新しいクライアントシークレット] を選択します。
[ クライアントシークレットの追加] ページで 、[ 説明] を入力し、[ 有効期限] で有効期限を選択し、[ 追加] を選択します。
[ クライアントシークレット ] ページで、新しいシークレットの [値 ] 列の文字列がパスワードです。この値を保存します。

サービスプリンシパルを使用して認証を設定する

新しいサービスプリンシパルが作成されたら、サービスプリンシパルが Microsoft Purview アカウントにアクセスできるようにアクセス許可を割り当てる必要があります。割り当てる必要があるアクセス許可は、従来の 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 を呼び出すには、上記のアクセストークンを使用します。