Graph REST APIs para gráficos personalizados (pré-visualização)

As APIs REST do Graph permitem-lhe listar e consultar gráficos personalizados no seu Microsoft Sentinel data lake. Utilize estas APIs para interagir programaticamente com os seus grafos personalizados a partir de qualquer cliente HTTP, pipeline de automatização ou aplicação personalizada.

Para obter mais informações sobre como criar gráficos personalizados, veja Criar gráficos personalizados no data lake de segurança.

Autenticação

As APIs REST do Graph utilizam a autenticação do token de portador OAuth 2.0. Para chamar as APIs, obtenha um token de acesso do Microsoft Entra ID e inclua-o no Authorization cabeçalho de cada pedido.

Obter um token de acesso

  1. Registe uma aplicação no Microsoft Entra ID ou utilize um registo de aplicações existente. Para obter mais informações, veja Registar uma aplicação.
  2. Conceda à aplicação as permissões necessárias para Microsoft Defender XDR.
  3. Peça um token de acesso com o fluxo de credenciais de cliente OAuth 2.0 ou em nome de um utilizador com sessão iniciada.

Incluir o token nos pedidos

Adicione o token ao Authorization cabeçalho de cada pedido de API:

Authorization: Bearer <access_token>

URL Base

Todos os pontos finais da API REST do Graph utilizam o seguinte URL base:

https://api.securityplatform.microsoft.com

Listar gráficos

Liste todos os gráficos personalizados disponíveis no seu inquilino.

Pedido

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

Não é necessário nenhum corpo do pedido.

Resposta

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

Propriedades da resposta

Propriedade Tipo Descrição
name Cadeia O nome da instância do gráfico.
mapFileName Cadeia O nome do ficheiro de mapa associado ao gráfico.
mapFileVersion Cadeia A versão do ficheiro de mapa.
graphDefinitionName Cadeia O nome da definição de gráfico utilizada para criar esta instância.
graphDefinitionVersion Cadeia A versão da definição do gráfico.
refreshFrequency Cadeia Com que frequência os dados do grafo são atualizados.
createTime Cadeia Quando a instância do gráfico foi criada.
lastUpdateTime Cadeia Quando a instância do gráfico foi atualizada pela última vez.
lastSnapshotTime Cadeia O carimbo de data/hora do instantâneo de dados mais recente.
lastSnapshotRequestTime Cadeia Quando o último instantâneo foi pedido.
instanceStatus Cadeia O estado atual da instância do gráfico.

Códigos de estado de resposta

Código de estado Descrição
200 OK Lista obtida com êxito.

Consultar um gráfico

Consultar um gráfico personalizado com a Linguagem de Consulta Graph (GQL). Para obter mais informações sobre a GQL, veja Referência de GQL para Microsoft Sentinel grafo.

Nota

{graphName} refere-se ao name de um gráfico devolvido da operação de lista.

Pedido

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

Corpo do pedido

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

Propriedades do corpo do pedido

Propriedade Tipo Obrigatório Descrição
query Cadeia Sim A consulta GQL a executar.
queryLanguage Cadeia Sim A linguagem de consulta. Tem de ser GQL.
responseFormats Matriz de cadeia Não Controla o formato da resposta da consulta. Aceita um ou ambos os seguintes valores: Table, Graph. A predefinição é se Table não for especificada.

Formatos de resposta

A responseFormats propriedade controla a estrutura da resposta:

Formatar Descrição
Table Devolve dados tabulares não processados (predefinição, se não especificado).
Graph Devolve dados estruturados por grafos com nós e arestas.

Pode pedir um ou ambos os formatos:

  • ["Table"] - Devolve apenas o formato da tabela.
  • ["Graph"] - Devolve apenas o formato de gráfico.
  • ["Table", "Graph"] - Devolve ambos os formatos na resposta.

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

Exemplo: Consulta com ambos os formatos de resposta

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

Resposta de exemplo (ambos os 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 resposta

Código de estado Descrição
200 OK A consulta foi executada com êxito.
404 Não Encontrado A instância de grafo especificada não existe.

Exemplo de resposta de erro

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

Passos seguintes

  • Última atualização a