Microsoft Purview を使用した API のGraphQL (プレビュー)

重要

この機能は現在プレビューの段階です。 Microsoft Azure プレビューの補足使用条件には、ベータ版、プレビュー版、または一般公開されていないAzure機能に適用される追加の法的条件が含まれています。

このチュートリアルでは、GraphQL API を使用してプログラムで Microsoft Purview と対話する方法について説明します。一般的なGraphQLの詳細については、このGraphQLの概要に関するページを参照してください。

GraphQLの使用は、サービスエンドポイントに JSON ペイロードを送信するという点で、REST API の使用と似ています。ただし、GraphQLを使用すると、1 回のフェッチで完全な情報を返すことができます。これにより、複数の API 呼び出しが不要になります。

GraphQLでは、宣言型データフェッチも使用されます。宣言型データフェッチは、元のエンティティにリンクされた分類/term/関連エンティティなどのフィールドで選択的にフェッチする場合に便利です。これらのクエリパターンでGraphQLを使用することで、バックエンドデータベースのフェッチとデータ転送を最適化できます。 "フィルター処理された関連エンティティを持つエンティティを取得し、エイリアスで区切る" の例を示します。

イントロスペクション機能により、GraphQL API は自己説明的になり、クライアントは使用可能なクエリ、型、クエリパラメーターなどのスキーマの詳細を取得できます。イントロスペクションの詳細を参照してください。

前提条件

Azure サブスクリプションをお持ちでない場合は、開始する前に無料アカウントを作成してください。
既存の Microsoft Purview アカウントが必要です。そうでない場合は、 Microsoft Purview アカウントを作成するためのクイックスタートを参照してください。
ベアラートークンを確立し、すべての API を呼び出すには、 Microsoft Purview の API を認証する方法に関するドキュメントを参照してください。

GraphQL エンドポイント

すべての要求について、次のエンドポイントに POST 要求を送信できます。

POST https://{{endpoint}}/datamap/api/graphql

新しい Microsoft Purview ポータルを使用している場合、{{endpoint}} の値は api.purview-service.microsoft.comです。
従来の Microsoft Purview ガバナンスポータルを使用している場合、{{endpoint}} の値は {your_purview_account_name}.purview.azure.comです。

基本的なクエリ

エンティティ - Guid で一覧表示

query {
    entities(where: { guid: ["<guid1>", "<guid2>"] }) { #Values in the array are combined as a logical-OR.
        guid
        createTime
        updateTime
        typeName
        attributes
        name
        qualifiedName
        description
    }
}

応答の例:

{
    "data": {
        "entities": [
            {
                "guid": "9fb74c11-ac48-4650-95bc-760665c5bd92",
                "createTime": 1553072455110,
                "updateTime": 1553072455110,
                "typeName": "azure_storage_account",
                "attributes": {
                    "qualifiedName": "https://exampleaccount.core.windows.net",
                    "name": "ExampleStorageAccount",
                },
                "name": "ExampleStorageAccount",
                "qualifiedName": "https://exampleaccount.core.windows.net",
                "description": "Example Storage Account"
            }
        ]
    }
}

型と修飾名でエンティティを照会する

query {
    entities(
        where: {
            type: { typeName: ["<entityType1>", "<entityType2>"] }
            qualifiedName: { in: ["<qualifiedName1>", "<qualifiedName2>"] }
        }
    ) {
        guid
        typeName
        qualifiedName
        attributes
    }
}

演算子 in は、複数の修飾名のクエリに使用されます。

可能な演算子は、 exists|eq|ne|in|nin|gt|ge|lt|leできます。イントロスペクションを使用すると、より多くのサーバースキーマの詳細を確認できます。

宣言型データのフェッチ

選択したフィールドを含むエンティティを取得する

query {
    entities(where: { guid: "<guid>" }) {
        guid
        typeName
        attributes
        businessAttributes
        qualifiedName
    }
}

すべてのフィールドを含むエンティティを取得する

query {
    entities(where: { guid: "<guid>" }) {
        guid
        createTime
        createdBy
        updateTime
        updatedBy
        lastModifiedTS
        typeName
        attributes
        businessAttributes
        collectionId
        customAttributes
        hierarchyInfo {
            ...hierarchyInfoFields
        }
        labels
        sensitivityLabel {
            ...sensitivityLabelFields
        }
        source
        sourceDetails
        qualifiedName
        name
        description
        displayName
        userDescription
        classifications {
            ...classificationFields
        }
        relatedEntities {
            ...relatedEntitiesFields
        }
        assignedTerms {
            ...assignedTermsFields
        }
    }
}

