监控 API

Zaraz 监控 API 允许用户通过 GraphQL Analytics API 检索有关 Zaraz 事件的详细数据。使用此 API，您可以监控事件、页面浏览量、触发器、操作和服务器端请求状态，包括任何错误和成功。API 提供的数据与仪表板中 Zaraz 监控页面显示的数据一致，但通过 API 您可以以编程方式查询数据，以便在出现意外偏差时创建告警和通知。

首先，您需要按照 API 令牌身份验证指南生成 Analytics API 令牌。

关键实体

监控 API 包含以下核心实体，各自提供不同的洞察：

zarazTrackAdaptiveGroups：包含有关 Zaraz 事件的数据，例如事件计数和时间戳。
zarazActionsAdaptiveGroups：提供有关 Zaraz Actions 的信息。
zarazTriggersAdaptiveGroups：跟踪有关 Zaraz Triggers 的数据。
zarazFetchAdaptiveGroups：捕获服务器端请求数据，包括 URL 以及 Zaraz 发出的第三方请求返回的状态码。

GraphQL 查询示例

您可以使用上述数据集构建任何所需查询，以下是一些可以使用的查询示例。

按时间分组查询 Zaraz 事件计数。

query ZarazEvents(
	$zoneTag: string
	$limit: uint64!
	$start: Time
	$end: Time
	$orderBy: ZoneZarazTrackAdaptiveGroupsOrderBy!
) {
	viewer {
		zones(filter: { zoneTag: $zoneTag }) {
			data: zarazTrackAdaptiveGroups(
				limit: $limit
				filter: { datetimeHour_geq: $start, datetimeHour_leq: $end }
				orderBy: [$orderBy]
			) {
				count
				dimensions {
					ts: datetimeHour
				}
			}
		}
	}
}

按时间分组查询 Zaraz 加载次数。

query ZarazLoads(
	$zoneTag: string
	$limit: uint64!
	$start: Date
	$end: Date
	$orderBy: ZoneZarazTriggersAdaptiveGroupsOrderBy!
) {
	viewer {
		zones(filter: { zoneTag: $zoneTag }) {
			data: zarazTriggersAdaptiveGroups(
				limit: $limit
				filter: { date_geq: $start, date_leq: $end, triggerName: Pageview }
				orderBy: [$orderBy]
			) {
				count
				dimensions {
					ts: date
				}
			}
		}
	}
}

查询 Zaraz 处理的每个触发器的总执行次数。

query ZarazTriggers(
	$zoneTag: string
	$limit: uint64!
	$start: Date
	$end: Date
) {
	viewer {
		zones(filter: { zoneTag: $zoneTag }) {
			data: zarazTriggersAdaptiveGroups(
				limit: $limit
				filter: { date_geq: $start, date_leq: $end }
				orderBy: [count_DESC]
			) {
				count
				dimensions {
					name: triggerName
				}
			}
		}
	}
}

按时间和 URL 分组查询 400 服务器端响应的计数。

query ErroneousResponses(
	$zoneTag: string
	$limit: uint64!
	$start: Time
	$end: Time
	$orderBy: ZoneZarazFetchAdaptiveGroupsOrderBy!
) {
	viewer {
		zones(filter: { zoneTag: $zoneTag }) {
			data: zarazFetchAdaptiveGroups(
				limit: $limit
				filter: {
					datetimeHour_geq: $start
					datetimeHour_leq: $end
					url_neq: ""
					status: 400
				}
				orderBy: [$orderBy]
			) {
				count
				dimensions {
					ts: datetimeHour
					name: url
				}
			}
		}
	}
}

变量示例

{
	"zoneTag": "d6dfdf32c704a77ac227243a5eb5ca61",
	"start": "2025-01-01T00:00:00Z",
	"end": "2025-01-30T00:00:00Z",
	"limit": 10000,
	"orderBy": "datetimeHour_ASC"
}

请务必将 zoneTag 自定义为匹配您的特定 zone，并设置所需的开始和结束日期

参数说明

zoneTag：您的 Cloudflare zone 的唯一标识符。
limit：返回结果的最大数量。
start 和 end：以 ISO 8601 格式定义查询的日期范围。
orderBy：确定排序顺序，例如按升序或降序日期时间。

`curl` 请求示例

使用此 curl 命令查询 Zaraz 监控 API，获取 Zaraz 处理的事件数量。将 $TOKEN 替换为您的 API 令牌，将 $ZONE_TAG 替换为您的 zone 标签，并根据需要调整开始和结束日期。

curl -X POST https://api.cloudflare.com/client/v4/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "query": "query AllEvents($zoneTag: String!, $limit: Int!, $start: Date, $end: Date, $orderBy: [ZoneZarazTriggersAdaptiveGroupsOrderBy!]) { viewer { zones(filter: { zoneTag: $zoneTag }) { data: zarazTrackAdaptiveGroups( limit: $limit filter: { datetimeHour_geq: $start datetimeHour_leq: $end } orderBy: [$orderBy] ) { count dimensions { ts: datetimeHour } } } } }",
    "variables": {
      "zoneTag": "$ZONE_TAG",
      "start": "2025-01-01T00:00:00Z",
      "end": "2025-01-30T00:00:00Z",
      "limit": 10000,
      "orderBy": "datetimeHour_ASC"
    }
  }'

`curl` 组件说明

Authorization：Authorization 标头需要 Bearer 令牌。将 $TOKEN 替换为您的实际 API 令牌。
Content-Type：设置为 application/json 以指示 JSON 负载。
Data Payload：此负载包含 GraphQL 查询和变量参数，例如 zoneTag、start、end、limit 和 orderBy。

此 curl 示例将返回包含指定日期范围内事件计数和时间戳的 JSON 响应。根据用例需要修改 variables 值。

其他资源

有关可用字段、筛选条件以及 Zaraz 监控 API 查询的更多自定义选项，请参阅完整的 GraphQL Analytics API 文档。