请求日志 · Cloudflare Logs docs

端点

Logpull API 支持以下三个端点：

GET /logs/received - 根据指定参数返回 HTTP 请求日志数据
GET /logs/received/fields - 返回所有可用日志字段的列表
GET /logs/rayids/{ray_id} - 返回与 {ray_id} 匹配的 HTTP 请求日志数据

必需的身份验证标头

所有端点调用都需要以下标头：

X-Auth-Email - 与域名关联的 Cloudflare 账户电子邮件地址
X-Auth-Key - Cloudflare API 密钥

或者，也可以使用具有 Logs Read 权限的 API token 进行身份验证：

Authorization: Bearer <API_TOKEN>

参数

API 期望在 GET 请求查询字符串中提供端点参数。以下为示例格式：

logs/received

https://api.cloudflare.com/client/v4/zones/{zone_id}/logs/received?start=<unix|rfc3339>&end=<unix|rfc3339>[&count=<int>][&sample=<float>][&fields=<FIELDS>][&timestamps=<string>][&CVE-2021-44228=<boolean>]

logs/rayids/{ray_id}

https://api.cloudflare.com/client/v4/zones/{zone_id}/logs/rayids/{ray_id}?[&fields=<FIELDS>][&timestamps=<string>]

下表描述可用的参数：

参数	说明	适用于	必需
start	- 包含该时间点 - 时间戳格式为 `UNIX`（默认为 UTC）、`UNIX Nano` 或 `rfc3339`。要在 URL 查询参数中指定 `rfc3339` 时区，需要对 URL 进行编码，例如 `start=2024-08-07T07:00:00%2B08:00&end=2024-08-07T07:01:00%2B08:00`。 - 必须不早于当前时间 7 天	/logs/received	是
end	- 不包含该时间点 - 格式与 start 相同 - 必须至少早于当前时间 1 分钟，且晚于 start	/logs/received	是
count	- 最多返回该数量的记录 - 若要返回所有记录，请勿包含此参数 - 结果未排序；因此重复请求可能返回不同数据 - 适用于返回的总记录数，而非采样记录数	/logs/received	否
sample	- 仅返回记录的样本 - 若要返回所有记录，请勿包含此参数 - 取值范围为 `0.0`（不含）到 `1.0`（含） - `sample=0.1` 表示返回全部记录的 10%（每 10 条中 1 条） - 结果是随机的；因此重复请求返回的结果数量可能不同	/logs/received	否
fields	- 要返回的字段的逗号分隔列表 - 若为空，则返回默认列表	/logs/received /logs/rayids	否
timestamps	- 时间戳字段的返回格式 - 可选值为：`unixnano`（默认）、`unix`、`rfc3339` - 对 `unix` 和 `unixnano` 返回整数时间戳，对 `rfc3339` 返回字符串	/logs/received /logs/rayids	否
CVE-2021-44228	- 针对 CVE-2021-44228 ↗ 的可选脱敏。此选项会将字符串 `${` 的每次出现替换为 `x{`。例如：`CVE-2021-44228=true`	/logs/received	否

使用 cURL 的示例 API 请求

logs/received

curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/logs/received?start=2017-07-18T22:00:00Z&end=2017-07-18T22:01:00Z&count=1&fields=ClientIP,ClientRequestHost,ClientRequestMethod,ClientRequestURI,EdgeEndTimestamp,EdgeResponseBytes,EdgeResponseStatus,EdgeStartTimestamp,RayID" \
--header "X-Auth-Email: <EMAIL>" \
--header "X-Auth-Key: <API_KEY>"

logs/rayids/{ray_id}

curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/logs/rayids/{ray_id}}?timestamps=rfc3339" \
--header "X-Auth-Email: <EMAIL>" \
--header "X-Auth-Key: <API_KEY>"

字段

除非在 fields 参数中指定，否则 API 返回一组有限的日志字段。此默认字段集可能随时更改。所有可用字段的列表位于：

https://api.cloudflare.com/client/v4/zones/{zone_id}/logs/received/fields

字段的指定顺序无关紧要，响应中的字段顺序也不固定。

使用 bash 子 shell 和 jq，您可以在不手动复制粘贴字段到请求中的情况下，下载包含所有可用字段的日志。例如：

FIELDS=$(curl https://api.cloudflare.com/client/v4/zones/{zone_id}/logs/received/fields \
--header "X-Auth-Email: <EMAIL>" \
--header "X-Auth-Key: <API_KEY>" \
| jq '. | to_entries[] | .key' -r | paste -sd "," -)

curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/logs/received?start=2017-07-18T22:00:00Z&end=2017-07-18T22:01:00Z&count=1&fields=$FIELDS" \
--header "X-Auth-Email: <EMAIL>" \
--header "X-Auth-Key: <API_KEY>"

请参阅 Download jq ↗ 了解如何获取和安装 jq。

请参阅 HTTP 请求字段获取当前可用字段。