チュートリアル: API の認証

[アーティクル]
11/13/2024

このチュートリアルでは、 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] ページで、左側のウィンドウから [アプリの登録] を選択します。
[新規登録] を選択します。
[アプリケーションの登録] ページ で、次の手順を実行 します。
1. アプリケーションの名前 (サービスプリンシパル名) を入力します。
2. [ このアプリケーションを使用できるユーザーまたはこの API にアクセスできるユーザー] で、この API を使用するユーザーアカウントの種類を選択します。
  
  ヒント
  
  現在のMicrosoft Entra ID テナントのユーザーのみが REST API を使用することを想定している場合は、[この組織のディレクトリ内のアカウントのみ (<テナントの名前>単一テナントのみ)] を選択します。それ以外の場合は、他のオプションを検討してください。
3. [ リダイレクト URI (省略可能)] で、[ Web ] を選択し、値を入力します。この値は有効なエンドポイントである必要はありません。 https://exampleURI.com やりましょう。
4. [登録] を選択します。
新しいサービスプリンシパルページで、後で保存する [表示名 ] と [アプリケーション (クライアント) 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 を呼び出すには、上記のアクセストークンを使用します。

次の手順

データソースの管理 Microsoft Purview データプレーン REST API

次の方法で共有

チュートリアル: API の認証

前提条件

サービスプリンシパル (アプリケーション) を作成する

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

トークンを取得する

次の手順

フィードバック

その他のリソース

次の方法で共有

チュートリアル: API の認証

前提条件

サービス プリンシパル (アプリケーション) を作成する

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

トークンを取得する

次の手順

フィードバック

その他のリソース

サービスプリンシパル (アプリケーション) を作成する

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