Interfejsy API REST programu Graph dla wykresów niestandardowych (wersja zapoznawcza)

Interfejsy API REST programu Graph umożliwiają wyświetlanie list i wykonywanie zapytań dotyczących wykresów niestandardowych w usłudze data lake Microsoft Sentinel. Te interfejsy API umożliwiają programowe interakcje z wykresami niestandardowymi z dowolnego klienta HTTP, potoku automatyzacji lub aplikacji niestandardowej.

Aby uzyskać więcej informacji na temat tworzenia wykresów niestandardowych, zobacz Tworzenie wykresów niestandardowych w usłudze Security Data Lake.

Uwierzytelnianie

Interfejsy API REST programu Graph używają uwierzytelniania tokenu elementu nośnego OAuth 2.0. Aby wywołać interfejsy API, uzyskaj token dostępu z Microsoft Entra ID i dołącz go do Authorization nagłówka każdego żądania.

Uzyskiwanie tokenu dostępu

  1. Zarejestruj aplikację w Microsoft Entra ID lub użyj istniejącej rejestracji aplikacji. Aby uzyskać więcej informacji, zobacz Rejestrowanie aplikacji.
  2. Przyznaj aplikacji wymagane uprawnienia do Microsoft Defender XDR.
  3. Zażądaj tokenu dostępu przy użyciu przepływu poświadczeń klienta OAuth 2.0 lub w imieniu zalogowanego użytkownika.

Dołączanie tokenu do żądań

Dodaj token do nagłówka Authorization każdego żądania interfejsu API:

Authorization: Bearer <access_token>

Podstawowy adres URL

Wszystkie punkty końcowe interfejsu API REST programu Graph używają następującego podstawowego adresu URL:

https://api.securityplatform.microsoft.com

Wykresy listy

Wyświetl listę wszystkich wykresów niestandardowych dostępnych w dzierżawie.

Żądanie

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

Treść żądania nie jest wymagana.

Odpowiedzi

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

Właściwości odpowiedzi

Właściwość Typ Opis
name Ciąg Nazwa wystąpienia grafu.
mapFileName Ciąg Nazwa pliku mapy skojarzonego z wykresem.
mapFileVersion Ciąg Wersja pliku mapy.
graphDefinitionName Ciąg Nazwa definicji grafu użytej do skompilowania tego wystąpienia.
graphDefinitionVersion Ciąg Wersja definicji grafu.
refreshFrequency Ciąg Jak często dane grafu są odświeżane.
createTime Ciąg Po utworzeniu wystąpienia grafu.
lastUpdateTime Ciąg Kiedy wystąpienie grafu zostało ostatnio zaktualizowane.
lastSnapshotTime Ciąg Sygnatura czasowa najnowszej migawki danych.
lastSnapshotRequestTime Ciąg Kiedy zażądano ostatniej migawki.
instanceStatus Ciąg Bieżący stan wystąpienia grafu.

Kody stanu odpowiedzi

Kod stanu Opis
200 OK Lista została pomyślnie pobrana.

Wykonywanie zapytań dotyczących grafu

Wykonywanie zapytań względem grafu niestandardowego przy użyciu języka zapytań programu Graph (GQL). Aby uzyskać więcej informacji na temat GQL, zobacz GQL reference for Microsoft Sentinel graph (Dokumentacja GQL dla grafu Microsoft Sentinel).

Uwaga

{graphName} odnosi się do name wykresu zwróconego z operacji listy.

Żądanie

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

Treść żądania

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

Właściwości treści żądania

Właściwość Typ Wymagany Opis
query Ciąg Tak Zapytanie GQL do wykonania.
queryLanguage Ciąg Tak Język zapytań. Musi być GQL.
responseFormats Tablica ciągów Nie Steruje formatem odpowiedzi zapytania. Akceptuje jedną lub obie z następujących wartości: Table, Graph. Wartość domyślna to Table , jeśli nie zostanie określona.

Formaty odpowiedzi

Właściwość responseFormats kontroluje strukturę odpowiedzi:

Formatowanie Opis
Table Zwraca nieprzetworzone dane tabelaryczne (domyślne, jeśli nie zostały określone).
Graph Zwraca dane ustrukturyzowane na wykresie z węzłami i krawędziami.

Możesz zażądać jednego lub obu formatów:

  • ["Table"] — Zwraca tylko format tabeli.
  • ["Graph"] — Zwraca tylko format grafu.
  • ["Table", "Graph"] — Zwraca oba formaty w odpowiedzi.

Przykład: zapytanie podstawowe

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

Przykład: Zapytanie o oba formaty odpowiedzi

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

Przykładowa odpowiedź (oba formaty)

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

Kody stanu odpowiedzi

Kod stanu Opis
200 OK Zapytanie zostało wykonane pomyślnie.
Nie znaleziono 404 Określone wystąpienie grafu nie istnieje.

Przykład odpowiedzi na błąd

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

Następne kroki

  • Ostatnia aktualizacja o