チュートリアル: API の認証
このチュートリアルでは、 Microsoft Purview データ プレーン API の認証方法について説明します。 Microsoft Purview にデータを送信したり、自動プロセスの一部として Microsoft Purview を含めたり、Microsoft Purview で独自のユーザー エクスペリエンスを構築したりする場合は、API を使用してこれを行うことができます。
- 開始するには、既存の Microsoft Purview アカウントが必要です。 カタログがない場合は、 Microsoft Purview アカウントを作成するためのクイック スタートを参照してください。
API クライアントが Microsoft Purview データ プレーン API にアクセスするには、クライアントにサービス プリンシパル (アプリケーション)、および Microsoft Purview が認識し、信頼するように構成されている ID が必要です。 API 呼び出しを行うと、そのサービス プリンシパルの ID が承認に使用されます。
既存のサービス プリンシパル (アプリケーション ID) を使用しているお客様は、エラー率が高くなっています。 そのため、API を呼び出すための新しいサービス プリンシパルを作成することをお勧めします。
新しいサービス プリンシパルを作成するには:
Azure portal にサインインし
ポータルで、Microsoft Entra IDを検索して選択します。
[Microsoft Entra ID] ページで、左側のウィンドウから [アプリの登録] を選択します。
[新規登録] を選択します。
[アプリケーションの登録] ページ で、次の手順を実行 します。
- アプリケーションの 名前 (サービス プリンシパル名) を入力します。
- [ このアプリケーションを使用できるユーザーまたはこの API にアクセスできるユーザー] で、この API を使用するユーザー アカウントの種類を選択します。
ヒント
現在のMicrosoft Entra ID テナントのユーザーのみが REST API を使用することを想定している場合は、[この組織のディレクトリ内のアカウントのみ (<テナントの名前>単一テナントのみ)] を選択します。 それ以外の場合は、他のオプションを検討してください。
- [ リダイレクト URI (省略可能)] で、[ Web ] を選択し、値を入力します。 この値は有効なエンドポイントである必要はありません。
https://exampleURI.com
やりましょう。 - [登録] を選択します。
新しいサービス プリンシパル ページで、後で保存する [表示名 ] と [アプリケーション (クライアント) ID] の 値をコピーします。
アプリケーション ID は、サンプル コードの
client_id
値です。
サービス プリンシパル (アプリケーション) を使用するには、次の方法で検出できるサービス プリンシパルのパスワードを知っている必要があります。
Azure portalで、Microsoft Entra IDを検索して選択し、左側のウィンドウから [アプリの登録] を選択します。
一覧からサービス プリンシパル (アプリケーション) を選択します。
左側のウィンドウから [ 証明書 & シークレット ] を選択します。
[新しいクライアント シークレット] を選択します。
[ クライアント シークレットの追加] ページで 、[ 説明] を入力し、[ 有効期限] で有効期限を選択し、[ 追加] を選択します。
[ クライアント シークレット ] ページで、新しいシークレットの [値 ] 列の文字列がパスワードです。 この値を保存します。
新しいサービス プリンシパルが作成されたら、purview アカウントのデータ プレーン ロールを上記で作成したサービス プリンシパルに割り当てる必要があります。 サービス プリンシパルと Purview アカウントの間で信頼を確立するための正しいロールを割り当てるには、次の手順に従います。
Microsoft Purview ガバナンス ポータルに移動します。
左側のメニューで [データ マップ] を選択します。
[コレクション] を選択します。
[コレクション] メニューでルート コレクションを選択します。 これはリストの最上位のコレクションであり、Microsoft Purview アカウントと同じ名前になります。
注意
ルート コレクションではなく、任意のサブコレクションにサービス プリンシパルのアクセス許可を割り当てることもできます。 ただし、すべての API はそのコレクション (およびアクセス許可を継承するサブコレクション) にスコープが設定され、別のコレクションの API を呼び出そうとしているユーザーはエラーを受け取ります。
[ ロールの割り当て ] タブを選択します。
以前に作成したサービス プリンシパルに次のロールを割り当てて、Microsoft Purview のさまざまなデータ プレーンにアクセスします。 詳細な手順については、「 Microsoft Purview ガバナンス ポータルを使用して Azure ロールを割り当てる」を参照してください。
- カタログ データ プレーンにアクセスするためのデータ キュレーター ロール。
- スキャン データ プレーンにアクセスするためのデータ ソース管理者ロール。
- コレクション 管理アカウント データ プレーンとメタデータ ポリシー データ プレーンにアクセスするためのロール。
- DevOps ポリシー API にアクセスするためのポリシー作成者ロール
注意
Microsoft Purview でデータ プレーン ロールを割り当てることができるのは、Collection 管理 ロールのメンバーのみです。 Microsoft Purview ロールの詳細については、「Microsoft Purview のAccess Control」を参照してください。
POST 要求を次の URL に送信して、アクセス トークンを取得できます。
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 = "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 に設定されていることを確認します。
- POST 要求を送信するために使用しているアプリケーションのソフトウェアが最新であることを確認します。
データ プレーン API を呼び出すには、上記のアクセス トークンを使用します。