GraphQL API 与 Microsoft Purview (预览版)

2025/06/06

重要

此功能目前处于预览状态。 Azure 预览版的补充使用条款包含适用于 beta 版、预览版或其他尚未正式发布的 Azure 功能的其他法律条款。

本教程介绍如何使用 GraphQL API 以编程方式与 Microsoft Purview 交互。有关一般GraphQL的详细信息，请参阅此GraphQL简介。

使用 GraphQL类似于使用 REST API，即将 JSON 有效负载发送到服务终结点。但是，GraphQL允许我们在一次提取中返回完整信息，而无需多个 API 调用。

GraphQL还使用声明性数据提取。声明性数据提取对于对链接到原始实体的分类/术语/相关实体等字段进行选择性提取非常有用。通过对这些查询模式使用 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.cn。

基本查询

实体 - 按 Guids 列出

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.chinacloudapi.cn",
                    "name": "ExampleStorageAccount",
                },
                "name": "ExampleStorageAccount",
                "qualifiedName": "https://exampleaccount.core.chinacloudapi.cn",
                "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/Qualified-name 条件的非索引字段进行筛选将导致表扫描，并可能导致大型数据集的性能问题。
嵌套筛选：与非索引字段类似，嵌套筛选可能会导致表扫描，这可能会导致大型数据集的性能问题。例如，查找具有链接分类/术语/相关实体的实体。

尽管存在这些限制，但此调用模式优于客户端筛选，目前由内部客户端使用。

简单筛选器

按类型和系统属性查询实体

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
    }
}

筛选器组合

对象中的键 (映射) 组合为逻辑 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 个单位。

每当我们打算检索给定实体或术语的相关实体、分配的术语或分类时，都会计算执行提取成本。

示例：

假设我们查询了 3 个实体，每个实体都有两个相关实体。成本计算将如下所示：

根查询的一个单元
每个级别 1 实体有三个单位

因此，此查询的总成本为 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 管理数据源

通过

GraphQL API 与 Microsoft Purview (预览版)

先决条件

GraphQL终结点

基本查询

实体 - 按 Guids 列出

按类型和限定名称查询实体

声明性数据提取

获取具有所选字段的实体

获取包含所有字段的实体

使用分类获取实体

- 包含所有分类

- 使用筛选的分类

获取具有相关实体的实体

- 包含所有相关实体

- 包含筛选的相关实体

- 包含筛选的相关实体，以别名分隔

使用术语表术语获取实体

- 包含所有术语表术语

- 使用筛选的术语表术语

筛选 (预览)

简单筛选器

按类型和系统属性查询实体

按类型和属性查询实体

按类型和业务属性查询实体

按集合查询实体

筛选器组合

嵌套筛选器

按分类查询实体

按相关实体查询实体

按术语表术语查询实体

其他查询

获取关系

世系

获取包含下游数据集的数据集

局限性

查询提取深度限制：

执行时间提取成本限制：

示例：

筛选性能

后续步骤

其他资源