查询基础知识

使用GraphQL进行指标收集查询有几个基本方面。

GraphQL结构

GraphQL将数据结构为图形。 GraphQL使用模式来定义数据图中的对象及其层次结构。您可以通过查询来获取所需的数据，从而探索图的边缘。这些查询必须尊重模式的结构。

节点及其字段是GraphQL查询的核心。节点是一种特定类型的对象；该类型指定了构成该对象的字段。

字段可以是另一个节点，适当的查询将包含嵌套元素。有些节点看起来像函数，可以接受参数来限制其作用范围。您可以在每个节点上应用过滤器。

CloudflareGraphQL模式

针对 CloudflareGraphQL模式的典型查询由四个主要部分组成：

viewer- 根节点。
zones 或 "accounts--指明查询范围（要查询的域区域或账户）。 viewer 可以访问一个 "zones"或 "accounts"，也可以同时访问两个。
数据节点或数据集- 表示要查询的数据。zones 或 "accounts 可能包含一个或多个数据集。
字段组--"数据集的一组字段或嵌套字段。

GraphQL 的查询必须通过 HTTP发送，有效负载为JSON格式，包含以下字段：

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

从上述结构来看，“query 字段必须包含一个格式化为单行字符串的GraphQL查询（这意味着所有换行符都应去除或转义），而”variables 是一个对象，包含查询本身中使用的占位符的所有值。

单一数据集示例

在以下示例中，GraphQL从区域范围的 firewallEventsAdaptive 数据集中获取了2个WAF事件的 host 字段，分别为 datetime、action 和客户端请求 HTTP 主机。

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

该查询中有变量占位符："$tag、"$start 和 "$end。它通过将这些占位符放入有效载荷的 "variables 字段，在查询的同时提供这些占位符的值。

定义变量：

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

有多种方法可将您的查询发送到 CloudflareGraphQLAPI。您可以使用自己喜欢的GraphQL客户端或 CLI，使用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
}

在单个GraphQLAPI 请求中查询多个数据集

如前所述，查询可能包含一个或多个节点（数据集）。在应用程序接口层面，数据提取是同时进行的，但响应会延迟，直到所有数据集查询都收到结果。如果在执行过程中出现任何故障，整个查询将被终止，并返回错误信息。

一次尝试查询两个数据集的示例：

{
  viewer {
    zones(filter: { zoneTag: $tag }) {
      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
        }
      }
    }
  }
}

上一次查询的变量集：

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