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

Основы запросов

Структура запроса GraphQL

GraphQL представляет данные в виде графа. Объекты и их иерархию в графе данных GraphQL определяет с помощью схемы. Рёбра графа можно исследовать с помощью запросов, которые возвращают нужные данные. Такие запросы должны соответствовать структуре схемы.

A узел, за которым следует его поля, лежит в основе запроса GraphQL. Узел представляет собой объект определённого тип; тип определяет поля, из которых состоит объект.

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

Схема GraphQL Cloudflare

Типичный запрос к схеме Cloudflare GraphQL состоит из четырёх основных компонентов:

viewer - является корневым узлом,
zones или accounts - определяют область действия запроса, то есть домен или учётную запись, к которым выполняется запрос. Узел viewer может обращаться к одному zones или accounts, или оба сразу,
узел данных или dataset - представляют данные, которые нужно запросить. zones или accounts может содержать один или несколько датасетов. Подробнее о поиске узлов см. в интроспекция,
набор полей - набор полей или вложенных полей узла dataset.

Запрос к Cloudflare GraphQL API нужно отправлять с помощью HTTP-запроса POST с полезной нагрузкой в формате JSON, которая состоит из следующих полей:

{
	"query": "",
	"variables": {}
}

В приведённой выше структуре query поле должно содержать запрос GraphQL в формате одна строка строку (это означает, что все символы новой строки должны быть удалены или экранированы), если variables является объектом, который содержит все значения используемых заполнителей в самом запросе.

Пример одного набора данных

В следующем примере запрос GraphQL получает datetime, action, а также HTTP-хост клиентского запроса как host поле 2 событий WAF в пределах зоны firewallEventsAdaptive набор данных.

Запрос GraphQL

query ASingleDatasetExample($zoneTag: string, $start: Time, $end: Time) {
	viewer {
		zones(filter: { zoneTag: $zoneTag }) {
			firewallEventsAdaptive(
				filter: { datetime_gt: $start, datetime_lt: $end }
				limit: 2
				orderBy: [datetime_DESC]
			) {
				action
				datetime
				host: clientRequestHTTPHost
			}
		}
	}
}

В запросе выше используются переменные заполнители: $zoneTag, $start и $end. Значения для этих заполнителей передаются вместе с запросом и указываются в variables поле полезной нагрузки. Обратите внимание, что в примерах ниже используется часовой пояс UTC, обозначаемый буквой "Z".

Набор переменных

{
	"zoneTag": "<zone-tag>",
	"start": "2020-08-03T02:07:05Z",
	"end": "2020-08-03T17:07:05Z"
}

Отправить запрос в Cloudflare GraphQL API можно несколькими способами. Вы можете использовать любимый клиент GraphQL или интерфейс командной строки, чтобы отправить запрос через curl. У нас есть практическое руководство об использовании клиента GraphiQL, также ознакомьтесь с руководством о том, как выполнить запрос с помощью curl здесь.

Пример ответа на запрос выше

{
	"data": {
		"viewer": {
			"zones": [
				{
					"firewallEventsAdaptive": [
						{
							"action": "log",
							"host": "cloudflare.guru",
							"datetime": "2020-08-03T17:07:03Z"
						},
						{
							"action": "log",
							"host": "cloudflare.guru",
							"datetime": "2020-08-03T17:07:01Z"
						}
					]
				}
			]
		}
	},
	"errors": null
}

Запрос нескольких наборов данных в одном запросе GraphQL API

Как уже упоминалось, запрос может содержать один или несколько узлов (наборов данных). На уровне API извлечение данных выполняется одновременно, но ответ будет задержан, пока все запросы к наборам данных не получат результаты. Если хотя бы один из них завершится с ошибкой во время выполнения, весь запрос будет прерван и вернётся ошибка.

Пример запроса сразу для двух наборов данных

query MultipleDatasetsExample(
	$zoneTag: string
	$start: Time
	$end: Time
	$ts: Date
) {
	viewer {
		zones(filter: { zoneTag: $zoneTag }) {
			last10Events: firewallEventsAdaptive(
				filter: { datetime_gt: $start, datetime_lt: $end }
				limit: 10
				orderBy: [datetime_DESC]
			) {
				action
				datetime
				host: clientRequestHTTPHost
			}
			top3DeviceTypes: httpRequestsAdaptiveGroups(
				filter: { date: $ts }
				limit: 10
				orderBy: [count_DESC]
			) {
				count
				dimensions {
					device: clientDeviceType
				}
			}
		}
	}
}

Набор переменных для запроса выше

{
	"zoneTag": "<zone-tag>",
	"start": "2022-10-02T00:26:49Z",
	"end": "2022-10-04T14:26:49Z",
	"ts": "2022-10-04"
}

Пример ответа на запрос с переменными выше

{
	"data": {
		"viewer": {
			"zones": [
				{
					"last10Events": [
						{
							"action": "block",
							"country": "TR",
							"datetime": "2022-10-04T08:41:09Z"
						},
						{
							"action": "block",
							"country": "TR",
							"datetime": "2022-10-04T08:41:09Z"
						},
						{
							"action": "block",
							"country": "RU",
							"datetime": "2022-10-04T01:09:36Z"
						},
						{
							"action": "block",
							"country": "US",
							"datetime": "2022-10-03T14:26:49Z"
						},
						{
							"action": "block",
							"country": "US",
							"datetime": "2022-10-03T14:26:46Z"
						},
						{
							"action": "block",
							"country": "CN",
							"datetime": "2022-10-02T23:51:26Z"
						},
						{
							"action": "block",
							"country": "TR",
							"datetime": "2022-10-02T23:39:41Z"
						},
						{
							"action": "block",
							"country": "TR",
							"datetime": "2022-10-02T23:39:41Z"
						}
					],
					"top3DeviceTypes": [
						{
							"count": 4580,
							"dimensions": {
								"device": "desktop"
							}
						}
					]
				}
			]
		}
	},
	"errors": null
}

Полезные материалы

Вот несколько полезных статей о работе с Cloudflare Analytics API и GraphQL.

Специфично для Cloudflare

Как найти свой zoneTag с помощью API