Graph REST API를 사용하면 Microsoft Sentinel 데이터 레이크에서 사용자 지정 그래프를 나열하고 쿼리할 수 있습니다. 이러한 API를 사용하여 HTTP 클라이언트, 자동화 파이프라인 또는 사용자 지정 애플리케이션의 사용자 지정 그래프와 프로그래밍 방식으로 상호 작용합니다.
사용자 지정 그래프를 만드는 방법에 대한 자세한 내용은 보안 데이터 레이크에서 사용자 지정 그래프 만들기를 참조하세요.
인증
Graph REST API는 OAuth 2.0 전달자 토큰 인증을 사용합니다. API를 호출하려면 Microsoft Entra ID 액세스 토큰을 가져와서 각 요청의 헤더에 Authorization 포함합니다.
액세스 토큰 가져오기
- Microsoft Entra ID 애플리케이션을 등록하거나 기존 앱 등록을 사용합니다. 자세한 내용은 애플리케이션 등록을 참조하세요.
- 애플리케이션에 Microsoft Defender XDR 필요한 권한을 부여합니다.
- OAuth 2.0 클라이언트 자격 증명 흐름을 사용하거나 로그인한 사용자를 대신하여 액세스 토큰을 요청합니다.
요청에 토큰 포함
모든 API 요청의 헤더에 Authorization 토큰을 추가합니다.
Authorization: Bearer <access_token>
기본 URL
모든 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 |
String | 그래프 instance 이름입니다. |
mapFileName |
String | 그래프와 연결된 맵 파일의 이름입니다. |
mapFileVersion |
String | 맵 파일의 버전입니다. |
graphDefinitionName |
String | 이 instance 빌드하는 데 사용되는 그래프 정의의 이름입니다. |
graphDefinitionVersion |
String | 그래프 정의의 버전입니다. |
refreshFrequency |
String | 그래프 데이터가 새로 고쳐지는 빈도입니다. |
createTime |
String | 그래프 instance 생성된 경우 |
lastUpdateTime |
String | 그래프 instance 마지막으로 업데이트된 경우 |
lastSnapshotTime |
String | 가장 최근 데이터 스냅샷 타임스탬프입니다. |
lastSnapshotRequestTime |
String | 마지막 스냅샷 요청된 경우입니다. |
instanceStatus |
String | 그래프의 현재 상태 instance. |
응답 상태 코드
| 상태 코드 | 설명 |
|---|---|
| 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 |
String | 예 | 실행할 GQL 쿼리입니다. |
queryLanguage |
String | 예 | 쿼리 언어입니다. 이어야 GQL합니다. |
responseFormats |
String 배열 | 아니요 | 쿼리 응답의 형식을 제어합니다. 다음 값 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 찾을 수 없음 | 지정된 그래프 instance 존재하지 않습니다. |
오류 응답 예제
{
"error": {
"code": "GraphInstanceNotFound",
"message": "Graph Instance CustomGraph1 does not exist.",
"target": null,
"details": []
}
}