Rozhraní Graph REST API pro vlastní grafy (Preview)

Rozhraní Graph REST API umožňují vypsat a dotazovat se na vlastní grafy v Microsoft Sentinel Data Lake. Tato rozhraní API slouží k programové interakci s vlastními grafy z libovolného klienta HTTP, kanálu automatizace nebo vlastní aplikace.

Další informace o vytváření vlastních grafů najdete v tématu Vytváření vlastních grafů v jezeře Security Data Lake.

Ověřování

Rozhraní Graph REST API používají ověřování nosných tokenů OAuth 2.0. Pokud chcete volat rozhraní API, získejte přístupový token z Microsoft Entra ID a zahrňte ho do Authorization hlavičky každého požadavku.

Získání přístupového tokenu

  1. Zaregistrujte aplikaci v Microsoft Entra ID nebo použijte existující registraci aplikace. Další informace najdete v tématu Registrace aplikace.
  2. Udělte aplikaci požadovaná oprávnění pro Microsoft Defender XDR.
  3. Vyžádejte si přístupový token pomocí toku přihlašovacích údajů klienta OAuth 2.0 nebo jménem přihlášeného uživatele.

Zahrnout token do požadavků

Přidejte token do hlavičky Authorization každého požadavku rozhraní API:

Authorization: Bearer <access_token>

Základní adresa URL

Všechny koncové body rozhraní Graph REST API používají následující základní adresu URL:

https://api.securityplatform.microsoft.com

Výpis grafů

Vypíše všechny vlastní grafy dostupné ve vašem tenantovi.

Požadavek

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

Text požadavku se nevyžaduje.

Reakce

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

Vlastnosti odpovědi

Vlastnost Typ Popis
name String Název instance grafu.
mapFileName String Název mapového souboru přidruženého k grafu.
mapFileVersion String Verze souboru mapy.
graphDefinitionName String Název definice grafu použité k sestavení této instance.
graphDefinitionVersion String Verze definice grafu
refreshFrequency String Jak často se data grafu aktualizují.
createTime String Kdy byla vytvořena instance grafu.
lastUpdateTime String Kdy byla instance grafu naposledy aktualizována.
lastSnapshotTime String Časové razítko posledního snímku dat.
lastSnapshotRequestTime String Kdy byl požadován poslední snímek.
instanceStatus String Aktuální stav instance grafu.

Stavové kódy odpovědí

Stavový kód Popis
200 OK Seznam byl úspěšně načten.

Dotazování grafu

Dotazování vlastního grafu pomocí jazyka Graph Query Language (GQL) Další informace o GQL najdete v referenčních informacích ke GQL pro graf Microsoft Sentinel.

Poznámka

{graphName} odkazuje na name graf vrácený operací seznamu.

Požadavek

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

Text požadavku

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

Vlastnosti textu požadavku

Vlastnost Typ Povinný Popis
query String Ano Dotaz GQL, který se má spustit.
queryLanguage String Ano Dotazovací jazyk. Musí být GQL.
responseFormats Pole řetězců Ne Řídí formát odpovědi na dotaz. Přijímá jednu nebo obě následující hodnoty: Table, Graph. Výchozí hodnota je, Table pokud není zadána.

Formáty odpovědí

Vlastnost responseFormats řídí strukturu odpovědi:

Formát Popis
Table Vrátí nezpracovaná tabulková data (výchozí, pokud nejsou zadána).
Graph Vrátí data strukturovaná v grafu s uzly a hrany.

Můžete požádat o jeden nebo oba formáty:

  • ["Table"] – Vrátí pouze formát tabulky.
  • ["Graph"] – Vrátí pouze formát grafu.
  • ["Table", "Graph"] – Vrátí oba formáty v odpovědi.

Příklad: Základní dotaz

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

Příklad: Dotaz s oběma formáty odpovědí

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

Ukázková odpověď (oba formáty)

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

Stavové kódy odpovědí

Stavový kód Popis
200 OK Dotaz se úspěšně spustil.
404 Nenalezena Zadaná instance grafu neexistuje.

Příklad odpovědi na chybu

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

Další kroky

  • Poslední aktualizace v