分類を使用してエンティティを取得する

- すべての分類

query {
    entities(where: { guid: "<guid>" }) {
        guid
        typeName
        attributes
        classifications {
            typeName
            attributes
        }
    }
}

- フィルター処理された分類

query {
    entities(where: { guid: "<guid>" }) {
        guid
        typeName
        attributes
        classifications(where: { type: { typeName: "<classificationType>" } }) {
            typeName
            attributes
        }
    }
}

query {
    entities(where: { guid: "<guid>" }) {
        guid
        typeName
        attributes
        relatedEntities {
            relationshipAttributeName
            relationship {
                guid
                typeName
                attributes
            }
            entity {
                guid
                typeName
                qualifiedName
                attributes
            }
        }
    }
}

query {
    entities(where: { guid: "<guid>" }) {
        guid
        typeName
        attributes
        relatedEntities(where: { relationshipAttributeName: "<relAttrName1>" }) {
            entity {
                guid
                typeName
                qualifiedName
                attributes
            }
        }
    }
}

query {
    entities(where: { guid: "<guid>" }) {
        guid
        typeName
        attributes
        alias1: relatedEntities(where: { relationshipAttributeName: "<relAttrName1>" }) {
            entity {
                guid
                typeName
                attributes
            }
        }
        alias2: relatedEntities(where: { relationshipAttributeName: "<relAttrName2>" }) {
            entity {
                guid
                typeName
                attributes
            }
        }
    }
}

用語集の用語を使用してエンティティを取得する

- すべての用語集の用語

query {
    entities(where: { guid: "<guid>" }) {
        guid
        typeName
        attributes
        assignedTerms {
            confidence
            createdBy
            description
            expression
            steward
            source
            status
            term {
                qualifiedName
                name
                shortDescription
                longDescription
            }
        }
    }
}

- フィルター処理された用語集の用語

query {
    entities(where: { guid: "<guid>" }) {
        guid
        typeName
        attributes
        assignedTerms {
            confidence
            createdBy
            description
            expression
            steward
            source
            status
            term {
                qualifiedName
                name
                shortDescription
                longDescription
            }
        }
    }
}

フィルター処理 (プレビュー)

'GUID' と 'Qualified-Name' の正確な一致のパフォーマンスは、「基本クエリ」セクションで提供されている例で保証されています。ただし、他のフィルター処理パターンにはいくつかの制限があります。

インデックスのないフィールドでのフィルター処理: GUID & 修飾名以外のフィールドは現在インデックス付けされていません (「単純なフィルター」セクションの例)。 GUID/修飾名の条件なしでインデックスのないフィールドをフィルター処理すると、テーブルスキャンが発生し、大規模なデータセットでパフォーマンスの問題が発生する可能性があります。
入れ子になったフィルター処理: インデックスのないフィールドと同様に、入れ子になったフィルター処理によってテーブルスキャンが発生する可能性があり、大規模なデータセットでパフォーマンスの問題が発生する可能性があります。たとえば、リンクされた分類/用語/関連エンティティを持つエンティティを検索します。

これらの制限にもかかわらず、この呼び出しパターンはクライアント側のフィルター処理よりも優れており、現在は内部クライアントによって使用されています。

単純なフィルター

型とシステム属性でエンティティを照会する

query {
    entities(
        where: {
            type: { typeName: "<entityType>" }
            name: { eq: "<value>" }
            createTime: { timerange: LAST_7D }
            updateTime: { gt: "<timestamp>" }
        }
    ) {
        guid
        typeName
        qualifiedName
        attributes
    }
}

型と属性でエンティティを照会する

query {
    entities(
        where: {
            type: { typeName: "<entityType>" }
            attribute: { field: "<attrName>",operator: eq, value: "<attrValue>" }
        }
    ) {
        guid
        typeName
        qualifiedName
        attributes
    }
}

型とビジネス属性でエンティティを照会する

