Graph REST API 讓你能在 Microsoft Sentinel 資料湖中列出並查詢自訂圖形。 利用這些 API 程式化地與你來自任何 HTTP 客戶端、自動化流程或自訂應用程式的自訂圖形互動。
欲了解更多關於建立自訂圖表的資訊，請參閱 安全資料湖中的自訂圖表。
驗證
Graph REST API 採用 OAuth 2.0 持有憑證認證。 要呼叫 API，請從 Microsoft Entra ID 取得存取權杖，並將其包含在Authorization每個請求的標頭中。
取得存取權杖
- 請在 Microsoft Entra ID 註冊應用程式，或使用現有的應用程式註冊。 欲了解更多資訊，請參閱 「註冊申請」。
- 授予該應用程式 Microsoft Defender 全面偵測回應所需的權限。
- 可使用 OAuth 2.0 用戶端憑證流程或代表已登入使用者申請存取權杖。
在請求中包含該標記
將憑證加入 Authorization 每個 API 請求的標頭：
Authorization: Bearer <access_token>
基礎網址
所有 Graph REST API 端點皆使用以下基底 URL：
https://api.securityplatform.microsoft.com
列表圖表
列出租戶中所有可用的自訂圖表。
請求
GET https://api.securityplatform.microsoft.com/graphs/graph-instances?graphTypes=Custom
不需要申請機構。
回應
{
"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"
}
]
}
反應特性
| 屬性 | 類型 | 描述 |
|---|---|---|
name |
字串 | 圖實例的名稱。 |
mapFileName |
字串 | 與該圖相關的地圖檔案名稱。 |
mapFileVersion |
字串 | 地圖檔案的版本。 |
graphDefinitionName |
字串 | 用於建構此實例的圖定義名稱。 |
graphDefinitionVersion |
字串 | 圖定義的版本。 |
refreshFrequency |
字串 | 圖表資料刷新的頻率。 |
createTime |
字串 | 當圖實例建立時。 |
lastUpdateTime |
字串 | 圖表實例最後更新的時間。 |
lastSnapshotTime |
字串 | 最新資料快照的時間戳。 |
lastSnapshotRequestTime |
字串 | 當最後一次快照被要求時。 |
instanceStatus |
字串 | 圖實例的當前狀態。 |
回應狀態碼
| 狀態碼 | 描述 |
|---|---|
| 200 確定 | 名單已成功檢索。 |
查詢圖
使用 GQL) (圖查詢語言查詢自訂圖。 欲了解更多 GQL 資訊，請參閱 Microsoft Sentinel 圖的 GQL 參考文獻。
注意事項
{graphName} 指 name 的是從列表操作返回的圖。
請求
POST https://api.securityplatform.microsoft.com/graphs/graph-instances/{graphName}/query
Content-Type: application/json
要求內文
{
"query": "string",
"queryLanguage": "GQL"
}
請求身體屬性
| 屬性 | 類型 | 必要 | 描述 |
|---|---|---|---|
query |
字串 | 是 | 執行 GQL 查詢。 |
queryLanguage |
字串 | 是 | 查詢語言。 一定是 GQL。 |
responseFormats |
字串陣列 | 否 | 控制查詢回應的格式。 接受以下一個或兩個值： Table， Graph。 若未指定，則預設為 Table 。 |
回應格式
屬性 responseFormats 控制反應的結構：
| 格式 | 描述 |
|---|---|
Table |
若未) 指定， (預設回傳原始表格資料。 |
Graph |
回傳帶有節點與邊的圖結構化資料。 |
你可以申請其中一種或兩種格式：
-
["Table"]- 僅回傳表格格式。 -
["Graph"]- 僅回傳圖形格式。 -
["Table", "Graph"]- 在回應中回傳兩種格式。
範例：基本查詢
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"
}
範例：查詢同時使用兩種回應格式
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"
}
兩種格式的樣本回應 ()
{
"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"
}
回應狀態碼
| 狀態碼 | 描述 |
|---|---|
| 200 確定 | 查詢成功執行。 |
| 404號未找到 | 指定的圖實例不存在。 |
錯誤回應範例
{
"error": {
"code": "GraphInstanceNotFound",
"message": "Graph Instance CustomGraph1 does not exist.",
"target": null,
"details": []
}
}