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

重要

Microsoft Purview データ ガバナンス機能のみの廃止

Microsoft Purview 統合カタログと従来の Microsoft Purview データ ガバナンス機能 (旧称 Azure Purview) は廃止されます。 Microsoft Purview 全体は廃止されません。 Microsoft Purview のデータ セキュリティとコンプライアンス機能は、この発表の影響を受けず、Microsoft は引き続き投資します。

Microsoft は、Microsoft Fabric のデータ ガバナンス 機能を統合しています。 新しい Microsoft Purview データ ガバナンス アカウントは作成できなくなり、既存のデータ ガバナンス機能は 2027 年 11 月 12 日までメンテナンス モードのままになります。

廃止のタイムライン、移行ガイダンス、推奨される次の手順については、 Microsoft Purview データ ガバナンスの廃止のお知らせを参照してください。

このチュートリアルでは、 Microsoft Purview データ プレーン API の認証方法について説明します。 Microsoft Purview にデータを送信したり、自動プロセスの一部として Microsoft Purview を含めたり、Microsoft Purview で独自のユーザー エクスペリエンスを構築したりするユーザーは、誰でも API を使用してそうすることができます。

前提条件

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

API クライアントが Microsoft Purview データ プレーン API にアクセスするには、クライアントにはサービス プリンシパル (アプリケーション) と、Microsoft Purview が認識して信頼するように構成されている ID が必要です。 API 呼び出しを行うと、そのサービス プリンシパルの ID が承認に使用されます。

既存のサービス プリンシパル (アプリケーション ID) を使用していたお客様は、失敗率が高くなっています。 そのため、API を呼び出すための新しいサービス プリンシパルを作成することをお勧めします。

新しいサービス プリンシパルを作成するには、次の手順を実行します。

  1. Azure portal にサインインし

  2. ポータルから、 Microsoft Entra ID を検索して選択します。

  3. [Microsoft Entra ID] ページで、左側のウィンドウから [アプリの登録] を選択します。

  4. [新規登録] を選択します。

  5. [ アプリケーションの登録 ] ページで、次の操作を行います。

    1. アプリケーション の名前 (サービス プリンシパル名) を入力します。
    2. [ このアプリケーションを使用したり、この API にアクセスしたりできるユーザー] で、この API を使用する予定のユーザー アカウントの種類を選択します。

      ヒント

      現在の Microsoft Entra ID テナントのユーザーのみが REST API を使用することを想定している場合は、[ この組織ディレクトリ内のアカウントのみ (<テナントの名前> のみ - シングル テナント)] を選択します。 それ以外の場合は、他のオプションを検討してください。

    3. [ リダイレクト URI (省略可能)] で、[ Web ] を選択し、値を入力します。 この値は、有効なエンドポイントである必要はありません。 https://exampleURI.com できます。
    4. [登録] を選択します。

    上記のオプションが入力された、アプリケーションの登録ページのスクリーンショット。

  6. [新しいサービス プリンシパル] ページで、[ 表示名 ] と [アプリケーション (クライアント)ID] の値をコピーし、後で使用するために保存します。

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

    [アプリケーション (クライアント)] ID が強調表示されたポータルの [アプリケーション] ページのスクリーンショット。

サービス プリンシパル (アプリケーション) を使用するには、次の方法で見つけることができるサービス プリンシパルのパスワードを知っている必要があります。

  1. Azure portal から、 Microsoft Entra ID を検索して選択し、左側のウィンドウから [ アプリの登録 ] を選択します。

  2. 一覧からサービス プリンシパル (アプリケーション) を選択します。

  3. 左側のウィンドウから [ 証明書 & シークレット ] を選択します。

  4. [新しいクライアント シークレット] を選択します。

  5. [ クライアント シークレットの追加] ページで、[ 説明] を入力し、[ 有効期限] で有効期限を選択してから、[ 追加] を選択します。

    [ クライアント シークレット] ページで、新しいシークレットの [値 ] 列の文字列がパスワードになります。 この値を保存します。

    クライアント シークレットを示すスクリーンショット。

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

新しいサービス プリンシパルが作成されたら、上記で作成したサービス プリンシパルに、purview アカウントのデータ プレーン ロールを割り当てる必要があります。 次の手順に従って適切なロールを割り当て、サービス プリンシパルと Purview アカウントの間に信頼を確立します。

  1. Microsoft Purview ガバナンス ポータルに移動します。

  2. 左側のメニューで [データ マップ] を選択します。

  3. [コレクション] を選択します。

  4. コレクション メニューでルート コレクションを選択します。 これは一覧の一番上のコレクションになり、Microsoft Purview アカウントと同じ名前になります。

    注:

    また、ルート コレクションではなく任意のサブコレクションにサービス プリンシパル アクセス許可を割り当てることもできます。 ただし、すべての API はそのコレクション (およびアクセス許可を継承するサブコレクション) が対象となり、別のコレクションに対して API を呼び出そうとするとエラーが発生します。

  5. [ ロールの割り当て] タブを選択します。

  6. 以前に作成したサービス プリンシパルに次のロールを割り当てて、Microsoft Purview のさまざまなデータ プレーンにアクセスします。 詳細な手順については、「 Microsoft Purview ガバナンス ポータルを使用した Azure ロールの割り当て」を参照してください。

  • カタログにアクセスするためのデータキュレーター ロール データ プレーン。

  • スキャンにアクセスするためのデータ ソース管理者ロール データ プレーン。

  • アカウント データ プレーンとメタデータ ポリシー データ プレーンにアクセスするためのコレクション管理者ロール。

  • DevOps ポリシー API にアクセスするためのポリシー作成者ロール

    注:

    コレクション管理者ロールのメンバーのみが、Microsoft Purview でデータ プレーン ロールを割り当てることができます。 Microsoft Purview ロールの詳細については、「 Microsoft Purview でのアクセス制御」を参照してください。

トークンの取得

次の URL に POST 要求を送信して、アクセス トークンを取得できます。

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 = "00001111-aaaa-2222-bbbb-3333cccc4444"; 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 を呼び出します。

次の手順