query {
    entities(
        where: {
            type: { typeName: "<entityType>" }
            businessAttribute: { field: "<BusinessMetadataName>.<BusinessAttributeName>", operator: eq, value: "<BizAttrValue>" }
        }
    ) {
        guid
        typeName
        qualifiedName
        attributes
    }
}

コレクション別にエンティティを照会する

現時点では、このクエリパターンはサブアセンブリではサポートされていません。

query {
    entities(
        where: {
            type: { typeName: "<entityType>" }
            collectionID: "<collectionId>"
        }
    ) {
        guid
        typeName
        qualifiedName
        attributes
    }
}

フィルターの組み合わせ

オブジェクト (map) 内のキーは論理 AND として結合されます。

query {
    entities(
        where: {
            type: { typeName: "<entityType>" }
            or: [
                {
                    and: [
                        { attribute: { field: "<attrName1>", value: "<attrValue1>" } }
                        { attribute: { field: "<attrName2>", value: "<attrValue2>" } }
                    ]
                }
                {
                    not: {
                        businessAttribute: {
                            field: "<BusinessMetadataName>.<BusinessAttributeName>", value: "<BizAttrValue>"
                        }
                    }
                }
            ]
        }
    ) {
        guid
        typeName
        qualifiedName
        attributes
    }
}

入れ子になったフィルター

現時点では、このクエリパターンはサブアセンブリではサポートされていません。

分類によるエンティティのクエリ

query {
    entities(
        where: {
            classification: { type: { typeName: "<classificationType>", includeSubTypes: true } }
        }
    ) {
        guid
        typeName
        qualifiedName
        attributes
    }
}

query {
    entities(
        where: {
            relatedEntity: {
                relationshipAttributeName: "<relAttrName>"
                entity: {
                    type: { typeName: "<entityType>" }
                }
            }
        }
    ) {
        guid
        typeName
        qualifiedName
        attributes
    }
}

用語集の用語によるクエリエンティティ

query {
    entities(
        where: {
            assignedTerm: {
                term: {
                    qualifiedName: { eq: "<termName>" }
                }
            }
        }
    ) {
        guid
        typeName
        qualifiedName
        attributes
    }
}

その他のクエリ

リレーションシップを取得する

query {
    relationships(where: { guid: "<guid>" }) {
        guid
        typeName
        attributes
        end1 {
            guid
            typeName
            qualifiedName
            attributes
        }
        end2 {
            guid
            typeName
            qualifiedName
            attributes
        }
    }
}

応答の例:

{
    "data": {
        "relationships": [
            {
                "guid": "...",
                "typeName": "ExampleRelationship",
                "attributes": {},
                "end1": {
                    "guid": "...",
                    "typeName": "column",
                    "qualifiedName": "...",
                    "attributes": {}
                },
                "end2": {
                    "guid": "...",
                    "typeName": "column",
                    "qualifiedName": "...",
                    "attributes": {}
                }
            }
        ]
    }
}

系統

ダウンストリームデータセットを使用してデータセットを取得する

このクエリは、ダウンストリームデータセットを 2 度に返します。

