ダッシュボード・グラフ用の汎用 API 照会作成のヒント

汎用 API 照会およびダッシュボード・グラフをより簡単に作成するためのヒントは、特定のグラフ・タイプのデータ要件、返された JSON が配列でない場合の結果マッピング、および動的タイトルをカバーしています。

データ形式

呼び出される API は、ダッシュボードがデータを読み取ることができるようにするために、特定の JSON 形式でデータを返す必要があります。 API は、JSON 配列 (複数の結果がある場合) または JSON オブジェクト (1 つの結果のみがある場合) のいずれかを返します。返された JSON オブジェクトは、1 つのエレメントを含む JSON 配列に変換されます。

ほとんどの IBM® QRadar® API は、ダッシュボードが処理できる形式でデータを返します。アプリケーション API などの他の API では、ダッシュボードの結果マッピングを使用して、返された JSON オブジェクトの特定のキーを抽出することが必要になる場合があります。

表形式チャートのデータ要件

表形式のグラフの場合、API は、JSON オブジェクト (結果が 1 つしかない場合) または表形式データを表すエレメントの JSON 配列のいずれかを返す必要があります。例:

[{
      "rowstring": "Thanksgiving eCard Emails Distributing Malware",
      "category": "Threat Activity",
      "relevance": "25%",
      "href": "/app/href"
    }, {
      "title": "PyXie - RAT Written In Python",
      "category": "Threat Activity",
      "relevance": "25%",
      "href": "/app/href"
    }, ...

円グラフおよび単一系列の棒グラフのデータ要件

円グラフおよび単一系列棒グラフの場合、API は、JSON オブジェクト (結果が 1 つのみの場合) または少なくとも 1 つのラベルと 1 つの数値メトリックを含む JSON 配列のいずれかを返す必要があります。例:

[{
    "Country": "Europe",
    "Count": 97
  }, {
    "Country": "Middle East",
    "Count": 85
  }, {
    "Country": "North America",
    "Count": 83
  }, ...

時系列グラフのデータ要件

時系列グラフの場合、API は、有効な日付形式またはミリ秒形式を使用する時間ベースのメトリックを少なくとも 1 つ含む JSON オブジェクト (結果が 1 つのみの場合) または JSON 配列、および Y 軸にプロットする 1 つ以上の数値メトリックのいずれかを返す必要があります。データは時間順に並べる必要があります。例:

[{
    "date": "2020-02-18",
    "Phishing": 7.21,
    "C2": 82.67,
    "Malware": 272.05,
    "EarlyWarning": 448.32
  }, {
    "date": "2020-02-19",
    "Phishing": 7.47,
    "C2": 94.14,
    "Malware": 121.84,
    "EarlyWarning": 665.33
  }, {
    "date": "2020-02-20",
    "Phishing": 8.05,
    "C2": 92.35,
    "Malware": 120.71,
    "EarlyWarning": 736.9
  }, ...

地理分布図のデータ要件

散布グラフでは、座標を持つ geo_json キーと 1 つの数値メトリックを含む、文字列化された JSON オブジェクト (つまり、 JSON.stringify() JavaScript 関数を使用して変換されたオブジェクト) が必要です。例:

[{
    "sourceIP": "81.12.213.121",
    "geoSource": "{\"geo_json\":{\"coordinates\":[44.4354,26.1033],\"type\":\"Point\"}}",
    "geoDest": "{\"geo_json\":{\"coordinates\":[1.0,38.0],\"type\":\"Point\"}}",
    "eventCount": 50
  }, {
    "sourceIP": "59.154.60.0",
    "geoSource": "{\"geo_json\":{\"coordinates\":[-33.494,143.2104],\"type\":\"Point\"}}",
    "geoDest": "{\"geo_json\":{\"coordinates\":[53.3472,-6.2439],\"type\":\"Point\"}}",
    "eventCount": 60
  }, { ...

コロプレス地理グラフのデータ要件

コロプレス・グラフには、文字列化された JSON オブジェクト (つまり、 JSON.stringify() JavaScript 関数を使用して変換されたオブジェクト) が必要です。このオブジェクトには、国/地域名または国/地域の ISO-3 コードのいずれか、および 1 つの数値メトリックを持つ country キーが含まれています。例:

[{
    "sourceIP": "81.12.213.121",
    "geoCountry": "{\"country\":{\"confidence\":null,\"name\":\"Romania\",\"iso_code\":\"ROU\",\"geo_id\":798549}}",
    "eventCount": 50
  }, {
    "sourceIP": "59.154.60.0",
    "geoCountry": "{\"country\":{\"confidence\":null,\"name\":\"Australia\",\"iso_code\":\"AUS\",\"geo_id\":2077456}}",
    "eventCount": 60
  }, { ...

結果のマッピング

返された JSON 内のルート・オブジェクトがプロットしたい配列ではない場合は、「結果マッピング (Results mapping)」フィールドを使用して、プロットしたい関連データが含まれるキーを定義します。

結果マッピングでは、JSON ドット (.) 演算子を使用して、ルート・ノードから開始して文書をトラバースします。例えば、以下の JSON オブジェクトでは、関連データは table ルート・ノードの下にある items キーの下にあります。ダッシュボードが items 配列を読み取り、他のすべてのキーを無視するには、 table.items マッピングが必要です。

{
  "table": {
    "title": "Top 5 most relevant threats",
    "columns": [{
      "title": "Threat",
      "key": "title",
      "subkey": "category",
      "width": 75
    }, {
      "title": "X-Force Threat Score",
      "key": "relevance",
      "width": 0
    }],
    "items": [{
      "title": "Thanksgiving eCard Emails Distributing Malware",
      "category": "Threat Activity",
      "relevance": "25%",
      "href": "/app/href"
    }, {
      "title": "PyXie - RAT Written In Python",
      "category": "Threat Activity",
      "relevance": "25%",
      "href": "/app/href"
    }, { ...

返された JSON オブジェクト自体が配列の場合 (ほとんどのデフォルト QRadar API の場合)、マッピングは必要ありません。ただし、 QRadar アプリケーションでは、返される JSON の形式が異なる場合があります。

動的タイトル

データの現在の状態を記述する動的タイトルを使用して、ビュー名をオーバーライドできます。例えば、グラフのタイトルは「ワールド・悪意のあるアクティビティー: < threat_name>」であり、脅威の名前は時間の経過とともに変化します。動的タイトルには、以下の例に示すように、動的タイトル名を持つ title キーが必要です。

{
  "title": "Worldwide Malicious Activity: emotet",
  "items": [{
    "sourceIP": "81.12.213.121",
    "geoSource": "{\"geo_json\":{\"coordinates\":[44.4354,26.1033],\"type\":\"Point\"}}",
    "geoDest": "{\"geo_json\":{\"coordinates\":[1.0,38.0],\"type\":\"Point\"}}",
    "geoCountry": "{\"country\":{\"confidence\":null,\"name\":\"Romania\",\"iso_code\":\"ROU\",\"geo_id\":798549}}",
    "eventCount": 50
  }, { ...

title キーがルート・ノードの下にある場合は、「タイトル・マッピング」フィールドを使用します。タイトル・マッピングでは、JSON ドット (.) 演算子を使用して、ルート・ノードから開始して文書をトラバースします。例えば、 title キーが table ルート・ノードの下にある場合は、 table.title マッピングを指定します。