跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

API 配置

最后更新 查看 MarkdownAgent 设置

端点

下表汇总了 Logpush 和 Edge Log Delivery 作业可用的作业操作。账户范围数据集使用 /accounts/{account_id},zone 范围数据集使用 /zones/{zone_id}。有关详细信息,请参阅数据集。

HTTP 请求和防火墙事件数据集支持两种范围。要收集账户中每个 zone 的日志,请通过 /accounts/{account_id}/logpush/jobs 端点为数据集创建账户范围作业。使用 ZoneName 字段识别每条日志记录的来源 zone。

你可以根据查找 zone 和账户 ID 页面找到 {zone_id} 和 {account_id} 参数。 {job_id} 参数是数字,例如 123456。 {dataset_id} 参数表示日志类别(例如 http_requests 或 audit_logs)。

操作 说明 API
POST 创建作业 文档
GET 检索作业详细信息 文档
GET 检索所有数据集的所有作业 文档
GET 检索数据集的所有作业 文档
GET 检索数据集的所有可用字段 文档
PUT 更新作业 文档
DELETE 删除作业 文档
POST 检查目标是否存在 文档
POST 获取所有权质询 文档
POST 验证所有权质询 文档
POST 验证日志选项 文档

有关具体示例,请参阅 Logpush 示例中的教程。

连接

与任何其他 Cloudflare API 一样,Logpush API 需要凭据。

Required API token permissions

At least one of the following token permissions is required:
  • Logs Write
List Logpush jobsbash
curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/logpush/jobs" \
	--request GET \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

所有权

创建新作业前,必须证明目标的所有权。

要向目标发出所有权质询令牌:

Required API token permissions

At least one of the following token permissions is required:
  • Logs Write
Get ownership challengebash
curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/logpush/ownership" \
	--request POST \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"destination_conf": "s3://<BUCKET_PATH>?region=us-west-2"
	}'

系统会将质询文件写入目标,响应中会包含文件名(如果适合你的目标,文件名可能表示为路径):

{
  "errors": [],
  "messages": [],
  "result": {
    "valid": true,
    "message": "",
    "filename": "<PATH_TO_CHALLENGE_FILE>.txt"
  },
  "success": true
}

创建作业时,需要提供文件中包含的令牌。

目标

你可以通过必需的 destination_conf 参数指定云服务提供商目标。

destination_conf 参数必须采用以下格式:

<scheme>://<destination-address>

下面列出了支持的方案,每种方案针对 R2、S3 等特定提供商。此外,还涵盖了 https 等通用用例:

  • r2,
  • gs,
  • s3,
  • sumo,
  • https,
  • azure,
  • splunk,
  • sentinelone,
  • datadog.

