使用 GraphQL 查询 Magic Transit 端点健康检查结果

使用 GraphQL Analytics API 查询您账户的终端节点健康检查结果。magicEndpointHealthCheckAdaptiveGroups 数据集返回按您指定的维度和时间间隔聚合的探测结果。

将所有 GraphQL 查询作为 HTTP POST 请求发送到 https://api.cloudflare.com/client/v4/graphql。

前提条件

您需要以下各项来查询终端节点健康检查数据：

您的账户 ID。
具有 Account > Account Analytics > Read 权限的 API 令牌。有关详细信息，请参阅配置 Analytics API 令牌。

查询参数

以下参数是 filter 对象中一些最常用的参数：

参数	描述
`date_geq`	`YYYY-MM-DD` 格式的查询开始日期（例如，`2026-01-01`）。与基于日期的截断维度一起使用时，将返回此日期之后（含此日期）的结果。您还可以使用完整的 ISO 8601 时间戳（例如，`2026-01-01T00:00:00Z`）。
`date_leq`	（可选）查询的结束日期。使用与 `date_geq` 相同的格式。
`datetime_geq`	（可选） ISO 8601 格式的开始时间戳（例如，`2026-01-01T00:00:00Z`）。对于基于时间的截断维度，请用来代替 `date_geq`。
`datetime_leq`	（可选） ISO 8601 格式的结束时间戳。
`limit`	要返回的结果组的最大数量。

您还可以根据可用维度表中列出的任何维度进行过滤。在维度名称后附加运算符后缀以创建过滤器 —— 例如，endpoint_in 用于按终端节点列表进行过滤，或者 checkType_neq 用于排除特定的检查类型。使用不带后缀的维度名称可过滤等值情况。有关支持的运算符的完整列表，请参阅过滤。

可用维度

您可以在 dimensions 字段中查询以下维度：

维度	描述
`checkId`	已配置健康检查的唯一 ID。
`checkType`	健康检查的类型（例如，`icmp`）。
`endpoint`	正在检查的终端节点的 IP 地址。
`name`	配置时分配给健康检查的名称（如果未设置则可能为空）。
`date`	截断到天的时间戳事件。
`datetime`	完整的时间戳事件。
`datetimeMinute`	截断到分钟的时间戳事件。
`datetimeFiveMinutes`	截断到五分钟间隔的时间戳事件。
`datetimeFifteenMinutes`	截断到 15 分钟间隔的时间戳事件。
`datetimeHalfOfHour`	截断到 30 分钟间隔的时间戳事件。
`datetimeHour`	截断到小时的时间戳事件。

可用指标

指标	描述
`count`	组中健康检查事件的总数。
`sum.total`	发送的健康检查探测总数。
`sum.failures`	失败的健康检查探测数。
`avg.lossPercentage`	计算得出的平均丢包百分比 (0-100)。

API 调用

以下示例查询特定账户的终端节点健康检查结果，并返回以五分钟间隔聚合的探测计数。将 <ACCOUNT_ID> 替换为您的账户 ID，将 <API_TOKEN> 替换为您的 API 令牌。

echo '{ "query":
  "query GetEndpointHealthCheckResults($accountTag: string, $datetimeStart: string) {
    viewer {
      accounts(filter: {accountTag: $accountTag}) {
        magicEndpointHealthCheckAdaptiveGroups(
          filter: {
            datetime_geq: $datetimeStart
          }
          limit: 10
        ) {
          count
          dimensions {
            checkId
            checkType
            endpoint
            datetimeFiveMinutes
          }
          sum {
            failures
            total
          }
        }
      }
    }
  }",
  "variables": {
    "accountTag": "<ACCOUNT_ID>",
    "datetimeStart": "2026-01-21T00:00:00Z"
  }
}' | tr -d '\n' | curl --silent \
https://api.cloudflare.com/client/v4/graphql \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data @-

将输出通过管道传输到 jq，以格式化 JSON 响应以便于阅读：

... | curl --silent \
https://api.cloudflare.com/client/v4/graphql \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data @- | jq .

示例响应

{
  "data": {
    "viewer": {
      "accounts": [
        {
          "magicEndpointHealthCheckAdaptiveGroups": [
            {
              "count": 288,
              "dimensions": {
                "checkId": "90b478c7-bb51-4640-b94b-2c3050e9fa00",
                "checkType": "icmp",
                "datetimeFiveMinutes": "2026-01-21T12:00:00Z",
                "endpoint": "103.21.244.100"
              },
              "sum": {
                "failures": 0,
                "total": 288
              }
            },
            {
              "count": 288,
              "dimensions": {
                "checkId": "90b478c7-bb51-4640-b94b-2c3050e9fa00",
                "checkType": "icmp",
                "datetimeFiveMinutes": "2026-01-21T12:05:00Z",
                "endpoint": "103.21.244.100"
              },
              "sum": {
                "failures": 2,
                "total": 288
              }
            }
          ]
        }
      ]
    }
  },
  "errors": null
}

在此响应中，sum.total 是在间隔期间发送的探测数，sum.failures 是未收到回复的数量。failures 值为 0 表示在此期间终端节点完全可达。