快速入门 · Cloudflare Analytics 文档

前提条件

要运行账户范围的查询，你需要一个账户标识符，以及对该账户具有 Account Analytics Read 权限的 API 令牌。包含 zoneTag 的查询需要每个命名 zone 的 Zone Analytics Read 权限，或其所属账户的 Account Analytics Read 权限。

SQL API 数据集代表不同的 Cloudflare 产品。某些数据集和字段需要额外的 API 令牌权限，以访问它们所暴露产品的数据。请包含计划查询的每个数据集和字段所需的权限。

Cloudflare 建议使用 API 令牌，因为你可以将每个令牌限制到特定资源。说明请参阅创建 API 令牌。

运行查询

向 SQL API 端点发送 POST 请求。将 SQL 语句及其参数作为 JSON 传递。

以下查询返回指定开始时间之后某个账户最常见的五种 HTTP 响应状态。将 <START_TIME> 替换为数据集保留期内最近的 ISO 8601 时间戳。

curl "https://api.cloudflare.com/client/v4/analytics/sql" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --data '{
    "query": "SELECT edgeResponseStatus AS status, COUNT(*) AS requests FROM events.httpRequests WHERE accountTag = $account AND timestamp >= $start GROUP BY edgeResponseStatus ORDER BY requests DESC LIMIT 5",
    "params": {
      "account": "<ACCOUNT_TAG>",
      "start": "<START_TIME>"
    }
  }'

成功响应具有以下结构：

{
	"data": [
		{
			"status": 200,
			"requests": 125430
		},
		{
			"status": 404,
			"requests": 8240
		},
		{
			"status": 301,
			"requests": 5175
		},
		{
			"status": 304,
			"requests": 3960
		},
		{
			"status": 500,
			"requests": 82
		}
	],
	"rows": 5,
	"statistics": {
		"elapsed_ms": 42,
		"rows_read": 250000,
		"bytes_read": 18000000
	}
}

data 数组为每个结果行包含一个对象。对象键与所选字段名或别名匹配。rows 值是返回的行数。statistics 对象描述数据存储执行的工作。

此响应形态适用于 ClickHouse 支持的数据集的默认输出。Log Explorer 和显式输出格式具有不同的响应形态。请参阅响应格式。

使用 Cloudflare CLI

Cloudflare CLI 提供 cf sql query。将 SQL 语句作为位置参数传递，然后提供恰好一个范围标志和下限时间边界：

cf sql query \
  'SELECT edgeResponseStatus AS status, COUNT(*) AS requests FROM events.httpRequests GROUP BY edgeResponseStatus ORDER BY requests DESC LIMIT 5' \
  --scope-account "<ACCOUNT_TAG>" \
  --time-since "<START_TIME>"

对于 zone 范围，使用 --scope-zone 代替 --scope-account。可以选择添加 --time-until。两个时间边界都是包含的。在提供对应 CLI 标志时，不要在 SQL 中包含租户或时间戳谓词。

有关请求选项和参数绑定，请参阅查询 API。