Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Mit den Graph-REST-APIs können Sie benutzerdefinierte Graphen in Ihrem Microsoft Sentinel Data Lake auflisten und abfragen. Verwenden Sie diese APIs für die programmgesteuerte Interaktion mit Ihren benutzerdefinierten Graphen aus jedem HTTP-Client, einer Automatisierungspipeline oder einer benutzerdefinierten Anwendung.
Weitere Informationen zum Erstellen benutzerdefinierter Graphen finden Sie unter Erstellen benutzerdefinierter Graphen im Security Data Lake.
Authentifizierung
Die Graph-REST-APIs verwenden die OAuth 2.0-Bearertokenauthentifizierung. Um die APIs aufzurufen, rufen Sie ein Zugriffstoken von Microsoft Entra ID ab, und fügen Sie es in den Authorization Header jeder Anforderung ein.
Abrufen eines Zugriffstokens
- Registrieren Sie eine Anwendung in Microsoft Entra ID, oder verwenden Sie eine vorhandene App-Registrierung. Weitere Informationen finden Sie unter Registrieren einer Anwendung.
- Erteilen Sie der Anwendung die erforderlichen Berechtigungen für Microsoft Defender XDR.
- Anfordern eines Zugriffstokens mithilfe des OAuth 2.0-Clientanmeldeinformationsflows oder im Namen eines angemeldeten Benutzers.
Einschließen des Tokens in Anforderungen
Fügen Sie das Token dem Authorization Header jeder API-Anforderung hinzu:
Authorization: Bearer <access_token>
Basis-URL
Alle Graph-REST-API-Endpunkte verwenden die folgende Basis-URL:
https://api.securityplatform.microsoft.com
Auflisten von Diagrammen
Listet alle benutzerdefinierten Diagramme auf, die in Ihrem Mandanten verfügbar sind.
Anforderung
GET https://api.securityplatform.microsoft.com/graphs/graph-instances?graphTypes=Custom
Es ist kein Anforderungstexts erforderlich.
Antwort
{
"value": [
{
"name": "custom_graph_10",
"mapFileName": "custom_graph_10",
"mapFileVersion": "1.0.0",
"graphDefinitionName": "custom_graph_10",
"graphDefinitionVersion": "1.0.0",
"refreshFrequency": "00:00:00",
"createTime": "11/04/2025 22:32:43",
"lastUpdateTime": "11/04/2025 22:32:43",
"lastSnapshotTime": "2025-11-04T22:34:04.7105015+00:00",
"lastSnapshotRequestTime": "2025-11-04T22:32:52.0187838+00:00",
"instanceStatus": "Ready"
},
{
"name": "notebook_graph_5",
"mapFileName": null,
"mapFileVersion": null,
"graphDefinitionName": "notebook_graph_5",
"graphDefinitionVersion": "1.0.0",
"refreshFrequency": "00:00:00",
"createTime": "11/04/2025 20:15:22",
"lastUpdateTime": "11/04/2025 20:15:22",
"lastSnapshotTime": null,
"lastSnapshotRequestTime": null,
"instanceStatus": "Creating"
}
]
}
Antworteigenschaften
| Eigenschaft | Typ | Beschreibung |
|---|---|---|
name |
Zeichenfolge | Der Name des Graphen instance. |
mapFileName |
Zeichenfolge | Der Name der Zuordnungsdatei, die dem Diagramm zugeordnet ist. |
mapFileVersion |
Zeichenfolge | Die Version der Zuordnungsdatei. |
graphDefinitionName |
Zeichenfolge | Der Name der Graphdefinition, die zum Erstellen dieses instance verwendet wird. |
graphDefinitionVersion |
Zeichenfolge | Die Version der Graphdefinition. |
refreshFrequency |
Zeichenfolge | Gibt an, wie oft die Diagrammdaten aktualisiert werden. |
createTime |
Zeichenfolge | Wenn das Diagramm instance erstellt wurde. |
lastUpdateTime |
Zeichenfolge | Wann das Diagramm instance zuletzt aktualisiert wurde. |
lastSnapshotTime |
Zeichenfolge | Der Zeitstempel der letzten daten Momentaufnahme. |
lastSnapshotRequestTime |
Zeichenfolge | Wann die letzte Momentaufnahme angefordert wurde. |
instanceStatus |
Zeichenfolge | Die aktuelle status des Diagramms instance. |
Antwortcodes status
| Statuscode | Beschreibung |
|---|---|
| 200 OK (Anforderung erfolgreich) | Die Liste wurde erfolgreich abgerufen. |
Abfragen eines Graphen
Abfragen eines benutzerdefinierten Graphen mithilfe der Graph Query Language (GQL). Weitere Informationen zu GQL finden Sie unter GQL-Referenz für Microsoft Sentinel Graph.
Hinweis
{graphName} verweist auf die name eines Graphen, der vom Listenvorgang zurückgegeben wird.
Anforderung
POST https://api.securityplatform.microsoft.com/graphs/graph-instances/{graphName}/query
Content-Type: application/json
Anforderungstext
{
"query": "string",
"queryLanguage": "GQL"
}
Eigenschaften des Anforderungstexts
| Eigenschaft | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
query |
Zeichenfolge | Ja | Die auszuführende GQL-Abfrage. |
queryLanguage |
Zeichenfolge | Ja | Die Abfragesprache. Muss GQL sein. |
responseFormats |
Zeichenfolgenarray | Nein | Steuert das Format der Abfrageantwort. Akzeptiert einen oder beide der folgenden Werte: Table, Graph. Wenn nicht angegeben, wird standardmäßig auf Table festgelegt. |
Antwortformate
Die responseFormats -Eigenschaft steuert die Struktur der Antwort:
| Format | Beschreibung |
|---|---|
Table |
Gibt unformatierte tabellarische Daten zurück (Standardwert, wenn nicht angegeben). |
Graph |
Gibt diagrammstrukturierte Daten mit Knoten und Kanten zurück. |
Sie können ein oder beide Formate anfordern:
-
["Table"]– Gibt nur das Tabellenformat zurück. -
["Graph"]– Gibt nur das Diagrammformat zurück. -
["Table", "Graph"]– Gibt beide Formate in der Antwort zurück.
Beispiel: Einfache Abfrage
POST https://api.securityplatform.microsoft.com/graphs/graph-instances/{graphName}/query
Content-Type: application/json
{
"query": "MATCH (u)-[v]->(w) RETURN * LIMIT 2",
"queryLanguage": "GQL"
}
Beispiel: Abfrage mit beiden Antwortformaten
POST https://api.securityplatform.microsoft.com/graphs/graph-instances/{graphName}/query
Content-Type: application/json
{
"query": "MATCH (n:User)-[r:HasAccess]->(m:Resource) RETURN n, r, m LIMIT 100",
"responseFormats": ["Table", "Graph"],
"queryLanguage": "GQL"
}
Beispielantwort (beide Formate)
{
"status": 200,
"result": {
"rawData": {
"tables": [
{
"tableName": "PrimaryResult",
"columns": [
{
"columnName": "u",
"dataType": "dynamic"
},
{
"columnName": "r",
"dataType": "dynamic"
},
{
"columnName": "g",
"dataType": "dynamic"
}
],
"rows": [
[
{
"oid": "node-user-001",
"labels": ["User"],
"properties": {
"name": "Aino Rebane",
"email": "aino.rebane@contoso.com",
"department": "Engineering"
}
},
{
"oid": "edge-001",
"labels": ["HasRole"],
"sourceOid": "node-user-001",
"targetOid": "node-group-001",
"properties": {
"assignedDate": "2024-01-15T10:30:00Z",
"assignedBy": "admin@contoso.com"
}
},
{
"oid": "node-group-001",
"labels": ["Group"],
"properties": {
"name": "Administrators",
"description": "System administrators group",
"memberCount": 25
}
}
]
]
}
]
},
"graph": {
"nodes": [
{
"id": "node-user-001",
"labels": ["User"],
"properties": {
"name": "Aino Rebane",
"email": "aino.rebane@contoso.com",
"department": "Engineering"
}
},
{
"id": "node-group-001",
"labels": ["Group"],
"properties": {
"name": "Administrators",
"description": "System administrators group",
"memberCount": 25
}
},
{
"id": "node-group-002",
"labels": ["Group"],
"properties": {
"name": "Engineering Team",
"description": "Software engineering team",
"memberCount": 150
}
}
],
"edges": [
{
"id": "edge-001",
"sourceId": "node-user-001",
"targetId": "node-group-001",
"labels": ["HasRole"],
"properties": {
"assignedDate": "2024-01-15T10:30:00Z",
"assignedBy": "admin@contoso.com"
}
},
{
"id": "edge-002",
"sourceId": "node-user-001",
"targetId": "node-group-002",
"labels": ["HasRole"],
"properties": {
"assignedDate": "2024-02-01T14:20:00Z",
"assignedBy": "hr@contoso.com"
}
}
]
}
},
"correlationId": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
Antwortcodes status
| Statuscode | Beschreibung |
|---|---|
| 200 OK (Anforderung erfolgreich) | Die Abfrage wurde erfolgreich ausgeführt. |
| 404 Nicht gefunden | Der angegebene Graph instance ist nicht vorhanden. |
Fehlerantwort-Beispiel
{
"error": {
"code": "GraphInstanceNotFound",
"message": "Graph Instance CustomGraph1 does not exist.",
"target": null,
"details": []
}
}