API 配置

下表汇总了 Logpush 和 Edge Log Delivery 作业可用的作业操作。请确保账户作用域的数据集使用 /accounts/{account_id}，zone 作用域的数据集使用 /zone/{zone_id}。更多信息请参阅 Datasets 页面。

您可以根据 查找 zone 和账户 ID 页面定位 {zone_id} 和 {account_id} 参数。 {job_id} 参数为数字，例如 123456。 {dataset_id} 参数表示日志类别（例如 http_requests 或 audit_logs）。

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

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

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/logpush/jobs" \
	--request GET \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

在创建新作业之前，必须证明对目标的所有权。

要将所有权质询令牌发送到您的目标：

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>

支持的 scheme 如下所示，分别针对 R2、S3 等特定提供商进行了定制。此外，还涵盖 https 等通用用例：

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

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

• Cloudflare R2（scheme r2）：存储桶路径 + 账户 ID + R2 access key ID + R2 secret access key；例如：r2://<BUCKET_PATH>?account-id=<ACCOUNT_ID>&access-key-id=<R2_ACCESS_KEY_ID>&secret-access-key=<R2_SECRET_ACCESS_KEY>
• AWS S3（scheme s3）：存储桶 + 可选目录 + 区域 + 可选加密参数（如果策略要求）；例如： s3://bucket/[dir]?region=<REGION>[&sse=AES256]
• Datadog（scheme 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（scheme gs）：存储桶 + 可选目录；例如：gs://bucket/[dir]
• Microsoft Azure（scheme azure）：将 https 替换为 azure 的服务级 SAS URL + 在查询字符串前添加的可选目录；例如：azure://<BLOB_CONTAINER_PATH>/[dir]?<QUERY_STRING>
• New Relic（使用 scheme 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（scheme splunk）：Splunk 端点 URL + Splunk channel ID + insecure-skip-verify 标志 + Splunk sourcetype + 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（scheme sumo）：将 https 替换为 sumo 的 HTTP source address URL；例如：sumo://<SUMO_ENDPOINT_URL>/receiver/v1/http/<UNIQUE_HTTP_COLLECTOR_CODE>
• SentinelOne（scheme sentinelone）：SentinelOne 端点 URL + SentinelOne sourcetype + 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]

当您希望按天对日志分组时，此方法很有用。

有关云存储提供商取值的更多信息，请参阅以下约定：

• AWS S3 CLI ↗（S3Uri 路径参数类型）
• Google Cloud Storage CLI ↗（访问资源的语法）
• Microsoft Azure Shared Access Signature ↗
• Sumo Logic HTTP Source ↗

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

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 数据集。

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 已被 Custom Log Formatting output_options 取代。请参阅 Log Output Options 文档，了解如何配置这些选项并将现有作业更新为使用这些选项。

如果您仍在使用 logpull_options，以下是可以自定义的选项：

1. 字段（可选）：请参阅 Datasets 了解当前可用字段。字段列表也可直接从 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 是否有效：

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 分钟内出现在日志中。此时间为估算值，可能因系统负载而有所不同。

使用筛选器选择要包含和/或从日志中移除的事件。更多信息请参阅 Filters。

值的范围可以从 0.0（不含）到 1.0（含）。sample=0.1 表示返回所有记录的 10%（10 条中的 1 条）。默认值为 1，表示日志不会采样。

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，则大约会收到原始事件的 1/10,000（1000 × 10）。

这些参数控制每个上传批次的大小——而非数据交付的速度。使用它们可以防止因上传过大或过小而使目标过载。

• 如果目标难以处理大型有效负载，或在处理大批次时内存不足，请减小 max_upload_records。
• 如果希望生成更少、更大的文件（例如推送到 R2 或 S3 等对象存储），请增大 max_upload_records。
• 对于像 Datadog 这样具有严格有效负载限制的目标，Logpush 会自动使用较小的批次大小（例如 1,000 行）。

您可以以 HTTP 请求标头、HTTP 响应标头和 cookie 的形式向 HTTP 请求日志条目添加自定义字段。自定义字段配置适用于 zone 中使用 HTTP requests 数据集的所有 Logpush 作业。了解更多信息，请参阅 Custom fields。

以下 Logpush 操作会记录在 Cloudflare Audit Logs（Cloudflare 审计日志） 中：创建、更新和删除作业。