Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
Les API REST Graph vous permettent de répertorier et d’interroger des graphiques personnalisés dans votre lac de données Microsoft Sentinel. Utilisez ces API pour interagir par programmation avec vos graphiques personnalisés à partir d’un client HTTP, d’un pipeline d’automatisation ou d’une application personnalisée.
Pour plus d’informations sur la création de graphiques personnalisés, consultez Créer des graphiques personnalisés dans le lac de données de sécurité.
Authentification
Les API REST Graph utilisent l’authentification par jeton du porteur OAuth 2.0. Pour appeler les API, obtenez un jeton d’accès à partir de Microsoft Entra ID et incluez-le dans l’en-tête Authorization de chaque requête.
Obtenir un jeton d’accès
- Inscrire une application dans Microsoft Entra ID ou utiliser une inscription d’application existante. Pour plus d’informations, consultez Inscrire une application.
- Accordez à l’application les autorisations requises pour Microsoft Defender XDR.
- Demandez un jeton d’accès à l’aide du flux d’informations d’identification du client OAuth 2.0 ou au nom d’un utilisateur connecté.
Inclure le jeton dans les requêtes
Ajoutez le jeton à l’en-tête Authorization de chaque requête d’API :
Authorization: Bearer <access_token>
URL de base
Tous les points de terminaison de l’API REST Graph utilisent l’URL de base suivante :
https://api.securityplatform.microsoft.com
Graphes de liste
Répertoriez tous les graphiques personnalisés disponibles dans votre locataire.
Demande
GET https://api.securityplatform.microsoft.com/graphs/graph-instances?graphTypes=Custom
Vous n’êtes pas obligé de spécifier le corps de la demande.
Réponse
{
"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"
}
]
}
Propriétés response
| Propriété | Type | Description |
|---|---|---|
name |
String | Nom du graphique instance. |
mapFileName |
String | Nom du fichier de carte associé au graphe. |
mapFileVersion |
String | Version du fichier de carte. |
graphDefinitionName |
String | Nom de la définition de graphique utilisée pour générer cette instance. |
graphDefinitionVersion |
String | Version de la définition du graphique. |
refreshFrequency |
String | Fréquence à laquelle les données du graphique sont actualisées. |
createTime |
String | Lorsque le graphique instance a été créé. |
lastUpdateTime |
String | Lorsque le graphique instance a été mis à jour pour la dernière fois. |
lastSnapshotTime |
String | Horodatage de la instantané de données la plus récente. |
lastSnapshotRequestTime |
String | Lorsque la dernière instantané a été demandée. |
instanceStatus |
String | La status actuelle de l’instance de graphique. |
Codes de status de réponse
| Code d'état | Description |
|---|---|
| 200 OK | Liste récupérée avec succès. |
Interroger un graphe
Interroger un graphe personnalisé à l’aide du langage de requête Graph (GQL). Pour plus d’informations sur GQL, consultez informations de référence sur GQL pour Microsoft Sentinel graphe.
Remarque
{graphName} fait référence au name d’un graphique retourné à partir de l’opération de liste.
Demande
POST https://api.securityplatform.microsoft.com/graphs/graph-instances/{graphName}/query
Content-Type: application/json
Corps de la demande
{
"query": "string",
"queryLanguage": "GQL"
}
Propriétés du corps de la demande
| Propriété | Type | Requis | Description |
|---|---|---|---|
query |
String | Oui | Requête GQL à exécuter. |
queryLanguage |
String | Oui | Langage de requête. Doit être GQL. |
responseFormats |
Tableau de chaînes | Non | Contrôle le format de la réponse à la requête. Accepte une ou les deux valeurs suivantes : Table, Graph. La valeur par défaut est Table si elle n’est pas spécifiée. |
Formats de réponse
La responseFormats propriété contrôle la structure de la réponse :
| Format | Description |
|---|---|
Table |
Retourne des données tabulaires brutes (valeur par défaut si elle n’est pas spécifiée). |
Graph |
Retourne des données structurées par graphique avec des nœuds et des arêtes. |
Vous pouvez demander un ou les deux formats :
-
["Table"]- Retourne uniquement le format de tableau. -
["Graph"]- Retourne uniquement le format de graphique. -
["Table", "Graph"]- Retourne les deux formats dans la réponse.
Exemple : requête de base
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"
}
Exemple : Requête avec les deux formats de réponse
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"
}
Exemple de réponse (les deux formats)
{
"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"
}
Codes de status de réponse
| Code d'état | Description |
|---|---|
| 200 OK | Requête exécutée avec succès. |
| 404 Introuvable | Le instance de graphe spécifié n’existe pas. |
Exemple de réponse d’erreur
{
"error": {
"code": "GraphInstanceNotFound",
"message": "Graph Instance CustomGraph1 does not exist.",
"target": null,
"details": []
}
}