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.

Solicitação

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

Nenhum corpo de solicitação é obrigatório.

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 de resposta

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

Códigos de status de resposta

Código de status Descrição
200 Tudo certo 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.

Observação

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

Solicitação

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

Corpo da solicitação

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

Propriedades do corpo do pedido

Propriedade Tipo Obrigatório Descrição
query Cadeia de caracteres Sim A consulta GQL a executar.
queryLanguage Cadeia de caracteres Sim A linguagem de consulta. Deve ser GQL.
responseFormats Matriz de string 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 status de resposta

Código de status Descrição
200 Tudo certo 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": []
    }
}

Próximas etapas

  • Última atualização em