今回は チュートリアル:REST API を使用する 参考に REST API アクセスを見ていきます。ただしチュートリアルは API の内容についての詳細はないため、この記事では実際のカタログを検索する方法を紹介します。
REST API
他の多くのサービス同様、Azure Purview も REST API をサポートしており、プログラムからカタログ情報に対してアクセスが行えます。
サービスプリンシパルの作成と権限の付与
REST API で Purview にアクセスする際に利用するサービスプリンシパルを作成し、権限を設定していきます。
1. Azure ポータルより「Azure Active Directory」を選択し、「アプリの登録」より「新規登録」をクリック。
2. 任意の名前を付与。他の設定は既定のまま「登録」をクリック。
3.「概要」で「アプリケーション ID」と「テナント ID」を確認。後程利用するためコピーしておく。
4.「証明書とシークレット」より「新しいクライアント シークレット」をクリック。任意の有効期間を選んで「追加」をクリック。発行されたキーをコピーしておく。
5. Azure Purview リソースに移動し、「アクセス制御 (IAM)」より「追加」を選択し、「ロールの割り当ての追加」をクリック。
6. 作成したサービスプリンシパルに「Purview Data Curator」ロールを付与。
アクセストークンの取得
通常の Azure AD を利用した OAuth 2.0 認証です。C# などプログラム言語を利用する場合は MSAL を使ってアクセストークンを取得できます。ここでは Postman を使った手順を紹介します。
1. Postman を起動して、以下のように設定。テナント ID、クライアント ID、シークレットは上記で取得したものを利用。
HTTP メソッド: POST
アドレス: https://login.microsoftonline.com/<テナント ID>/oauth2/token
Body: x-www-form-urlencoded
キーと値: 以下画面ショットの通り
2.「Send」をクリックし、結果からアクセストークンを取得。
検索の実行
REST API ドキュメントを参照する の手順で Open API のドキュメントを確認します。いくつかエンドポイントがありますが、今回は検索と資産の参照を行います。
[API ドキュメント]
また Azure Purview の REST エンドポイントは Azure ポータルより、Purview アカウントのプロパティ画面で確認できます。
キーワードのみでの検索
まずは search/advanced エンドポイントに対して、キーワードのみで検索してみます。
1. Postman でアドレスとヘッダーに以下を設定。
HTTP メソッド: POST
アドレス: https://<Purview アカウント名>.catalog.purview.azure.com/api/atlas/v2/search/advanced
Headers: キーに Authorization、値に「Bearer 取得したアクセストークン」
※Bearer とアクセストークンの間に半角スペースが必要
2. Body で以下を設定。
種類: raw で JSON を選択
値: 以下 JSON を設定
{
"keywords":"contoso"
}
3.「Send」をクリックして結果を確認。
複数の結果が返ってきますが、期待していた資産の結果だけではなく、用語も含めた検索結果となっています。画面ショットは以下の用語が検索に出ています。
ファセットの追加
次に Azure Purview Studio の検索結果の左側に出るようなファセットも取得してみます。
1. Postman の Body に facets を追加。
{
"keywords":"contoso",
"facets": [
{
"facet": "assetType",
"count": 0,
"sort": {
"count": "desc"
}
},
{
"facet": "classification",
"count": 10,
"sort": {
"count": "desc"
}
},
{
"facet": "contactId",
"count": 10,
"sort": {
"count": "desc"
}
},
{
"facet": "label",
"count": 10,
"sort": {
"count": "desc"
}
},
{
"facet": "term",
"count": 10,
"sort": {
"count": "desc"
}
},
{
"facet": "classificationCategory",
"count": 0,
"sort": {
"count": "desc"
}
},
{
"facet": "fileExtension",
"count": 0,
"sort": {
"count": "desc"
}
}
]
}
2.「Send」をクリックして結果を確認。
Azure Purview Studio と同じように、分類や資産の種類などが検索結果と共に取得できることを確認します。
フィルターを追加して検索
現在は用語も含めた結果が取得されるため、資産のみ取得できるようフィルターを追加します。
1. Postman の Body に filter を追加。
{
"keywords": "contoso",
"filter": {
"and": [
{
"not": {
"or": [
{
"attributeName": "size",
"operator": "eq",
"attributeValue": 0
},
{
"attributeName": "fileSize",
"operator": "eq",
"attributeValue": 0
}
]
}
},
{
"not": {
"classification": "MICROSOFT.SYSTEM.TEMP_FILE"
}
},
{
"not": {
"or": [
{
"entityType": "AtlasGlossaryTerm"
},
{
"entityType": "AtlasGlossary"
}
]
}
}
]
},
"facets": [
{
"facet": "assetType",
"count": 0,
"sort": {
"count": "desc"
}
},
{
"facet": "classification",
"count": 10,
"sort": {
"count": "desc"
}
},
{
"facet": "contactId",
"count": 10,
"sort": {
"count": "desc"
}
},
{
"facet": "label",
"count": 10,
"sort": {
"count": "desc"
}
},
{
"facet": "term",
"count": 10,
"sort": {
"count": "desc"
}
},
{
"facet": "classificationCategory",
"count": 0,
"sort": {
"count": "desc"
}
},
{
"facet": "fileExtension",
"count": 0,
"sort": {
"count": "desc"
}
}
]
}
2.「Send」を実行して結果を確認。
資産のみが表示されていることを確認します。まだ不要なものが出ている場合は、フィルター条件を追加してさらに絞ってください。
資産の確認
続いて検索結果より資産の詳細を確認してみます。
1. Postman でアドレスとヘッダーに以下を設定。資産の guid は検索結果から任意のものを利用。
HTTP メソッド: GET
アドレス: https://<Purview アカウント名>.catalog.purview.azure.com/api/atlas/v2/entity/guid/<資産の guid>
Headers: キーに Authorization、値に「Bearer 取得したアクセストークン」
※Bearer とアクセストークンの間に半角スペースが必要
2.「Send」をクリックして結果を確認。
資産によってはスキーマや分類などを含んだ数多くの情報が表示されます。また手動で設定した連絡先などの情報も表示されることを確認してください。
その他のエンドポイント
Open API のドキュメントを見る限りでは、系列や分類などを個別に取得することもできますし、データの登録なども行えます。
ただしスキャンの手動トリガーなどの API は私が見た限りでは見つけられませんでした。発見した方は是非教えてください。