destination-address 通常应由目标提供商提供。但是,对于某些提供商,我们要求 destination-address 遵循特定格式:

  • Cloudflare R2(方案 r2):存储桶路径 + 账户 ID + R2 访问密钥 ID + R2 机密访问密钥;例如:r2://<BUCKET_PATH>?account-id=<ACCOUNT_ID>&access-key-id=<R2_ACCESS_KEY_ID>&secret-access-key=<R2_SECRET_ACCESS_KEY>
  • AWS S3(方案 s3):存储桶 + 可选目录 + 区域 + 可选加密参数(如果策略要求);例如: s3://bucket/[dir]?region=<REGION>[&sse=AES256]
  • Datadog(方案 datadog):Datadog 端点 URL + Datadog API 密钥 + 可选参数;例如:datadog://<DATADOG_ENDPOINT_URL>?header_DD-API-KEY=<DATADOG_API_KEY>&ddsource=cloudflare&service=<SERVICE>&host=<HOST>&ddtags=<TAGS>
  • Google Cloud Storage(方案 gs):存储桶 + 可选目录;例如:gs://bucket/[dir]
  • Microsoft Azure(方案 azure):将 https 替换为 azure 的服务级 SAS URL + 在查询字符串前添加的可选目录;例如:azure://<BLOB_CONTAINER_PATH>/[dir]?<QUERY_STRING>
  • New Relic(使用方案 https):New Relic 端点 URL(美国为 https://log-api.newrelic.com/log/v1,欧盟为 https://log-api.eu.newrelic.com/log/v1)+ 许可证密钥 + 格式;例如,美国为 "https://log-api.newrelic.com/log/v1?Api-Key=<NR_LICENSE_KEY>&format=cloudflare",欧盟为 "https://log-api.eu.newrelic.com/log/v1?Api-Key=<NR_LICENSE_KEY>&format=cloudflare"
  • Splunk(方案 splunk):Splunk 端点 URL + Splunk 通道 ID + 跳过不安全验证标志 + Splunk 源类型 + Splunk 授权令牌;例如:splunk://<SPLUNK_ENDPOINT_URL>?channel=<SPLUNK_CHANNEL_ID>&insecure-skip-verify=<INSECURE_SKIP_VERIFY>&sourcetype=<SOURCE_TYPE>&header_Authorization=<SPLUNK_AUTH_TOKEN>
  • Sumo Logic(方案 sumo):将 https 替换为 sumo 的 HTTP 源地址 URL;例如:sumo://<SUMO_ENDPOINT_URL>/receiver/v1/http/<UNIQUE_HTTP_COLLECTOR_CODE>
  • SentinelOne(方案 sentinelone):SentinelOne 端点 URL + SentinelOne 源类型 + SentinelOne 授权令牌;例如:sentinelone://<SENTINELONE_ENDPOINT_URL>?sourcetype=<SOURCE_TYPE>&header_Authorization=<SENTINELONE_AUTH_TOKEN>

对于 R2、S3、Google Cloud Storage 和 Azure,可以在 URL 路径中包含特殊占位符 {DATE},将日志整理到每日子目录中。此占位符会自动替换为 YYYYMMDD 格式的日期(例如 20180523)。

例如:

  • s3://mybucket/logs/{DATE}?region=us-east-1&sse=AES256
  • azure://myblobcontainer/logs/{DATE}?[QueryString]

当你希望按天对日志进行分组时,此方法很有用。

有关云存储提供商的值的详细信息,请参阅以下约定:

要检查目标是否已在使用:

Required API token permissions

At least one of the following token permissions is required:
  • Logs Write
Check destination existsbash
curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/logpush/validate/destination/exists" \
	--request POST \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"destination_conf": "s3://foo"
	}'

响应

{
  "errors": [],
  "messages": [],
  "result": {
    "exists": false
  },
  "success": true
}

名称

人类可读的可选作业名称,无需唯一。建议选择有意义的名称(例如域名),以便轻松识别和管理作业。以后可根据需要更新名称。

类型

可选的 kind 参数用于区分 Logpush 和 Edge Log Delivery 作业。对于 Logpush 作业,可以将此参数留空或省略。对于 Edge Log Delivery 作业,请设置 "kind": "edge"。目前,Edge Log Delivery 仅支持 http_requests 数据集。

Required API token permissions

At least one of the following token permissions is required:
  • Logs Write
Create Logpush jobbash
curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/logpush/jobs" \
	--request POST \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"name": "<DOMAIN_NAME>",
		"destination_conf": "s3://<BUCKET_PATH>?region=us-west-2",
		"dataset": "http_requests",
		"output_options": {
				"field_names": [
						"ClientIP",
						"ClientRequestHost",
						"ClientRequestMethod",
						" ClientRequestURI",
						"EdgeEndTimestamp",
						"EdgeResponseBytes",
						"EdgeResponseStatus",
						"EdgeStartTimestamp",
						"RayID"
				],
				"timestamp_format": "rfc3339"
		},
		"kind": "edge"
	}'

选项

Logpull_options 已替换为自定义日志格式化 output_options。有关配置这些选项以及更新现有作业以使用这些选项的说明,请参阅日志输出选项文档。

