GraphQL-API mit Microsoft Purview (Vorschau)

Wichtig

Dieses Feature ist derzeit in der Vorschau. Die ergänzenden Nutzungsbedingungen für Microsoft Azure Previews enthalten zusätzliche rechtliche Bestimmungen, die für Azure Features gelten, die sich in der Betaversion, in der Vorschauversion oder anderweitig noch nicht in der allgemeinen Verfügbarkeit befinden.

In diesem Tutorial erfahren Sie, wie Sie mithilfe der GraphQL-API programmgesteuert mit Microsoft Purview interagieren. Weitere Informationen zu GraphQL im Allgemeinen finden Sie in dieser Einführung in GraphQL.

Die Verwendung von GraphQL ähnelt der Verwendung der REST-APIs, da Sie eine JSON-Nutzlast an einen Dienstendpunkt senden. GraphQL ermöglicht es uns jedoch, vollständige Informationen in einem einzigen Abruf zurückzugeben, sodass nicht mehr mehrere API-Aufrufe erforderlich sind.

GraphQL verwendet auch deklarative Datenabrufe. Deklaratives Abrufen von Daten ist nützlich für das selektive Abrufen von Feldern, z. B. mitklassifizierungsausdruckbezogenen//Entitäten, die mit der ursprünglichen Entität verknüpft sind. Durch die Verwendung von GraphQL mit diesen Abfragemustern können wir das Abrufen von Back-End-Datenbanken und die Datenübertragung optimieren. Ein gutes Beispiel ist "Get Entity with filtered related entities, separated by aliases".

Mit der Introspektion-Funktion wird die GraphQL-API selbstdeskriptiv, sodass Clients Schemadetails wie verfügbare Abfragen, Typen und Abfrageparameter abrufen können. Weitere Informationen finden Sie unter Introspektion.

Voraussetzungen

GraphQL-Endpunkt

Für alle Anforderungen können Sie eine POST Anforderung an den folgenden Endpunkt senden:

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

Standardabfrage

Entität – Auflisten nach 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
    }
}

Beispielantwort:

{
    "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"
            }
        ]
    }
}

Abfragen von Entitäten nach Typ und qualifiziertem Namen

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

Der Operator in wird verwendet, um mehrere qualifizierte Namen abzufragen.

Mögliche Operatoren können sein exists|eq|ne|in|nin|gt|ge|lt|le. Weitere Details zum Serverschema finden Sie bei der Introspektion.

Deklaratives Abrufen von Daten

Entität mit ausgewählten Feldern abrufen

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

Abrufen der Entität mit allen Feldern

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

Abrufen einer Entität mit Klassifizierungen

- mit allen Klassifizierungen

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

– mit gefilterten Klassifizierungen

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

– mit allen verwandten Entitäten

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

– mit gefilterten verwandten Entitäten

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

– mit gefilterten verknüpften Entitäten, durch Aliase getrennt

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

Entität mit Glossarbegriffen abrufen

- mit allen Glossarbegriffen

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

- mit gefilterten Glossarbegriffen

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

Filtern (Vorschau)

Die Leistung des genauen Abgleichs für "GUID" und "Qualified-Name" wird in den Beispielen im Abschnitt "Grundlegende Abfragen" garantiert. Es gibt jedoch einige Einschränkungen für andere Filtermuster:

  • Filtern nach nicht indizierten Feldern: Andere Felder als GUID & qualifizierten Namen sind derzeit nicht indiziert (beispiele im Abschnitt "Einfacher Filter"). Das Filtern nach nicht indizierten Feldern ohne Kriterien für GUID/Qualified-name führt zu einer Tabellenüberprüfung und kann zu Leistungsproblemen bei großen Datasets führen.
  • Geschachtelte Filterung: Ähnlich wie bei nicht indizierten Feldern kann die geschachtelte Filterung Tabellenscans verursachen, was zu Leistungsproblemen bei großen Datasets führen kann. Beispiel: Suchen einer Entität mit einer verknüpften Klassifizierungs-/Begriffs-/verknüpften Entität.

