GraphQL API 与 Microsoft Purview（预览版）

项目
2024/11/21

重要

此功能目前以预览版提供。 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。

基本查询

实体 - 按 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.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”和“限定名称”的完全匹配性能。但是，其他筛选模式存在一些限制：

对非索引字段进行筛选：除 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
    }
}

筛选器组合

对象（映射）中的键组合为逻辑与。

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 终结点

基本查询

实体 - 按 Guid 列出

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

声明性数据提取

获取具有选定字段的实体

获取具有所有字段的实体

获取具有分类的实体

- 具有所有分类

- 具有筛选的分类

获取具有相关实体的实体

- 具有所有相关实体

- 具有筛选的相关实体

- 具有筛选的相关实体，由别名分隔

获取具有术语表术语的实体

- 具有所有术语表术语

- 具有筛选的术语表术语

筛选（预览）

简单筛选器

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

按类型和属性查询实体

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

按集合查询实体

筛选器组合

嵌套的筛选器

按分类查询实体

按相关实体查询实体

按术语表术语查询实体

其他查询

获取关系

沿袭

获取带有下游数据集的数据集

限制

查询提取深度限制：

执行时提取成本限制：

示例

筛选性能

后续步骤

其他资源