GraphQL 将数据结构化为图。GraphQL 使用 schema 定义对象及其在数据图中的层次结构。你可以使用查询探索图的边以获取所需数据。这些查询必须遵守 schema 的结构。
node 及其 fields 是 GraphQL 查询的核心。node 是特定 type 的对象；type 指定构成对象的 field。
field 可以是另一个 node，适当的查询将包含嵌套元素。某些 node 类似函数，可接受参数以限制其作用范围。你可以在每个 node 应用筛选器。
针对 Cloudflare GraphQL schema 的典型查询由四个主要部分组成：
viewer— 是根 node，zones或accounts— 表示查询范围，即要查询的域区域或 account。viewer可以访问一个zones或accounts，或两者，- data node 或 dataset — 表示要查询的数据。
zones或accounts可能包含一个或多个 dataset。要了解更多关于发现 node 的信息，请参阅 introspection， - fieldset — dataset 的 field 或嵌套 field 集合。
向 Cloudflare GraphQL API 的查询必须通过 HTTP POST 请求发送，payload 为 JSON 格式，包含以下字段：
{
"query": "",
"variables": {}
}从上述结构来看，query field 必须包含格式化为单行字符串的 GraphQL 查询（意味着应去除/转义所有换行符），variables 是包含查询中使用的所有占位符值的对象。
在以下示例中，GraphQL 查询从 zone 范围的 firewallEventsAdaptive dataset 获取 2 个 WAF 事件的 datetime、action 以及作为 host field 的客户端请求 HTTP host。
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。我们通过将值放入 payload 的 variables field 来提供这些占位符的值。请注意，以下示例使用 UTC 时区，由字母 "Z" 表示。
{
"zoneTag": "<zone-tag>",
"start": "2020-08-03T02:07:05Z",
"end": "2020-08-03T17:07:05Z"
}有多种方式将查询发送到 Cloudflare GraphQL API。你可以使用喜欢的 GraphQL 客户端或 CLI 通过 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
}如前所述，查询可能包含一个或多个 node（dataset）。在 API 级别，数据提取将同时进行，但响应会延迟到所有 dataset 查询获得结果。如果执行过程中任何查询失败，整个查询将终止并返回错误。
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 的有用文章。