Trotz dieser Einschränkungen ist dieses Aufrufmuster der clientseitigen Filterung überlegen und wird derzeit von unserem internen Client verwendet.

Einfacher Filter

Abfragen von Entitäten nach Typ und Systemattributen

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

Abfragen von Entitäten nach Typ und Attributen

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

Abfragen von Entitäten nach Typ und Geschäftsattributen

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

Abfragen von Entitäten nach Sammlung

Derzeit wird dieses Abfragemuster für Unterassets nicht unterstützt.

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

Filterkombination

Schlüssel in einem Objekt (Map) werden als logisches AND kombiniert.

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

Geschachtelter Filter

Derzeit wird dieses Abfragemuster für Unterassets nicht unterstützt.

Abfrageentität nach Klassifizierung

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

Abfrageentität nach Glossarbegriffen

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

Andere Abfragen

Beziehung abrufen

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

Beispielantwort:

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

Herkunft

Abrufen eines Datasets mit nachgeschalteten Datasets

Diese Abfrage gibt nachgeschaltete Datasets auf 2 Grad zurück.

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

Beispielantwort:

{
    "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": "..."
                                                            }
                                                        }
                                                    ]
                                                }
                                            }
                                        ]
                                    }
                                }
                            ]
                        }
                    }
                ]
            }
        ]
    }
}

Begrenzungen

Einschränkung der Abfrageabruftiefe:

Abfragen werden durch die Abfragetiefe eingeschränkt. Die maximale Tiefe beträgt 5. Die folgende Abfrage schlägt z. B. fehl:

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

Einschränkung der Abrufkosten zur Ausführungszeit:

Abfragen werden durch die Kosten der Abfrageausführung eingeschränkt. Die maximal zulässigen Kosten sind auf 100 Einheiten festgelegt.

Die Ausführungsabrufkosten werden jedes Mal berechnet, wenn wir verwandte Entitäten, zugewiesene Begriffe oder Klassifizierungen für eine bestimmte Entität oder einen bestimmten Begriff abrufen möchten.

Beispiel

Stellen Sie sich ein Szenario vor, in dem wir drei Entitäten mit jeweils zwei verwandten Entitäten abfragen. Die Kostenberechnung lautet wie folgt:

  • Eine Einheit für die Stammabfrage
  • Drei Einheiten für jede Entität der Ebene 1

Daher würden die Gesamtkosten für diese Abfrage sein 1 (root query) + 3 (level-1 entities) = 4.

Filterleistung

Die Filterung befindet sich derzeit in der Vorschauphase und weist einige Einschränkungen auf. Weitere Informationen finden Sie unter Filtern .

GraphQL Abfragen beginnen mit einer Stammabfrage, die die Knoten der obersten Ebene abruft. Anschließend werden die zugehörigen Knoten rekursiv abgerufen.

Die Leistung einer geschachtelten Abfrage wird in erster Linie durch die Stammabfrage bestimmt, da die zugehörigen Knoten von einem bekannten Ausgangspunkt abgerufen werden, ähnlich wie bei einem Fremdschlüssel in SQL.

Um die Leistung zu optimieren, ist es wichtig, Wildcard-Stammabfragen zu vermeiden, die eine Tabellenüberprüfung auf den Knoten der obersten Ebene auslösen könnten.

Für instance kann die folgende Abfrage Leistungsprobleme bei großen Datasets verursachen, da das name Feld nicht indiziert ist:

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

Um solche Leistungsprobleme zu verhindern, stellen Sie sicher, dass Sie einen Filter auf guid oder qualifiedNameanwenden.

Nächste Schritte

Verwalten von MicrosoftPurview-DATENebenen-REST-APIs für Datenquellen

  • Last updated on