INTEGRITY Документация

← Аналитика / analytics / graphql-api / tutorials

С помощью GraphQL создавайте виджеты

В этой статье приведены примеры запросов, которые можно использовать для наполнения своего дашборда.

Чтобы создавать и тестировать запросы, используйте следующий порядок действий:

Параметры и фильтры

В этих примерах используется ID аккаунта Cloudflare, к которому выполняется запрос. Его можно определить как переменную (accountTag) и ссылаться на неё в своих запросах.

Запросы также используют фильтр, чтобы указать нужный временной интервал. Фильтр определяет интервал с помощью времени начала и окончания. Атрибуты для указания времени начала и окончания различаются в зависимости от периода, который вы хотите запросить. См. Фильтрация , где приведены дополнительные сведения о фильтрах.

Следующий пример запрашивает данные с датой больше или равной date_geq и меньше или равно date_leq:

Настройки временного интервала аккаунта и запроса
{
	"accountTag": "{account-id}",
	"filter": {
		"AND": [{ "date_geq": "2020-01-19" }, { "date_leq": "2020-01-20" }]
	}
}

В этой таблице перечислены наборы данных (узлы) Network Analytics и datetimeDimension который следует использовать при запросе данных за выбранный период.

Если нужно агрегированное представление данных, используйте Groups узлы запроса. Например, ipFlows1mAttacksGroups набор данных содержит сводные отчёты по активности атак с разбивкой по минутам. Подробнее см. в Наборы данных.

Выбор времениУзел QuerydatetimeDimension
Прошлая неделяipFlows1dGroupsdate
Прошлый месяцipFlows1dGroupsdate
24 часаipFlows1mGroupsdatetimeFifteenMinutes
12 часовipFlows1mGroupsdatetimeFifteenMinutes
6 часовipFlows1mGroupsdatetimeFiveMinutes
30 минipFlows1mGroupsdatetimeMinute
Custom rangeЗависит от выбранного диапазонаЗависит от выбранного диапазона

В таблице ниже перечислены атрибуты начала и окончания времени, допустимые для узлов запроса, которые представляют разные временные диапазоны.

Узел QueryФильтр начального дня и времениФильтр конечной даты и времени
ipFlows1mGroupsdatetimeMinute_geqdatetimeMinute_leq
ipFlows1mAttacksGroupsdate_geqdate_leq
ipFlows1hGroupsdatetimeHour_geqdatetimeHour_leq
ipFlows1dGroupsdate_geqdate_leq

График временного ряда

С помощью следующего запроса постройте график временного ряда в Network Analytics:

График временного ряда
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
				}
			}
		}
	}
}

Activity log

Этот запрос возвращает журнал активности с поминутными сводками трафика атак в IP-потоках. Запрос группирует данные по полям, перечисленным в dimensions объект.

Запрос Activity log
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
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 параметр управляет количеством возвращаемых записей. В следующем коде выделенные строки показывают, что запрос возвращает пять наибольших результатов.

Карточки Top N: Назначение
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

Этот запрос извлекает количество пакетов TCP из поминутных сводок IP-потоков и группирует результаты по значению флага TCP. Он использует limit: 8 чтобы показать восемь лучших результатов, отсортированных по убыванию.

Чтобы отобразить данные TCP, добавьте в фильтр следующую строку:

{ "ipProtocol": "TCP" }
Запрос флагов TCP
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
          }
        }
      }
    }
  }

Сводный отчёт

Запрос сводного отчёта обобщает общую активность, поэтому фильтрует данные только по выбранному временному интервалу и игнорирует все остальные фильтры, применённые в аналитике. Используйте разные запросы в зависимости от того, какой временной интервал вы хотите изучить и какой трафик наблюдается на аккаунте.

Если временной интервал абсолютный, например с 09:00 25 марта до 17:00 25 марта, выполните запрос на атаки за этот период. Используйте подходящий узел запроса, например ipFlows1dGroups, для временного интервала.

Запрос GetPreviousAttacks: получение данных о предыдущих атаках
query GetPreviousAttacks($accountTag: string, $filter: filter) {
  viewer {
    accounts(filter: {accountTag: $accountTag}) {
      ${queryNode}(limit: 1000, filter: $filter) {
        dimensions {
          attackId
        }
        sum {
          packets
          bits
        }
      }
    }
  }
}

Если временной интервал относительный, например последние 24 часа или последние 30 минут, выполните запрос к ipFlows1mGroup узел, чтобы проверить, были ли атаки за последние пять минут. Атаки за последние пять минут считаются текущими: журнал активности отображает Present. В ответе на запрос перечислены attackID значения текущих атак.

Запрос GetOngoingAttackIds: проверка текущих атак
query GetOngoingAttackIds($accountTag: string, $filter: filter) {
	viewer {
		accounts(filter: { accountTag: $accountTag }) {
			ipFlows1mGroups(limit: 1000, filter: $filter) {
				dimensions {
					attackId
				}
			}
		}
	}
}

Если атаки происходят в данный момент, выполните запрос к ipFlows1mAttacksGroups узел, отфильтровав его с помощью attackID значения из предыдущего запроса. Приведённый ниже запрос возвращает максимальную скорость в битах и пакетах.

Запрос GetOngoingAttacks: получение данных о текущих атаках
query GetOngoingAttacks($accountTag: string, $filter: filter) {
	viewer {
		accounts(filter: { accountTag: $accountTag }) {
			ipFlows1mAttacksGroups(limit: 1000, filter: $filter) {
				dimensions {
					attackId
				}
				max {
					bitsPerSecond
					packetsPerSecond
				}
			}
		}
	}
}

Если атаки в данный момент не происходят, используйте GetPreviousAttacks запрос для отображения данных об атаках за абсолютный интервал времени.