GraphQL でウィジェットを作成する

この記事では、独自のダッシュボードを埋めるために使えるクエリ例を紹介します。

パラメーターとフィルター
時系列グラフ
アクティビティログ
Top N カード - 送信元
Top N カード - 宛先
TCP Flags
エグゼクティブサマリー

クエリの作成とテストは、次の流れで進めます。

GraphiQL ↗ アプリをインストールして設定し、Cloudflare Analytics GraphQL API へ認証します。Cloudflare はトークン認証を推奨します。詳細は Analytics API トークンを設定するを参照してください。
GraphiQL でクエリを組み立てます。GraphQL クライアントのイントロスペクションドキュメントで、利用できるノードを調べられます。クエリの詳細はクエリの基本を参照してください。
GraphiQL から実行するか、GraphQL API エンドポイントへ cURL リクエストのペイロードとして渡して、クエリをテストします。
アプリケーションでクエリを使い、ダッシュボードウィジェットへデータを供給します。

パラメーターとフィルター

これらの例では、クエリ対象の Cloudflare アカウントのアカウント ID を使います。変数（accountTag）として定義し、クエリから参照できます。

クエリは、対象の時間間隔を指定するフィルターも使います。フィルターは開始時刻と終了時刻で時間間隔を定義します。開始時刻と終了時刻を指定する属性は、クエリしたい期間によって異なります。フィルターの詳細はフィルタリングを参照してください。

次の例は、date_geq 以上かつ date_leq 以下の日付のデータをクエリします。

アカウントとクエリ時間間隔の設定json

{
	"accountTag": "{account-id}",
	"filter": {
		"AND": [{ "date_geq": "2020-01-19" }, { "date_leq": "2020-01-20" }]
	}
}

次の表は、Network Analytics のデータセット（ノード）と、各時間選択で使う datetimeDimension を示します。

データを集計して見たい場合は、Groups クエリノードを使います。たとえば ipFlows1mAttacksGroups データセットは、攻撃アクティビティの 1 分単位のロールアップレポートです。詳細はデータセットを参照してください。

時間の選択	クエリノード	datetimeDimension
過去 1 週間	ipFlows1dGroups	date
過去 1 か月	ipFlows1dGroups	date
24 時間	ipFlows1mGroups	datetimeFifteenMinutes
12 時間	ipFlows1mGroups	datetimeFifteenMinutes
6 時間	ipFlows1mGroups	datetimeFiveMinutes
30 分	ipFlows1mGroups	datetimeMinute
カスタム範囲	選択した範囲に依存	選択した範囲に依存

次の表は、異なる時間範囲を表すクエリノードで有効な開始・終了時刻の属性です。

クエリノード	開始日 / 時刻フィルター	終了日 / 時刻フィルター
ipFlows1mGroups	datetimeMinute_geq	datetimeMinute_leq
ipFlows1mAttacksGroups	date_geq	date_leq
ipFlows1hGroups	datetimeHour_geq	datetimeHour_leq
ipFlows1dGroups	date_geq	date_leq

時系列グラフ

ネットワーク分析の時系列グラフを作るには、次のクエリを使います。

時系列グラフgraphql

query ipFlowTimeseries(
	$accountTag: string
	$filter: AccountIpFlows1mGroupsFilter_InputObject
) {
	viewer {
		accounts(filter: { accountTag: $accountTag }) {
			ipFlows1mGroups(
				limit: 1000
				filter: $filter
				orderBy: datetimeMinute_ASC
			) {
				dimensions {
					timestamp: datetimeMinute
					attackMitigationType
					attackId
				}
				sum {
					bits
					packets
				}
			}
		}
	}
}

アクティビティログ

このクエリは、IP フロー内の攻撃トラフィックを 1 分単位でまとめたアクティビティログを返します。dimensions オブジェクトに列挙したフィールドでデータをグループ化します。

アクティビティログのクエリgraphql

query ipFlowEventLog(
	$accountTag: string
	$filter: AccountIpFlows1mAttacksGroupsFilter_InputObject
) {
	viewer {
		accounts(filter: { accountTag: $accountTag }) {
			ipFlows1mAttacksGroups(
				limit: 10
				filter: $filter
				orderBy: [min_datetimeMinute_ASC]
			) {
				dimensions {
					attackId
					attackDestinationIP
					attackDestinationPort
					attackMitigationType
					attackSourcePort
					attackType
				}
				avg {
					bitsPerSecond
					packetsPerSecond
				}
				min {
					datetimeMinute
					bitsPerSecond
					packetsPerSecond
				}
				max {
					datetimeMinute
					bitsPerSecond
					packetsPerSecond
				}
				sum {
					bits
					packets
				}
			}
		}
	}
}

Top N カード - 送信元

このクエリは、上位の送信元 IP に関するデータを返します。 limit パラメーターは、各ノードで返すレコード数を制御します。次のコードでは、強調表示した行が limit の設定箇所です。

Top N カードのクエリgraphql

