カスタム グラフ用の Graph REST API (プレビュー)

Graph REST API を使用すると、Microsoft Sentinel データ レイク内のカスタム グラフの一覧表示とクエリを実行できます。 これらの API を使用して、任意の HTTP クライアント、オートメーション パイプライン、またはカスタム アプリケーションからカスタム グラフをプログラムで操作します。

カスタム グラフの作成の詳細については、「 セキュリティ データ レイクでカスタム グラフを作成する」を参照してください。

認証

Graph REST API では、OAuth 2.0 ベアラー トークン認証が使用されます。 API を呼び出すには、Microsoft Entra IDからアクセス トークンを取得し、各要求のAuthorization ヘッダーに含めます。

アクセス トークンを取得する

  1. アプリケーションをMicrosoft Entra IDに登録するか、既存のアプリ登録を使用します。 詳細については、「 アプリケーションの登録」を参照してください。
  2. アプリケーションにMicrosoft Defender XDRに必要なアクセス許可を付与します。
  3. OAuth 2.0 クライアント資格情報フローを使用するか、サインインしているユーザーの代わりにアクセス トークンを要求します。

要求にトークンを含める

すべての API 要求の Authorization ヘッダーにトークンを追加します。

Authorization: Bearer <access_token>

ベース URL

すべての Graph REST API エンドポイントでは、次の基本 URL が使用されます。

https://api.securityplatform.microsoft.com

グラフを一覧表示する

テナントで使用できるすべてのカスタム グラフを一覧表示します。

要求

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

要求の本文は必要ありません。

応答

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

response のプロパティ

プロパティ タイプ 説明
name 文字列 グラフ インスタンスの名前。
mapFileName 文字列 グラフに関連付けられているマップ ファイルの名前。
mapFileVersion 文字列 マップ ファイルのバージョン。
graphDefinitionName 文字列 このインスタンスのビルドに使用されるグラフ定義の名前。
graphDefinitionVersion 文字列 グラフ定義のバージョン。
refreshFrequency 文字列 グラフ データが更新される頻度。
createTime 文字列 グラフ インスタンスが作成されたとき。
lastUpdateTime 文字列 グラフ インスタンスが最後に更新されたとき。
lastSnapshotTime 文字列 最新のデータ スナップショットのタイムスタンプ。
lastSnapshotRequestTime 文字列 最後のスナップショットが要求されたとき。
instanceStatus 文字列 グラフ インスタンスの現在の状態。

応答状態コード

状態コード 説明
200 OK（正常に処理されました） 正常に取得されたリスト。

グラフのクエリ

Graph クエリ言語 (GQL) を使用してカスタム グラフにクエリを実行します。 GQL の詳細については、「Microsoft Sentinel グラフの GQL リファレンス」を参照してください。

注:

{graphName} は、リスト操作から返されるグラフの name を指します。

要求

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

要求本文

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

要求本文のプロパティ

プロパティ タイプ 必須 説明
query 文字列 はい 実行する GQL クエリ。
queryLanguage 文字列 はい クエリ言語。 GQL である必要があります。
responseFormats 文字列配列 不要 クエリ応答の形式を制御します。 次の値のいずれかまたは両方を受け入れます: Table、 Graph。 既定値は、指定されていない場合は Table します。

応答形式

responseFormats プロパティは、応答の構造を制御します。

フォーマット 説明
Table 表形式の生データを返します (指定されていない場合は既定値)。
Graph ノードとエッジを含むグラフ構造データを返します。

一方または両方の形式を要求できます。

  • ["Table"] - テーブル形式のみを返します。
  • ["Graph"] - グラフ形式のみを返します。
  • ["Table", "Graph"] - 応答内の両方の形式を返します。

例: 基本クエリ

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

例: 両方の応答形式でクエリを実行する

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

サンプル応答 (両方の形式)

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

応答状態コード

状態コード 説明
200 OK（正常に処理されました） クエリが正常に実行されました。
404 が見つかりません 指定したグラフ インスタンスが存在しません。

エラー応答例

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

次の手順

  • 最終更新: