Compartir a través de

API rest de Graph para gráficos personalizados (versión preliminar)

Las API rest de Graph le permiten enumerar y consultar gráficos personalizados en el lago de datos de Microsoft Sentinel. Use estas API para interactuar mediante programación con los gráficos personalizados desde cualquier cliente HTTP, canalización de automatización o aplicación personalizada.

Para obtener más información sobre cómo crear gráficos personalizados, consulte Creación de gráficos personalizados en el lago de datos de seguridad.

Autenticación

Las API rest de Graph usan la autenticación de token de portador de OAuth 2.0. Para llamar a las API, obtenga un token de acceso de Microsoft Entra ID e inclúyelo en el Authorization encabezado de cada solicitud.

Obtención de un token de acceso

  1. Registre una aplicación en el identificador de Entra de Microsoft o use un registro de aplicación existente. Para obtener más información, consulte Registro de una aplicación.
  2. Conceda a la aplicación los permisos necesarios para XDR de Microsoft Defender.
  3. Solicite un token de acceso mediante el flujo de credenciales de cliente de OAuth 2.0 o en nombre de un usuario que haya iniciado sesión.

Incluir el token en las solicitudes

Agregue el token al Authorization encabezado de cada solicitud de API:

Authorization: Bearer <access_token>

Dirección URL base

Todos los puntos de conexión de la API REST de Graph usan la siguiente dirección URL base:

https://api.securityplatform.microsoft.com

Enumerar gráficos

Enumere todos los gráficos personalizados disponibles en el inquilino.

Solicitud

GET https://api.securityplatform.microsoft.com/graphs/graph-instances?graphTypes=Custom

No es necesario ningún cuerpo de solicitud.

Respuesta

{
  "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"
    }
  ]
}

Propiedades de respuesta

Propiedad Tipo Descripción
name String Nombre de la instancia del grafo.
mapFileName String Nombre del archivo de asignación asociado al gráfico.
mapFileVersion String Versión del archivo de asignación.
graphDefinitionName String Nombre de la definición del grafo que se usa para compilar esta instancia.
graphDefinitionVersion String Versión de la definición del grafo.
refreshFrequency String Frecuencia con la que se actualizan los datos del grafo.
createTime String Cuando se creó la instancia del grafo.
lastUpdateTime String Cuando la instancia del grafo se actualizó por última vez.
lastSnapshotTime String Marca de tiempo de la instantánea de datos más reciente.
lastSnapshotRequestTime String Cuando se solicitó la última instantánea.
instanceStatus String Estado actual de la instancia del grafo.

Códigos de estado de respuesta

Código de estado Descripción
200 Ok Lista recuperada correctamente.

Consulta de un grafo

Consulta de un grafo personalizado mediante el lenguaje de consulta de Graph (GQL). Para obtener más información sobre GQL, consulte Referencia de GQL para el grafo de Microsoft Sentinel.

Nota:

{graphName} hace referencia al name de un gráfico devuelto de la operación de lista.

Solicitud

POST https://api.securityplatform.microsoft.com/graphs/graph-instances/{graphName}/query
Content-Type: application/json

Cuerpo de la solicitud

{
  "query": "string",
  "queryLanguage": "GQL"
}

Propiedades del cuerpo de la solicitud

Propiedad Tipo Obligatorio Descripción
query String Sí Consulta GQL que se va a ejecutar.
queryLanguage String Sí Lenguaje de consulta. Debe ser GQL.
responseFormats Matriz de cadenas No Controla el formato de la respuesta de consulta. Acepta uno o ambos de los siguientes valores: Table, Graph. El valor predeterminado es Table si no se especifica.

Formatos de respuesta

La responseFormats propiedad controla la estructura de la respuesta:

Formato Descripción
Table Devuelve datos tabulares sin formato (valor predeterminado si no se especifica).
Graph Devuelve datos estructurados por grafos con nodos y bordes.

Puede solicitar uno o ambos formatos:

  • ["Table"] - Devuelve solo el formato de tabla.
  • ["Graph"] - Devuelve solo el formato de grafo.
  • ["Table", "Graph"] : devuelve ambos formatos en la respuesta.

Ejemplo: Consulta básica

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"
}

Ejemplo: Consulta con ambos formatos de respuesta

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"
}

Respuesta de ejemplo (ambos formatos)

{
  "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"
}

Códigos de estado de respuesta

Código de estado Descripción
200 Ok La consulta se ejecutó correctamente.
404 No encontrado La instancia de grafo especificada no existe.

Ejemplo de respuesta de error

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

Pasos siguientes

  • Last updated on