Graph REST API's voor aangepaste grafieken (preview)

Met de Graph REST API's kunt u aangepaste grafieken in uw Microsoft Sentinel data lake weergeven en er query's op uitvoeren. Gebruik deze API's om programmatisch te communiceren met uw aangepaste grafieken vanuit elke HTTP-client, automatiseringspijplijn of aangepaste toepassing.

Zie Aangepaste grafieken maken in de security data lake voor meer informatie over het maken van aangepaste grafieken.

Verificatie

De Graph REST API's maken gebruik van OAuth 2.0 bearer-tokenverificatie. Als u de API's wilt aanroepen, haalt u een toegangstoken op van Microsoft Entra ID en neemt u dit op in de Authorization header van elke aanvraag.

Een toegangstoken ophalen

  1. Registreer een toepassing in Microsoft Entra ID of gebruik een bestaande app-registratie. Zie Een toepassing registreren voor meer informatie.
  2. Ververleent de toepassing de vereiste machtigingen voor Microsoft Defender XDR.
  3. Een toegangstoken aanvragen met behulp van de OAuth 2.0-clientreferentiestroom of namens een aangemelde gebruiker.

Het token opnemen in aanvragen

Voeg het token toe aan de Authorization header van elke API-aanvraag:

Authorization: Bearer <access_token>

Basis-URL

Alle Graph REST API-eindpunten gebruiken de volgende basis-URL:

https://api.securityplatform.microsoft.com

Lijstgrafieken

Alle aangepaste grafieken weergeven die beschikbaar zijn in uw tenant.

Verzoek

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

Er is geen aanvraagtekst vereist.

Antwoord

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

Antwoordeigenschappen

Eigenschap Type Beschrijving
name Tekenreeks De naam van het grafiekexemplaren.
mapFileName Tekenreeks De naam van het kaartbestand dat is gekoppeld aan de grafiek.
mapFileVersion Tekenreeks De versie van het toewijzingsbestand.
graphDefinitionName Tekenreeks De naam van de grafiekdefinitie die wordt gebruikt om dit exemplaar te bouwen.
graphDefinitionVersion Tekenreeks De versie van de grafiekdefinitie.
refreshFrequency Tekenreeks Hoe vaak de grafiekgegevens worden vernieuwd.
createTime Tekenreeks Wanneer het grafiekexemplaren is gemaakt.
lastUpdateTime Tekenreeks Wanneer het grafiekexemplaren voor het laatst is bijgewerkt.
lastSnapshotTime Tekenreeks De tijdstempel van de meest recente momentopname van gegevens.
lastSnapshotRequestTime Tekenreeks Wanneer de laatste momentopname is aangevraagd.
instanceStatus Tekenreeks De huidige status van het grafiekexemplaren.

Antwoordstatuscodes

Statuscode Beschrijving
200 Akkoord De lijst is opgehaald.

Query's uitvoeren op een grafiek

Een query uitvoeren op een aangepaste grafiek met behulp van Graph Query Language (GQL). Zie GQL-verwijzing voor Microsoft Sentinel grafiek voor meer informatie over GQL.

Opmerking

{graphName} verwijst naar de name van een grafiek die wordt geretourneerd uit de lijstbewerking.

Verzoek

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

Aanvraagtekst

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

Eigenschappen van aanvraagbody

Eigenschap Type Vereist Beschrijving
query Tekenreeks Ja De GQL-query die moet worden uitgevoerd.
queryLanguage Tekenreeks Ja De querytaal. Moet zijn GQL.
responseFormats Tekenreeksmatrix Nee Hiermee bepaalt u de indeling van het queryantwoord. Accepteert een of beide van de volgende waarden: Table, Graph. De standaardinstelling is Table als deze niet is opgegeven.

Antwoordindelingen

De responseFormats eigenschap bepaalt de structuur van het antwoord:

Formaat Beschrijving
Table Retourneert onbewerkte tabelgegevens (standaard indien niet opgegeven).
Graph Retourneert grafiekgestructureerde gegevens met knooppunten en randen.

U kunt een of beide indelingen aanvragen:

  • ["Table"] - Retourneert alleen tabelindeling.
  • ["Graph"] - Retourneert alleen de grafiekindeling.
  • ["Table", "Graph"] - Retourneert beide indelingen in het antwoord.

Voorbeeld: Basisquery

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

Voorbeeld: Query uitvoeren met beide antwoordindelingen

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

Voorbeeldantwoord (beide indelingen)

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

Antwoordstatuscodes

Statuscode Beschrijving
200 Akkoord De query is uitgevoerd.
404 Niet gevonden Het opgegeven grafiekexemplaren bestaat niet.

Voorbeeld van foutreactie

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

Volgende stappen

  • Laatst bijgewerkt om