← Analytics / analytics / graphql-api / getting-started

Základy dotazování

Struktura dotazu GraphQL

GraphQL strukturuje data jako graf. Objekty a jejich hierarchii v datovém grafu definuje pomocí schématu. Hrany grafu můžete procházet pomocí dotazů, kterými získáte potřebná data. Tyto dotazy musí respektovat strukturu schématu.

A uzel, za kterým následuje jeho pole, je jádrem dotazu GraphQL. Uzel je objekt konkrétního typ; typ určuje pole, ze kterých se objekt skládá.

Pole může být dalším uzlem, kde odpovídající dotaz obsahuje vnořené prvky. Některé uzly připomínají funkce, které přijímají argumenty omezující rozsah toho, na co se vztahují. Filtry lze použít na každém uzlu.

Schéma GraphQL Cloudflare

Typický dotaz vůči schématu Cloudflare GraphQL se skládá ze čtyř hlavních součástí:

viewer - je kořenovým uzlem,
zones nebo accounts - určují rozsah dotazu, tedy oblast nebo účet, který chcete dotazovat. Uzel viewer má přístup k jednomu zones nebo accounts, nebo obojí,
datový uzel nebo dataset - představují data, která chcete dotazovat. zones nebo accounts může obsahovat jeden nebo více datasetů. Další informace o vyhledávání uzlů najdete v introspekce,
sada polí - sada polí nebo vnořených polí uzlu dataset.

Dotaz na Cloudflare GraphQL API musí být odeslán prostřednictvím požadavku HTTP POST s payloadem ve formátu JSON, který se skládá z následujících polí:

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

Ve výše uvedené struktuře query pole musí obsahovat dotaz GraphQL ve formátu jeden řádek řetězec (což znamená, že všechny znaky nového řádku by měly být odstraněny nebo escapovány), pokud variables je objekt, který obsahuje všechny hodnoty použitých zástupných symbolů v samotném dotazu.

Příklad jediného datasetu

V následujícím příkladu dotaz GraphQL načte datetime, action, a HTTP hostitele klientského požadavku jako host pole 2 událostí WAF ze zóny firewallEventsAdaptive datová sada.

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

Ve výše uvedeném dotazu máme zástupné proměnné: $zoneTag, $start a $end. Hodnoty pro tyto proměnné doplňujeme spolu s dotazem tak, že je vložíme do variables pole payloadu. Všimněte si, že níže uvedené příklady používají časové pásmo UTC, označené písmenem "Z".

Sada proměnných

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

Dotaz do rozhraní Cloudflare GraphQL API můžete odeslat několika způsoby. Můžete použít svého oblíbeného klienta GraphQL nebo rozhraní CLI a odeslat požadavek přes curl. Máme k dispozici návod o používání klienta GraphiQL si také přečtěte návod, jak spustit dotaz pomocí curl zde.

Ukázka odpovědi na výše uvedený dotaz

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

Dotazování více datasetů v jednom požadavku GraphQL API

Jak již bylo zmíněno, dotaz může obsahovat jeden nebo více uzlů (datasetů). Na úrovni API by se extrakce dat prováděla současně, ale odpověď by byla zpožděna, dokud všechny dotazy na datasety nezískají výsledky. Pokud některý z nich během provádění selže, celý dotaz se ukončí a bude vrácena chyba.

Ukázkový dotaz pro dva datasety najednou

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

Sada proměnných pro výše uvedený dotaz

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

Ukázková odpověď na výše uvedený dotaz s proměnnými

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

Užitečné zdroje

Zde najdete několik užitečných článků o práci s Cloudflare Analytics API a GraphQL.

Specifické pro Cloudflare

Jak pomocí API zjistit svůj zoneTag