Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
Le API REST graph consentono di elencare ed eseguire query su grafici personalizzati nel data lake Microsoft Sentinel. Usare queste API per interagire a livello di codice con i grafici personalizzati da qualsiasi client HTTP, pipeline di automazione o applicazione personalizzata.
Per altre informazioni sulla creazione di grafici personalizzati, vedere Creare grafici personalizzati nel data lake di sicurezza.
Autenticazione
Le API REST Graph usano l'autenticazione del token di connessione OAuth 2.0. Per chiamare le API, ottenere un token di accesso da Microsoft Entra ID e includerlo nell'intestazione Authorization di ogni richiesta.
Ottenere un token di accesso
- Registrare un'applicazione in Microsoft Entra ID o usare una registrazione dell'app esistente. Per altre informazioni, vedere Registrare un'applicazione.
- Concedere all'applicazione le autorizzazioni necessarie per Microsoft Defender XDR.
- Richiedere un token di accesso usando il flusso delle credenziali client OAuth 2.0 o per conto di un utente connesso.
Includere il token nelle richieste
Aggiungere il token all'intestazione Authorization di ogni richiesta API:
Authorization: Bearer <access_token>
URL di base
Tutti gli endpoint DELL'API REST Graph usano l'URL di base seguente:
https://api.securityplatform.microsoft.com
Elencare i grafici
Elencare tutti i grafici personalizzati disponibili nel tenant.
Richiesta
GET https://api.securityplatform.microsoft.com/graphs/graph-instances?graphTypes=Custom
Non è necessario alcun corpo della richiesta.
Risposta
{
"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"
}
]
}
Proprietà della risposta
| Proprietà | Tipo | Descrizione |
|---|---|---|
name |
Stringa | Nome dell'istanza del grafico. |
mapFileName |
Stringa | Nome del file di mappa associato al grafico. |
mapFileVersion |
Stringa | Versione del file di mappa. |
graphDefinitionName |
Stringa | Nome della definizione del grafo usata per compilare questa istanza. |
graphDefinitionVersion |
Stringa | Versione della definizione del grafo. |
refreshFrequency |
Stringa | Frequenza di aggiornamento dei dati del grafo. |
createTime |
Stringa | Quando è stata creata l'istanza del grafico. |
lastUpdateTime |
Stringa | Data dell'ultimo aggiornamento dell'istanza del grafico. |
lastSnapshotTime |
Stringa | Timestamp dello snapshot dei dati più recente. |
lastSnapshotRequestTime |
Stringa | Quando è stato richiesto l'ultimo snapshot. |
instanceStatus |
Stringa | Stato corrente dell'istanza del grafico. |
Codici di stato della risposta
| Codice di stato | Descrizione |
|---|---|
| 200 Va bene | Elenco recuperato correttamente. |
Eseguire query su un grafico
Eseguire query su un grafico personalizzato usando Graph Query Language (GQL). Per altre informazioni su GQL, vedere Informazioni di riferimento su GQL per Microsoft Sentinel grafico.
Nota
{graphName} fa riferimento all'oggetto name di un grafo restituito dall'operazione di elenco.
Richiesta
POST https://api.securityplatform.microsoft.com/graphs/graph-instances/{graphName}/query
Content-Type: application/json
Corpo della richiesta
{
"query": "string",
"queryLanguage": "GQL"
}
Proprietà del corpo della richiesta
| Proprietà | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
query |
Stringa | Sì | Query GQL da eseguire. |
queryLanguage |
Stringa | Sì | Linguaggio di query. Deve essere GQL. |
responseFormats |
Matrice a stringa | No | Controlla il formato della risposta alla query. Accetta uno o entrambi i valori seguenti: Table, Graph. Il valore predefinito è Table se non specificato. |
Formati di risposta
La responseFormats proprietà controlla la struttura della risposta:
| Formato | Descrizione |
|---|---|
Table |
Restituisce dati tabulari non elaborati (impostazione predefinita se non specificata). |
Graph |
Restituisce dati strutturati a grafo con nodi e archi. |
È possibile richiedere uno o entrambi i formati:
-
["Table"]- Restituisce solo il formato di tabella. -
["Graph"]- Restituisce solo il formato del grafico. -
["Table", "Graph"]- Restituisce entrambi i formati nella risposta.
Esempio: Query di 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"
}
Esempio: Eseguire query con entrambi i formati di risposta
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"
}
Risposta di esempio (entrambi i formati)
{
"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"
}
Codici di stato della risposta
| Codice di stato | Descrizione |
|---|---|
| 200 Va bene | Query eseguita correttamente. |
| 404 Non trovato | L'istanza del grafico specificata non esiste. |
Esempio di risposta agli errori
{
"error": {
"code": "GraphInstanceNotFound",
"message": "Graph Instance CustomGraph1 does not exist.",
"target": null,
"details": []
}
}