REST API Graph для пользовательских графов (предварительная версия)

ИНТЕРФЕЙСы REST API Graph позволяют перечислять пользовательские графы и запрашивать их в Microsoft Sentinel озера данных. Используйте эти API для программного взаимодействия с пользовательскими графами из любого HTTP-клиента, конвейера автоматизации или пользовательского приложения.

Дополнительные сведения о создании пользовательских графов см. в разделе Создание пользовательских графов в озере данных безопасности.

Проверка подлинности

REST API Graph используют проверку подлинности маркера носителя OAuth 2.0. Чтобы вызвать API- интерфейсы, получите маркер доступа из Microsoft Entra ID и включите его в Authorization заголовок каждого запроса.

Получение токена доступа

  1. Зарегистрируйте приложение в Microsoft Entra ID или используйте существующую регистрацию приложения. Дополнительные сведения см. в разделе Регистрация приложения.
  2. Предоставьте приложению необходимые разрешения для Microsoft Defender XDR.
  3. Запросите маркер доступа с помощью потока учетных данных клиента OAuth 2.0 или от имени вошедшего пользователя.

Включение маркера в запросы

Добавьте маркер в Authorization заголовок каждого запроса API:

Authorization: Bearer <access_token>

Базовый URL-адрес

Все конечные точки REST API Graph используют следующий базовый 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 Имя экземпляра графа.
mapFileName String Имя файла карты, связанного с графом.
mapFileVersion String Версия файла карты.
graphDefinitionName String Имя определения графа, используемого для создания этого экземпляра.
graphDefinitionVersion String Версия определения графа.
refreshFrequency String Частота обновления данных графа.
createTime String При создании экземпляра графа.
lastUpdateTime String При последнем обновлении экземпляра графа.
lastSnapshotTime String Метка времени последнего snapshot данных.
lastSnapshotRequestTime String При запросе последнего snapshot.
instanceStatus String Текущее состояние экземпляра графа.

Коды состояния ответа

Код состояния Описание
200 OK (Запрос выполнен успешно) Список получен успешно.

Запрос графа

Запрос пользовательского графа с помощью языка запросов Graph (GQL). Дополнительные сведения о GQL см. в справочнике по GQL для Microsoft Sentinel графа.

Примечание.

{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 Массив строк Нет Управляет форматом ответа запроса. Принимает одно или оба следующих значения: 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 OK (Запрос выполнен успешно) Запрос выполнен успешно.
404 Не найдено Указанный экземпляр графа не существует.

Пример ответа об ошибке

{
    "error": {
        "code": "GraphInstanceNotFound",
        "message": "Graph Instance CustomGraph1 does not exist.",
        "target": null,
        "details": []
    }
}

Дальнейшие действия

  • Последнее обновление: