启用 Google BigQuery

Cloudflare Logpush 支持通过 Cloudflare 仪表板或 API 将日志直接推送到 Google BigQuery（使用 Legacy Streaming API）。

创建并获取 BigQuery 表访问权限

Cloudflare 使用 Logpush 作业 destination_conf 中提供的 Google Application Credentials 获取对表的写入访问权限。所提供的服务账户需要对该表具备写入权限。

要启用 Logpush 到 BigQuery：

前往你账户的 Google Cloud Console。
前往 IAM & Admin（IAM 和管理） > Service Accounts（服务账号），并创建新的服务账户。
在 Permissions（权限） 下添加 BigQuery Data Editor（BigQuery 数据编辑者） 角色。至少需要 bigquery.tables.updateData 权限。
在 Keys（密钥） 下添加密钥。
1. 点击 Add key（添加密钥）。
2. 点击 Create new key（创建新密钥）。
3. 选择密钥类型 JSON。
4. 点击 Create（创建）。
5. 保存 Application Credentials JSON 文件。设置新的 Logpush 作业时需要使用此文件。
在 BigQuery 中创建数据集与表。请参阅 BigQuery 说明 ↗。例如，使用 schema.json 与 bq 命令：

gcloud auth activate-service-account --key-file=${KEY_FILE}

PROJECT_ID=<PROJECT_ID>
DATASET_ID=<DATASET_ID>
TABLE_ID=<TABLE_ID>

bq mk --table "${PROJECT_ID}:${DATASET_ID}.${TABLE_ID}" schema.json

通过 Cloudflare 仪表板管理

在 Cloudflare 仪表板中，前往账户或域名（也称为 zone）级别的 Logpush（日志推送） 页面。

账户级别：Go to Logpush ↗
域名（也称为 zone）级别：Go to Logpush ↗
根据你的选择，可分别访问账户范围数据集与 zone 范围数据集。
选择 Create a Logpush job（创建 Logpush 作业）。

在 Select a destination（选择目标） 中，选择 Google BigQuery。
输入以下目标详情：
- Project ID - 你的 Google Cloud 项目 ID
- Dataset ID - 包含你的表的 BigQuery 数据集
- Table ID - 要推送日志的 BigQuery 表
- Service Account Credentials（服务账户凭据） - 粘贴你的 Google 服务账户密钥 JSON。此凭据会加密存储，且不会再次显示。

输入完目标详情后，选择 Continue（继续）。

选择要推送到存储服务的数据集。
在下一步中，你需要配置 logpush 作业：
- 输入 Job name（作业名称）。
- 在 If logs match（如果日志匹配） 下，你可以选择要包含和/或从日志中移除的事件。更多信息请参阅 Filters。并非所有数据集都提供此选项。
- 在 Send the following fields（发送以下字段） 中，你可以选择将所有日志推送到存储目标，或有选择地选择要推送的日志。
在 Advanced Options（高级选项） 中，你可以：
- 选择日志中时间戳字段的格式（RFC3339（默认）、Unix 或 UnixNano）。
- 为日志选择采样率，或推送随机采样百分比的日志。
- 为 CVE-2021-44228 启用脱敏。此选项会将每次出现的 ${ 替换为 x{。
配置完 logpush 作业后，选择 Submit（提交）。

通过 API 管理

要设置 BigQuery Logpush 作业：

使用适当的端点 URL 与认证参数创建作业。
启用作业以开始推送日志。

在尝试读取或配置 Logpush 任务之前，请确保已启用 Log Share 权限。更多信息请参阅角色部分。

1. 创建作业

要创建作业，请向 Logpush jobs 端点发送带有以下字段的 POST 请求：

name（可选）- 使用你的域名作为作业名称。
destination_conf - 由 BigQuery 表引用与凭据组成的日志目标，格式如下字符串。
- <PROJECT_ID>、<DATASET_ID>、<TABLE_ID>：指定 BigQuery 表的 Project ID、Dataset ID 与 table ID。
- <ENCODED_VALUE>：Application Credentials JSON 作为 credentials 的编码值，可使用带 base64: 前缀的 base64 编码，或带 url: 前缀的 URL 编码。

"bq://projects/<PROJECT_ID>/datasets/<DATASET_ID>/tables/<TABLE_ID>?credentials=<ENCODED_VALUE>"

dataset - 你希望接收的日志类别。完整支持的数据集列表请参阅 Datasets。
output_options（可选）- 要配置字段、采样率与时间戳格式，请参阅 Log Output Options。对于时间戳，Cloudflare 建议使用 timestamps=rfc3339。
- 当包含自定义格式选项（例如 output_type）或任何前缀 / 后缀 / 分隔符 / 模板选项时，请确保同时将 stringify_object 设为 true，否则 object 类型的字段可能无法以与 BigQuery Legacy Streaming API 兼容的格式序列化。

使用 cURL 的示例请求：

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": "bq://projects/<PROJECT_ID>/datasets/<DATASET_ID>/tables/<TABLE_ID>?credentials=<ENCODED_VALUE>",
		"output_options": {
				"field_names": [
						"ClientIP",
						"ClientRequestHost",
						"ClientRequestMethod",
						"ClientRequestURI",
						"EdgeEndTimestamp",
						"EdgeResponseBytes",
						"EdgeResponseStatus",
						"EdgeStartTimestamp",
						"RayID"
				],
				"timestamp_format": "rfc3339"
		},
		"max_upload_bytes": 5000000,
		"max_upload_records": 50000,
		"dataset": "http_requests",
		"enabled": true
	}'

响应：

{
  "errors": [],
  "messages": [],
  "result": {
    "id": <JOB_ID>,
    "dataset": "http_requests",
    "kind": "",
    "max_upload_bytes": 5000000,
    "max_upload_records": 50000,
    "enabled": true,
    "name": "<DOMAIN_NAME>",
    "output_options": {
      "field_names": ["ClientIP", "ClientRequestHost", "ClientRequestMethod", "ClientRequestURI", "EdgeEndTimestamp", "EdgeResponseBytes", "EdgeResponseStatus" ,"EdgeStartTimestamp", "RayID"],
      "timestamp_format": "rfc3339"
    },
    "destination_conf": "bq://projects/<PROJECT_ID>/datasets/<DATASET_ID>/tables/<TABLE_ID>?credentials=<ENCODED_VALUE>",
    "last_complete": null,
    "last_error": null,
    "error_message": null
  },
  "success": true
}

这将使用空内容进行测试上传以验证 Logpush 能否上传，你可能会看到一行空数据。

关于更新作业（包括启用与禁用），请参阅 Manage Logpush with cURL。

限制

请注意以下默认配额与限制，详见 BigQuery 文档 ↗。

以下限制适用于 BigQuery 流式插入：

最大 HTTP 请求大小（未压缩，可能包含请求头）：10 MB
最大行大小：10 MB
每个请求的最大行数：50,000 行。

这些是默认配额 / 限制，你应根据限制调整 Logpush 作业，并在需要时向 Google 申请提高配额。

Google Cloud Storage 集成

Cloudflare Logpush 支持将日志推送到 Google Cloud Storage。

BigQuery 支持每个表每天最多 1,500 个 load 作业（含失败），每次 load 最多 1,000 万个文件。这意味着你可以每分钟向 BigQuery 加载一次，并在一次 load 中包含最多 1,000 万个文件。更多信息请参阅 BigQuery 关于 load jobs 的配额。

Logpush 会尽快投递日志批次，这意味着你每分钟可能收到不止一批文件。请确保你的 BigQuery 作业配置为按给定时间间隔（例如每分钟）摄取文件，而不是在收到文件时立即摄取。若在收到每个 Logpush 文件时都摄取到 BigQuery，可能会很快耗尽 BigQuery 配额。

关于如何使用 BigQuery 设置计划 load 作业的社区支持示例，请参阅 Cloudflare + Google Cloud | Integrations repository ↗。请注意，该仓库以尽力而为方式提供，并非定期维护。