Graph REST API:er för anpassade grafer (förhandsversion)

Med Graph REST-API:erna kan du lista och köra frågor mot anpassade grafer i din Microsoft Sentinel datasjö. Använd dessa API:er för att interagera programmässigt med dina anpassade grafer från alla HTTP-klienter, automatiseringspipelines eller anpassade program.

Mer information om hur du skapar anpassade grafer finns i Skapa anpassade grafer i säkerhetsdatasjön.

Autentisering

Graph REST API:er använder autentisering med OAuth 2.0-ägartoken. Om du vill anropa API:erna hämtar du en åtkomsttoken från Microsoft Entra ID och inkluderar den i rubriken för Authorization varje begäran.

Hämta en åtkomsttoken

  1. Registrera ett program i Microsoft Entra ID eller använd en befintlig appregistrering. Mer information finns i Registrera ett program.
  2. Ge programmet de behörigheter som krävs för Microsoft Defender XDR.
  3. Begär en åtkomsttoken med OAuth 2.0-klientens autentiseringsuppgifter eller för en inloggad användares räkning.

Inkludera token i begäranden

Lägg till token i rubriken för Authorization varje API-begäran:

Authorization: Bearer <access_token>

Bas-URL

Alla Graph REST API-slutpunkter använder följande bas-URL:

https://api.securityplatform.microsoft.com

Visa diagram

Visa en lista över alla anpassade grafer som är tillgängliga i din klientorganisation.

Begäran

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

Ingen begärandetext krävs.

Svar

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

Svarsegenskaper

Egenskap Typ Beskrivning
name Sträng Namnet på grafinstansen.
mapFileName Sträng Namnet på kartfilen som är associerad med grafen.
mapFileVersion Sträng Kartfilens version.
graphDefinitionName Sträng Namnet på grafdefinitionen som används för att skapa den här instansen.
graphDefinitionVersion Sträng Versionen av grafdefinitionen.
refreshFrequency Sträng Hur ofta grafdata uppdateras.
createTime Sträng När grafinstansen skapades.
lastUpdateTime Sträng När grafinstansen senast uppdaterades.
lastSnapshotTime Sträng Tidsstämpeln för den senaste ögonblicksbilden av data.
lastSnapshotRequestTime Sträng När den senaste ögonblicksbilden begärdes.
instanceStatus Sträng Grafinstansens aktuella status.

Svarsstatuskoder

Statuskod Beskrivning
200 Okej Listan har hämtats.

Fråga ett diagram

Fråga en anpassad graf med hjälp av Graph Query Language (GQL). Mer information om GQL finns i GQL-referens för Microsoft Sentinel graf.

Obs!

{graphName} refererar till för name ett diagram som returneras från liståtgärden.

Begäran

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

Frågebrödtext

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

Egenskaper för begärandetext

Egenskap Typ Obligatoriskt Beskrivning
query Sträng Ja Den GQL-fråga som ska köras.
queryLanguage Sträng Ja Frågespråket. Måste vara GQL.
responseFormats Strängmatris Nej Styr formatet på frågesvaret. Accepterar ett eller båda av följande värden: Table, Graph. Standardvärdet är Table om det inte anges.

Svarsformat

Egenskapen responseFormats styr svarets struktur:

Format Beskrivning
Table Returnerar rådata i tabellform (standard om de inte anges).
Graph Returnerar grafstrukturerade data med noder och kanter.

Du kan begära ett eller båda formaten:

  • ["Table"] – Returnerar endast tabellformat.
  • ["Graph"] – Returnerar endast grafformat.
  • ["Table", "Graph"] – Returnerar båda formaten i svaret.

Exempel: Grundläggande fråga

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

Exempel: Fråga med båda svarsformaten

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

Exempelsvar (båda formaten)

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

Svarsstatuskoder

Statuskod Beskrivning
200 Okej Frågan har körts.
404 Hittades inte Den angivna grafinstansen finns inte.

Exempel på felsvar

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

Nästa steg

  • Uppdaterades senast