query {
    entities(where: { guid: "<guid>" }) {#dataset
        guid
        typeName
        qualifiedName
        relatedEntities(where: { relationshipAttributeName: "inputToProcesses" }) {
            entity {#process
                guid
                typeName
                relatedEntities(where: { relationshipAttributeName: "outputs" }) {
                    entity {#dataset
                        guid
                        typeName
                        qualifiedName
                        relatedEntities(where: { relationshipAttributeName: "inputToProcesses" }) {
                            entity {#process
                                guid
                                typeName
                                qualifiedName
                                relatedEntities(where: { relationshipAttributeName: "outputs" }) {
                                    entity {#dataset
                                        guid
                                        typeName
                                        qualifiedName
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}

応答の例:

{
    "data": {
        "entities": [
            {
                "guid": "...",
                "typeName": "Dataset",
                "qualifiedName": "...",
                "relatedEntities": [
                    {
                        "entity": {
                            "guid": "...",
                            "typeName": "Process",
                            "relatedEntities": [
                                {
                                    "entity": {
                                        "guid": "...",
                                        "typeName": "Dataset",
                                        "qualifiedName": "...",
                                        "relatedEntities": [
                                            {
                                                "entity": {
                                                    "guid": "...",
                                                    "typeName": "Process",
                                                    "relatedEntities": [
                                                        {
                                                            "entity": {
                                                                "guid": "...",
                                                                "typeName": "Dataset",
                                                                "qualifiedName": "..."
                                                            }
                                                        }
                                                    ]
                                                }
                                            }
                                        ]
                                    }
                                }
                            ]
                        }
                    }
                ]
            }
        ]
    }
}

制限事項

クエリのフェッチの深さの制限:

クエリはクエリの深さによって制限されます。最大深度は 5 です。たとえば、次のクエリは失敗します。

query {
    entities { #depth 1
        relatedEntities { #depth 2
            entity {
                relatedEntities { #depth 3
                    entity {
                        assignedTerms{ #depth 4
                            term {
                                classifications { #depth 5
                                    ...
                                }
                            }
                        }
                        relatedEntities { #depth 4
                            entity {
                                assignedTerms{ #depth 5
                                    term {
                                        classifications { #depth 6
                                            ...
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}

実行時フェッチコストの制限:

クエリは、クエリ実行のコストによって制約されます。最大許容コストは 100 単位に設定されます。

実行フェッチコストは、特定のエンティティまたは用語の関連エンティティ、割り当てられた用語、または分類の取得を目指すたびに計算されます。

例

2 つの関連エンティティを持つ 3 つのエンティティに対してクエリを実行するシナリオを考えてみましょう。コスト計算は次のようになります。

ルートクエリの 1 つのユニット
レベル 1 エンティティごとに 3 つのユニット

そのため、このクエリの合計コストは 1 (root query) + 3 (level-1 entities) = 4されます。

パフォーマンスのフィルター処理

フィルター処理は現在プレビュー段階であり、いくつかの制限があります。詳細については、「フィルター処理」を参照してください。

GraphQLクエリは、最上位ノードを取得するルートクエリで始まります。次に、関連ノードを再帰的にフェッチします。

入れ子になったクエリのパフォーマンスは、関連するノードが SQL の外部キーと同様に既知の開始点からフェッチされるため、主にルートクエリによって決まります。

パフォーマンスを最適化するには、最上位ノードでテーブルスキャンをトリガーする可能性があるワイルドカードルートクエリを回避することが重要です。

たとえば、次のクエリでは、 name フィールドにインデックスが作成されていないため、大規模なデータセットでパフォーマンスの問題が発生する可能性があります。

query {
    entities(where: { name: { eq: "<value>" } }) {
        guid
        typeName
        attributes
        relatedEntities {
            entity {
                guid
                typeName
                attributes
            }
        }
    }
}

このようなパフォーマンスの問題を防ぐには、 guid または qualifiedNameにフィルターを適用してください。

次の手順

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

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-05-15

次の方法で共有

Microsoft Purview を使用した API のGraphQL (プレビュー)

前提条件

GraphQL エンドポイント

基本的なクエリ

エンティティ - Guid で一覧表示

型と修飾名でエンティティを照会する

宣言型データのフェッチ

選択したフィールドを含むエンティティを取得する

すべてのフィールドを含むエンティティを取得する

分類を使用してエンティティを取得する

- すべての分類

- フィルター処理された分類

関連エンティティを持つエンティティを取得する

- すべての関連エンティティを含む

- フィルター処理された関連エンティティを含む

- フィルター処理された関連エンティティを使用し、エイリアスで区切ります

用語集の用語を使用してエンティティを取得する

- すべての用語集の用語

- フィルター処理された用語集の用語

フィルター処理 (プレビュー)

単純なフィルター

型とシステム属性でエンティティを照会する

型と属性でエンティティを照会する

型とビジネス属性でエンティティを照会する

コレクション別にエンティティを照会する

フィルターの組み合わせ

入れ子になったフィルター

分類によるエンティティのクエリ

関連エンティティによるエンティティのクエリ

用語集の用語によるクエリ エンティティ

その他のクエリ

リレーションシップを取得する

系統

ダウンストリーム データセットを使用してデータセットを取得する

制限事項

クエリのフェッチの深さの制限:

実行時フェッチコストの制限:

例

パフォーマンスのフィルター処理

次の手順

フィードバック

その他のリソース

用語集の用語によるクエリエンティティ

ダウンストリームデータセットを使用してデータセットを取得する