Microsoft Purview Python SDKは、Microsoft Purviewガバナンスポータルで行うデータソース登録、スキャン実行、カタログ検索をPythonから自動化したい管理者・開発者向けのSDKです。まず押さえるべき結論は、スキャンやカタログ検索を自動化する場合は、認証情報、Purviewロール、Storage側のIAM、ポータル種別ごとのエンドポイントを先に確認することです。ここを曖昧にしたままコードを書き始めると、SDKのインストールは成功しているのに、403エラーやエンドポイント不一致で止まりやすくなります。
2026年6月2日に更新された公式の「Azure Purview SDK for Python – latest」では、パッケージ一覧として主に Resource Management - Purview と azure-mgmt-purview が示されています。一方、Blob Storageの登録、スキャン定義、カタログ検索を行う公式チュートリアルでは、azure-purview-scanning、azure-purview-catalog、azure-purview-administration、azure-purview-account などを使います。つまり、Microsoft Purview Python SDKを使うときは、PurviewアカウントなどAzureリソースを管理するSDKと、データマップ・スキャン・カタログを操作するSDKを分けて考える必要があります。(Microsoft Learn)
Microsoft Purview Python SDKでできること
Microsoft Purview Python SDKを使うと、Microsoft Purviewガバナンスポータル上で手動実行していた作業をPythonスクリプトに置き換えられます。公式チュートリアルでは、主に次の操作が扱われています。(Microsoft Learn)
| 操作 | 使う主なクライアント | 実務での活用例 |
|---|---|---|
| データソース登録 | PurviewScanningClient | 新しいAzure Storageをデータマップへ定期登録する |
| スキャン定義の作成 | PurviewScanningClient | 環境ごとに同じスキャンルールを展開する |
| スキャン実行 | PurviewScanningClient | CI/CDや定期ジョブからメタデータ収集を開始する |
| カタログ検索 | PurviewCatalogClient | 特定キーワードを含む資産を抽出し、棚卸しに使う |
| コレクション取得 | PurviewAccountClient | 表示名ではなく、SDKで必要な内部コレクション名を取得する |
| データソース削除 | PurviewScanningClient | 検証用に登録したデータソースをクリーンアップする |
特に重要なのは、SDKでサブコレクションを扱う場合です。Microsoft Purviewの画面で見える「Sales」のようなフレンドリ名と、SDKが参照する内部名は異なります。ルート以外のコレクションにはデータマップ側で割り当てられた名前があり、Pythonから操作するときはその値を使う必要があります。(Microsoft Learn)
2026年6月公式情報で確認すべき変更点
2026年6月2日に更新された公式SDK参照ページでは、Azure Purview SDK for Pythonのlatestとして azure-mgmt-purview が掲載されています。これは主にPurviewアカウントなどのAzureリソース管理に関わるパッケージです。スキャンやカタログ検索を行うチュートリアルの内容とは目的が異なるため、同じ「PurviewのPython SDK」として一括りにしないほうが安全です。(Microsoft Learn)
また、公式のAzure SDK for Python概要では、AzureライブラリはPython 3.9以降をサポート対象として案内しています。azure-mgmt-purview のPyPI情報でも Python >=3.9 が要求され、プロジェクト説明ではPython 3.10以上でテストされている旨が示されています。既存の古い自動化環境がPython 3.6や3.7で動いている場合は、SDK更新前にランタイムを見直してください。(Microsoft Learn)
| 確認項目 | 管理者・開発者への影響 |
|---|---|
azure-mgmt-purview の位置づけ | Purviewアカウント管理向け。スキャン・カタログ検索用SDKとは用途が違う |
| Pythonバージョン | 新規構築ではPython 3.9以上、可能なら3.10以上を前提にする |
| パッケージ更新 | CI/CDで無制限に最新版を入れず、検証済みバージョンを固定する |
| 既存コード | azure-mgmt-purview のプレビュー版を試す場合、破壊的変更の影響を確認する |
| エンドポイント | 旧ポータルと新ポータルで値が異なるため、ハードコードを避ける |
azure-mgmt-purview は2026年5月20日に1.0.1がリリースされ、1.1.0b2のプレリリースではメソッド引数やモデル構造に関するBreaking Changesも記載されています。検証なしにプレリリースへ上げると、Account モデルの参照方法やメソッド呼び出しが変わり、既存スクリプトが失敗する可能性があります。(PyPI)
影響範囲：どの環境を確認すべきか
Microsoft Purview Python SDKの影響を受けやすいのは、次のような環境です。
- Azure StorageやデータソースをPythonで自動登録している
- スキャン実行をAzure Functions、GitHub Actions、Azure DevOps、バッチサーバーなどから呼び出している
- カタログ検索結果を棚卸し、データ分類、監査レポートに使っている
- サービスプリンシパルのクライアントシークレットで認証している
- Purviewポータル移行やエンドポイント変更に合わせてコードを修正している
- SDKのパッケージバージョンを固定せず、
pip installだけで本番デプロイしている
逆に、Microsoft Purviewの画面だけで手動スキャンしている環境は、Python SDKの更新による直接影響は限定的です。ただし、同じPurviewアカウントやコレクションの権限をSDK用サービスプリンシパルにも付与している場合は、権限の棚卸し対象に含めてください。
事前準備：SDKを動かす前に確認する設定
Microsoft Purview Python SDKでは、コード以前の設定が成否を大きく左右します。特に、Storage側のIAMとPurview側のロールは別物です。
| 設定箇所 | 必要な確認 | 失敗しやすいポイント |
|---|---|---|
| Azure Storage | Purviewインスタンスに読み取り権限を付与 | Storage側のIAMを忘れ、スキャン時に失敗する |
| Microsoft Entra ID | サービスプリンシパル、クライアントID、テナントID、シークレット | シークレット期限切れや誤ったテナントID |
| Microsoft Purviewコレクション | SDK操作に必要なPurviewロールを付与 | ルートではなく対象コレクションに権限がない |
| Python環境 | Python 3.9以上、仮想環境、依存関係固定 | ローカルでは動くがCI/CDで別バージョンが入る |
| エンドポイント | 旧ポータル・新ポータルの違いを確認 | scan endpointとcatalog endpointを取り違える |
公式チュートリアルでは、Blob Storageをスキャンする前に、StorageアカウントのIAMでMicrosoft Purviewインスタンスへ Storage Blob Data Reader 相当の読み取り権限を付与する流れが示されています。また、サービスプリンシパルにはPurviewコレクション側で Collection admins、Data source admins、Data curators、Data readers を付与する手順が案内されています。(Microsoft Learn)
本番運用では、チュートリアル通りに広めの権限を与えたあと放置するのではなく、操作内容に応じて権限を見直してください。たとえば、カタログ検索だけを行うジョブにデータソース管理権限まで必要か、検証用と本番用のサービスプリンシパルを分けるべきか、シークレットのローテーション手順があるかを確認します。
インストールするPythonパッケージの考え方
公式チュートリアルでは、認証とPurview操作のために次のパッケージをインストールします。(Microsoft Learn)
pip install azure-identity
pip install azure-purview-scanning
pip install azure-purview-administration
pip install azure-purview-catalog
pip install azure-purview-account
pip install azure-corePurviewアカウントそのものの作成・管理など、Azureリソース管理に関わる処理では azure-mgmt-purview も確認対象になります。
pip install azure-mgmt-purview実務では、直接本番環境で pip install するのではなく、次のように requirements.txt に固定してから展開するのが安全です。
azure-identity==任意の検証済みバージョン
azure-purview-scanning==任意の検証済みバージョン
azure-purview-catalog==任意の検証済みバージョン
azure-purview-administration==任意の検証済みバージョン
azure-purview-account==任意の検証済みバージョン
azure-core==任意の検証済みバージョンバージョン番号は、検証環境で動作確認したものを入れてください。記事やチュートリアルに書かれていないバージョンを推測で固定するのは避けるべきです。
エンドポイント設定は旧ポータルと新ポータルで分ける
Microsoft Purview Python SDKでつまずきやすいのがエンドポイントです。公式チュートリアルでは、使用しているMicrosoft Purviewポータルによってエンドポイント値が異なると説明されています。クラシックポータルではアカウント名を含むURL、新しいMicrosoft Purviewポータルではサービス共通のAPIエンドポイントを使う構成です。(Microsoft Learn)
| 用途 | クラシックポータルの例 | 新しいMicrosoft Purviewポータルの例 |
|---|---|---|
| カタログ・管理系 | https://{your_purview_account_name}.purview.azure.com/ | https://api.purview-service.microsoft.com |
| スキャン系 | https://{your_purview_account_name}.scan.purview.azure.com/ | https://api.scan.purview-service.microsoft.com |
エンドポイントはコード内に直接書き込まず、環境変数として管理するのがおすすめです。検証環境、本番環境、旧ポータル、新ポータルで値が変わるためです。
export PURVIEW_ENDPOINT="https://api.purview-service.microsoft.com"
export PURVIEW_SCAN_ENDPOINT="https://api.scan.purview-service.microsoft.com"WindowsのPowerShellで設定する場合は、次のようにします。
$env:PURVIEW_ENDPOINT="https://api.purview-service.microsoft.com"
$env:PURVIEW_SCAN_ENDPOINT="https://api.scan.purview-service.microsoft.com"なお、Microsoft Learnのチュートリアル内には新ポータル向けスキャンエンドポイントの表記がセクションによって異なる箇所があります。SDK初期化やAPI呼び出しで接続エラーが出る場合は、利用中のPurviewポータル、公式ドキュメントの該当セクション、実際のアカウント設定を合わせて確認してください。
認証コードはシークレット直書きを避ける
公式チュートリアルでは ClientSecretCredential を使い、クライアントID、クライアントシークレット、テナントIDを指定して認証します。サンプルとしては分かりやすい一方、本番コードにシークレットを直接書くのは避けてください。(Microsoft Learn)
実務では、少なくとも環境変数から読み取る形にします。
import os
from azure.identity import ClientSecretCredential
from azure.purview.scanning import PurviewScanningClient
from azure.purview.catalog import PurviewCatalogClient
from azure.purview.administration.account import PurviewAccountClient
credential = ClientSecretCredential(
tenant_id=os.environ["AZURE_TENANT_ID"],
client_id=os.environ["AZURE_CLIENT_ID"],
client_secret=os.environ["AZURE_CLIENT_SECRET"],
)
purview_endpoint = os.environ["PURVIEW_ENDPOINT"]
purview_scan_endpoint = os.environ["PURVIEW_SCAN_ENDPOINT"]
scanning_client = PurviewScanningClient(
endpoint=purview_scan_endpoint,
credential=credential,
logging_enable=False,
)
catalog_client = PurviewCatalogClient(
endpoint=purview_endpoint,
credential=credential,
logging_enable=False,
)
account_client = PurviewAccountClient(
endpoint=purview_endpoint,
credential=credential,
logging_enable=False,
)Azure Functionsやコンテナーで動かす場合は、環境変数、Key Vault、マネージドIDの利用可否を設計段階で決めておくと、後からシークレット管理を作り直さずに済みます。
データソース登録からスキャン実行までの流れ
Microsoft Purview Python SDKでBlob Storageをスキャンする基本の流れは、次の順番です。
| 手順 | 内容 | 確認ポイント |
|---|---|---|
| 1 | StorageアカウントのリソースIDを取得 | サブスクリプション、リソースグループ、リージョンを間違えない |
| 2 | Purviewコレクション名を確認 | 画面の表示名ではなくSDK用の内部名を使う |
| 3 | データソース登録用のbodyを作成 | kind、endpoint、resourceId、collection を確認 |
| 4 | data_sources.create_or_update を実行 | 既存名と衝突しない命名にする |
| 5 | スキャン定義を作成 | ルールセット名と対象コレクションを確認 |
| 6 | run_scan で実行 | 実行IDはUUIDなどで一意にする |
| 7 | 完了後にカタログ検索 | スキャン直後は資産反映まで時間がかかる |
公式チュートリアルでは、スキャンは「スキャン定義の作成」と「スキャン実行」の2段階で行うと説明されています。また、スキャン完了後に資産が検出・分類され、Microsoft Purview Unified Catalogに表示されるまで時間がかかる場合があります。スキャン開始直後にカタログ検索して結果がない場合でも、すぐに失敗と判断しないでください。(Microsoft Learn)
スキャン定義の最小イメージは次のようになります。
import uuid
from azure.core.exceptions import HttpResponseError
data_source_name = "example-storage-source"
scan_name = "example-blob-scan"
collection_name = "対象コレクションの内部名"
scan_body = {
"kind": "AzureStorageMsi",
"properties": {
"scanRulesetName": "AzureStorage",
"scanRulesetType": "System",
"collection": {
"referenceName": collection_name,
"type": "CollectionReference",
},
},
}
try:
scanning_client.scans.create_or_update(
data_source_name=data_source_name,
scan_name=scan_name,
body=scan_body,
)
run_id = uuid.uuid4()
scanning_client.scan_result.run_scan(
data_source_name=data_source_name,
scan_name=scan_name,
run_id=run_id,
)
print(f"Scan started: {scan_name}, run_id={run_id}")
except HttpResponseError as error:
print(error)このコードを本番化する場合は、data_source_name、scan_name、collection_name を環境ごとに外出しし、同じスキャンを重複実行しない制御を入れましょう。夜間バッチで実行する場合は、前回のスキャンが完了しているかを確認してから次回を開始する設計が安全です。
カタログ検索の基本
スキャンが完了し、資産がカタログに反映されたら、PurviewCatalogClient で検索できます。公式チュートリアルでは、discovery.query に keywords を含む検索リクエストを渡す例が示されています。(Microsoft Learn)
from azure.core.exceptions import HttpResponseError
search_request = {
"keywords": "customer"
}
try:
result = catalog_client.discovery.query(search_request=search_request)
print(result)
except HttpResponseError as error:
print(error)実務では、単純なキーワード検索だけでなく、用途に応じて検索条件を分けると便利です。
| 目的 | 検索例 | 活用シーン |
|---|---|---|
| 個人情報候補の棚卸し | customer、email、phone | データ分類の初期確認 |
| 部門別の資産確認 | sales、finance | コレクション設計の妥当性確認 |
| 移行対象の抽出 | 旧システム名、データベース名 | 廃止予定システムの影響調査 |
| 命名ルール確認 | tmp、test、backup | 不要データや検証データの発見 |
検索結果をそのままレポートに使う場合は、実行日時、検索条件、対象Purviewアカウント、対象コレクションを一緒に保存してください。後日「なぜこの資産が一覧に入っていないのか」を確認するときに、再現性が重要になります。
管理者が確認すべきセキュリティ上の注意点
Microsoft Purview Python SDKの導入は、単なるPythonスクリプト追加ではありません。データカタログ、分類、スキャン対象にアクセスする自動化を増やすため、権限とログの扱いを慎重に設計する必要があります。
| 注意点 | 推奨対応 |
|---|---|
| クライアントシークレットの直書き | 環境変数、Key Vault、マネージドIDを検討する |
| サービスプリンシパルの過剰権限 | 検証用・本番用を分け、コレクション単位で棚卸しする |
| ログ出力 | HTTPヘッダーや本文を詳細ログに出しすぎない |
| パッケージ更新 | 本番前に検証環境でSDK更新テストを行う |
| エンドポイント移行 | 旧ポータル・新ポータルを混在させない |
| スキャン対象 | 不要なストレージや検証コンテナーを登録しない |
Purview Scanningクライアントのドキュメントでは、標準のloggingライブラリを使ってログ出力でき、DEBUGレベルではリクエスト・レスポンス本文や未編集のヘッダーが出る可能性がある旨が説明されています。トラブルシューティング時だけ詳細ログを有効化し、本番常時運用では必要最小限に抑えるのが安全です。(GitHub)
移行・展開時のチェックリスト
既存環境にMicrosoft Purview Python SDKを導入または更新する場合は、次の順番で確認すると失敗を減らせます。
| フェーズ | チェック内容 |
|---|---|
| 棚卸し | 既存スクリプト、Pythonバージョン、SDKパッケージ、実行基盤を確認 |
| 権限確認 | Storage IAM、Purviewコレクションロール、サービスプリンシパルを確認 |
| エンドポイント確認 | 旧ポータル・新ポータルのどちらを使うか決める |
| パッケージ固定 | 検証済みバージョンを requirements.txt に固定 |
| 検証実行 | 小さなBlob Storageや検証コレクションでスキャンを実行 |
| カタログ確認 | スキャン完了後、Unified Catalogに資産が反映されるか確認 |
| 本番展開 | ログ、監視、エラー通知、シークレット更新手順を整備 |
| 定期見直し | SDK更新、サービスプリンシパル期限、不要データソースを棚卸し |
特に、SDK更新とPurviewポータル移行を同時に行うのは避けたほうが無難です。エラーが出たときに、パッケージ変更、エンドポイント変更、権限変更のどれが原因か切り分けにくくなるためです。まずは現行SDKのままエンドポイントだけ検証し、次にSDKパッケージを更新するなど、変更点を分けて進めてください。
Microsoft Purview Python SDK導入でよくある失敗
SDKを入れたのに403エラーになる
多くの場合、Pythonコードではなく権限不足です。Storage側の読み取り権限と、Purviewコレクション側のロールは別々に確認します。サービスプリンシパルにAzureサブスクリプションの権限があっても、Purviewコレクションのロールが不足していれば操作できないことがあります。
コレクション名を指定しているのに見つからない
画面に表示されるフレンドリ名をそのまま使っている可能性があります。サブコレクションでは、SDKが参照する内部名を取得してから使います。ルートコレクションとサブコレクションで扱いが異なる点にも注意してください。
カタログ検索で結果が出ない
スキャン実行が成功しても、資産の検出・分類・カタログ反映には時間がかかることがあります。まずPurviewポータル上でスキャンが完了しているか、対象アセットがUnified Catalogに表示されているかを確認します。
CI/CDだけで失敗する
ローカル環境とCI/CD環境でPythonバージョン、環境変数、パッケージバージョンが違うケースがよくあります。python --version、pip freeze、環境変数の有無をジョブログに安全な範囲で出力し、差分を確認してください。
azure-mgmt-purview と azure-purview-scanning を混同する
azure-mgmt-purview はPurviewアカウントなどの管理プレーン向けです。データソース登録、スキャン実行、カタログ検索では、チュートリアルで使われる azure-purview-scanning や azure-purview-catalog などを確認します。Azure SDK for Python自体も、管理ライブラリとクライアントライブラリを用途別に分けて説明しています。(Microsoft Learn)
次に取るべき対応
Microsoft Purview Python SDKを使うなら、まずコードを書く前に、現在のPurview環境を次の4点で整理してください。
- 使う目的は「Purviewアカウント管理」か「スキャン・カタログ操作」か
- Python実行環境は3.9以上か
- 旧ポータルと新ポータルのどちらのエンドポイントを使うか
- サービスプリンシパルとPurviewコレクションの権限は適切か
そのうえで、検証用のBlob Storageを1つ登録し、スキャン定義、スキャン実行、カタログ検索までを小さく通します。最初から全データソースを自動化するのではなく、1つのデータソースで認証、権限、エンドポイント、パッケージバージョンを固めるのが、最も安全で早い導入方法です。
コメント