如果仍在使用 logpull_options,可以自定义以下选项:

  1. 字段(可选):有关当前可用字段,请参阅数据集。也可以直接从 API 访问字段列表:https://api.cloudflare.com/client/v4/zones/{zone_id}/logpush/datasets/{dataset_id}/fields。默认字段:https://api.cloudflare.com/client/v4/zones/{zone_id}/logpush/datasets/{dataset_id}/fields/default。
  2. 时间戳格式(可选):返回时间戳字段的格式。值选项:unixnano(纳秒单位,默认)、unix(秒单位)、rfc3339(秒单位)。
  3. 针对 CVE-2021-44228 的编辑(可选):此选项会将每次出现的 ${ 替换为 x{。要启用,请设置 "CVE-2021-44228": true。

要检查所选 logpull_options 是否有效:

Required API token permissions

At least one of the following token permissions is required:
  • Logs Write
Validate originbash
curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/logpush/validate/origin" \
	--request POST \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"logpull_options": "fields=RayID,ClientIP,EdgeStartTimestamp&timestamps=rfc3339&CVE-2021-44228=true",
		"dataset": "http_requests"
	}'

响应

{
  "errors": [],
  "messages": [],
  "result": {
    "valid": true,
    "message": ""
  },
  "success": true
}

配置更改生效时间

修改 Logpush 作业配置时,更改不会立即生效。

目标更改

如果重新配置作业以使用新目标,在过渡期间,日志可能会继续发送到旧目标约 10-15 分钟。此延迟让系统能够完成正在进行的上传,并在 Cloudflare 网络中传播新配置。

字段更改

向现有 Logpush 作业添加新字段时,新字段会在大约 10-15 分钟内出现在日志中。此时间为估计值,可能因系统负载而异。

过滤器

使用过滤器选择要包含在日志中的事件和/或从中移除的事件。有关详细信息,请参阅过滤器。

DDoS 攻击流量

在仪表板中,选择 Advanced Options 下的 Exclude DDoS attack traffic。对于 API,将 filter_attack_traffic 设置为 true。默认值为 false。

此设置支持以下数据集:

  • HTTP 请求 (http_requests)
  • 防火墙事件 (firewall_events)
  • Network Analytics Logs (network_analytics_logs)

然后,Logpush 会从日志中排除已识别的 DDoS 攻击流量。

采样率

取值范围为 0.0(不含)到 1.0(含)。sample=0.1 表示返回全部记录的 10%(每 10 条取 1 条)。默认值为 1,表示日志不进行采样。

了解 sample_rate 和 SampleInterval

sample_rate 参数和 SampleInterval 字段是相互独立的机制,分别作用于日志管道的不同阶段:

  • sample_rate:你在 Logpush 作业中设置的配置参数,用于控制发送到目标位置的日志比例(0.0–1.0)。例如,设置 sample_rate: 0.1 会发送约 10% 的日志。

  • SampleInterval:某些数据集(尤其是 Network Analytics Logs)中包含的数据字段,表示数据收集期间上游应用的采样。SampleInterval 为 1000 表示每条日志代表 1000 个数据包中的 1 个。

你配置的 sample_rate 会叠加在任何已有采样之上。如果数据已具有 SampleInterval: 1000,而你又设置 sample_rate: 0.1,那么收到的数据约为原始事件的万分之一(1000 × 10)。

最大上传参数

这些参数用于控制每个上传批次的大小,而非数据的传输速度。你可以使用这些参数,避免因上传批次过大或过小而使目标位置过载。

参数 说明 默认值
max_upload_bytes 每批日志的最大未压缩文件大小。 因目标位置而异
max_upload_records 每批日志行的最大数量。 100,000
max_upload_interval_seconds 每批日志数据的最大时间跨度(用于追赶处理场景)。 因目标位置而异

何时调整这些参数

  • 如果目标位置难以处理大型负载,或处理大批次时内存不足,请降低 max_upload_records。
  • 如果你希望减少文件数量并增大文件尺寸(例如推送到 R2 或 S3 等对象存储),请提高 max_upload_records。
  • 对于 Datadog 等有严格负载限制的目标位置,Logpush 会自动采用较小的批次(例如 1,000 行)。

自定义字段

你可以在 HTTP 请求日志条目中添加自定义字段,包括 HTTP 请求标头、HTTP 响应标头和 Cookie。自定义字段配置适用于 zone 中所有使用 HTTP requests 数据集的 Logpush 作业。更多信息请参阅自定义字段。

审计

以下 Logpush 操作会记录在 Cloudflare Audit Logs 中:创建、更新和删除作业。

这篇文档对您有帮助吗?