query GetTopNBySource(
    $accountTag: string
    $filter: AccountIpFlows1mGroupsFilter_InputObject
    $portFilter: AccountIpFlows1mGroupsFilter_InputObject
  ) {
    viewer {
      accounts(filter: { accountTag: $accountTag }) {
        topNPorts: ipFlows1mGroups(
        limit: 5
        filter: $portFilter
        orderBy: [sum_(bits/packets)_DESC]
      ) {
        sum {
          count: (bits/packets)
        }
        dimensions {
          metric: sourcePort
          ipProtocol
        }
      }
      topNASN: ipFlows1mGroups(
        limit: 5
        filter: $filter
        orderBy: [sum_(bits/packets)_DESC]
      ) {
        sum {
          count: (bits/packets)
        }
        dimensions {
          metric: sourceIPAsn
          description: sourceIPASNDescription
        }
      }
        topNIPs: ipFlows1mGroups(
        limit: 5
        filter: $filter
        orderBy: [sum_(bits/packets)_DESC]
      ) {
        sum {
          count: (bits/packets)
        }
        dimensions {
          metric: sourceIP
        }
      }
        topNColos: ipFlows1mGroups(
          limit: 10
          filter: $filter
          orderBy: [sum_(bits/packets)_DESC]
        ) {
          sum {
            count: (bits/packets)
          }
          dimensions {
            metric: coloCity
            coloCode
          }
        }
        topNCountries: ipFlows1mGroups(
          limit: 10
          filter: $filter
          orderBy: [sum_(bits/packets)_DESC]
        ) {
          sum {
            count: (bits/packets)
          }
          dimensions {
            metric: coloCountry
          }
        }
        topNIPVersions: ipFlows1mGroups(
          limit: 2
          filter: $filter
          orderBy: [sum_(bits/packets)_DESC]
        ) {
          sum {
            count: (bits/packets)
          }
          dimensions {
            metric: ipVersion
          }
        }
      }
    }
  }

Top N カード - 宛先

このクエリは、上位の宛先 IP に関するデータを返します。limit パラメーターは返すレコード数を制御します。次のコードでは、強調表示した行が上位 5 件を返すことを示しています。

Top N カード - 宛先graphql

query GetTopNByDestination(
    $accountTag: string
    $filter: AccountIpFlows1mGroupsFilter_InputObject
    $portFilter: AccountIpFlows1mGroupsFilter_InputObject
  ) {
    viewer {
      accounts(filter: { accountTag: $accountTag }) {
        topNIPs: ipFlows1mGroups(
          filter: $filter
          limit: 5
          orderBy: [sum_(bits/packets)_DESC]
        ) {
          sum {
            count: (bits/packets)
          }
          dimensions {
            metric: destinationIP
          }
        }
        topNPorts: ipFlows1mGroups(
          filter: $portFilter
          limit: 5
          orderBy: [sum_(bits/packets)_DESC]
        ) {
          sum {
            count: (bits/packets)
          }
          dimensions {
            metric: destinationPort
            ipProtocol
          }
        }
      }
    }
  }

TCP Flags

このクエリは、IP フローの 1 分単位ロールアップから TCP パケット数を取り出し、TCP フラグの値で結果をグループ化します。limit: 8 で上位 8 件を表示し、降順で並べます。

TCP データを見たいことを示すには、フィルターへ次の行を追加します。

{ "ipProtocol": "TCP" }

TCP Flags のクエリgraphql

query GetTCPFlags(
    $accountTag: string
    $filter: AccountIpFlows1mGroupsFilter_InputObject
  ) {
    viewer {
      accounts(filter: { accountTag: $accountTag }) {
        tcpFlags: ipFlows1mGroups(
          filter: $filter
          limit: 8
          orderBy: [sum_(bits/packets)_DESC]
        ) {
          sum {
            count: (bits/packets)
          }
          dimensions {
            tcpFlags
          }
        }
      }
    }
  }

エグゼクティブサマリー

エグゼクティブサマリーのクエリは、全体のアクティビティを要約します。そのため、選択した時間間隔だけでフィルターし、分析に適用したほかのフィルターは無視します。調べたい時間間隔と、アカウントが見ているトラフィックの種類に応じて、使うクエリを変えます。

時間間隔が絶対指定の場合（例：3 月 25 日 09:00 から 3 月 25 日 17:00）、その時間内の攻撃をクエリします。時間間隔に適切なクエリノード（例：ipFlows1dGroups）を使います。

GetPreviousAttacks クエリ - 過去の攻撃を取得graphql

query GetPreviousAttacks($accountTag: string, $filter: filter) {
  viewer {
    accounts(filter: {accountTag: $accountTag}) {
      ${queryNode}(limit: 1000, filter: $filter) {
        dimensions {
          attackId
        }
        sum {
          packets
          bits
        }
      }
    }
  }
}

時間間隔が現在時刻からの相対指定の場合（例：過去 24 時間、過去 30 分）、ipFlows1mGroup ノードをクエリし、過去 5 分以内に攻撃があったかを確認します。過去 5 分以内の攻撃は進行中として扱い、Activity Log は Present を表示します。クエリレスポンスには、進行中の攻撃の attackID 値が列挙されます。

GetOngoingAttackIds クエリ - 進行中の攻撃を確認graphql

query GetOngoingAttackIds($accountTag: string, $filter: filter) {
	viewer {
		accounts(filter: { accountTag: $accountTag }) {
			ipFlows1mGroups(limit: 1000, filter: $filter) {
				dimensions {
					attackId
				}
			}
		}
	}
}

進行中の攻撃がある場合は、前のクエリの attackID 値でフィルターして ipFlows1mAttacksGroups ノードをクエリします。次のクエリは、ビットレートとパケットレートの最大値を返します。

GetOngoingAttacks クエリ - 進行中の攻撃データを取得graphql

query GetOngoingAttacks($accountTag: string, $filter: filter) {
	viewer {
		accounts(filter: { accountTag: $accountTag }) {
			ipFlows1mAttacksGroups(limit: 1000, filter: $filter) {
				dimensions {
					attackId
				}
				max {
					bitsPerSecond
					packetsPerSecond
				}
			}
		}
	}
}

進行中の攻撃がない場合は、GetPreviousAttacks クエリを使い、絶対時間間隔内の攻撃データを表示します。