cURL で Logpush を管理する

コマンドラインから cURL を使って、Cloudflare Logpush を管理できます。

始める前に、次のドキュメントを確認してください。

API 設定

ステップ 1 - 所有権チャレンジを取得する

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"
	}'

パラメーター

destination_conf - 詳細は保存先を参照してください。

レスポンス

チャレンジファイルが保存先に書き込まれ、ファイル名がレスポンスに含まれます（保存先に応じて、ファイル名はパスとして返ることがあります）。例:

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "filename": "burritobot/logs/ownership-challenge.txt",
    "valid": true,
    "message": ""
  }
}

次のステップでジョブを作成するときに、このファイルに含まれるトークンを指定する必要があります。

ステップ 2 - ジョブを作成する

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"
		},
		"ownership_challenge": "<OWNERSHIP_CHALLENGE_TOKEN>"
	}'

パラメーター

name（任意）- ジョブ名にはドメイン名を使うことをおすすめします。作成後に名前は変更できません。
destination_conf - 詳細は保存先を参照してください。
dataset - 受け取りたいログのカテゴリです。対応データセットの一覧はデータセットを参照してください。このパラメーターはジョブ作成後に変更できません。
output_options（任意）- ログ出力オプションを参照してください。
- 通常は、必要なフィールドとタイムスタンプ形式を指定します。
- 次の用途では、タイムスタンプ形式を RFC 3339（"timestamp_format": "rfc3339"）に設定します。
  - Google BigQuery を使う場合。
  - Sumo Logic でのタイムスタンプ自動解析。詳細は Sumo Logic のタイムスタンプ ↗ を参照してください。
ownership_challenge - 保存先の所有権を証明するために必要なチャレンジトークンです。
kind（任意）- Logpush ジョブと Edge Log Delivery ジョブを区別するために使います。詳細は Kind を参照してください。
filter（任意）- 詳細はフィルターを参照してください。

レスポンス

レスポンスには、新しく作成されたジョブ ID が含まれます。例:

{
  "errors": [],
  "messages": [],
  "result": {
    "id": <JOB_ID>,
    "dataset": "http_requests",
    "kind": "",
    "enabled": false,
    "name": "<DOMAIN_NAME>",
    "output_options": {
      "field_names": ["ClientIP", "ClientRequestHost", "ClientRequestMethod", "ClientRequestURI", "EdgeEndTimestamp","EdgeResponseBytes", "EdgeResponseStatus", "EdgeStartTimestamp", "RayID"],
      "timestamp_format": "rfc3339"
    },
    "destination_conf": "s3://<BUCKET_PATH>?region=us-west-2",
    "last_complete": null,
    "last_error": null,
    "error_message": null
  },
  "success": true
}

ステップ 3 - ジョブを有効にする（更新する）

まず、ジョブ ID を使って特定のジョブの情報を取得します。

Required API token permissions

At least one of the following token permissions is required:

Logs Write

Get Logpush job detailsbash

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

レスポンス

{
  "errors": [],
  "messages": [],
  "result": {
    "id": <JOB_ID>,
    "dataset": "http_requests",
    "kind": "",
    "enabled": false,
    "name": "<DOMAIN_NAME>",
    "output_options": {
      "field_names": ["ClientIP", "ClientRequestHost", "ClientRequestMethod", "ClientRequestURI", "EdgeEndTimestamp","EdgeResponseBytes", "EdgeResponseStatus", "EdgeStartTimestamp", "RayID"],
      "timestamp_format": "rfc3339"
    },
    "destination_conf": "s3://<BUCKET_PATH>?region=us-west-2",
    "last_complete": null,
    "last_error": null,
    "error_message": null
  },
  "success": true
}

デフォルトではジョブは有効になっていません（"enabled": false）。

ジョブ ID を覚えていない場合は、ゾーン ID を使って取得できます。

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

Update Logpush jobbash

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/logpush/jobs/$JOB_ID" \
	--request PUT \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"enabled": true
	}'

レスポンス

{
  "errors": [],
  "messages": [],
  "result": {
    "id": <JOB_ID>,
    "dataset": "http_requests",
    "kind": "",
    "enabled": true,
    "name": "<DOMAIN_NAME>",
    "output_options": {
      "field_names": ["ClientIP", "ClientRequestHost", "ClientRequestMethod", "ClientRequestURI", "EdgeEndTimestamp","EdgeResponseBytes", "EdgeResponseStatus", "EdgeStartTimestamp", "RayID"],
      "timestamp_format": "rfc3339"
    },
    "destination_conf": "s3://<BUCKET_PATH>?region=us-west-2",
    "last_complete": null,
    "last_error": null,
    "error_message": null
  },
  "success": true
}

ジョブを有効にすると、数分以内にログの受信が始まり、無効にするまでできるだけ早くバッチで届きます。リクエスト量が非常に多いゾーンでは、初めてログを受け取るまで数時間かかることがあります。

enabled の変更に加えて、output_options の値も更新できます。destination_conf を変更する場合は、所有権チャレンジを再取得し、更新リクエストにそのトークンを指定する必要があります。現在のジョブを削除して、新しいジョブを作成することもできます。

ジョブが有効になり実行を始めると、last_complete フィールドに、最後のログバッチが保存先へ正常に送信された時刻が表示されます。

ジョブ ID でジョブを取得し、last_complete を確認するリクエスト

Required API token permissions

At least one of the following token permissions is required:

Logs Write

Get Logpush job detailsbash

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

レスポンス

{
  "errors": [],
  "messages": [],
  "result": {
    "id": <JOB_ID>,
    "dataset": "http_requests",
    "kind": "",
    "enabled": true,
    "name": "<DOMAIN_NAME>",
    "output_options": {
      "field_names": ["ClientIP", "ClientRequestHost", "ClientRequestMethod", "ClientRequestURI", "EdgeEndTimestamp","EdgeResponseBytes", "EdgeResponseStatus", "EdgeStartTimestamp", "RayID"],
      "timestamp_format": "rfc3339"
    },
    "destination_conf": "s3://<BUCKET_PATH>?region=us-west-2",
    "last_complete": "2018-08-09T21:26:00Z",
    "last_error": null,
    "error_message": null
  },
  "success": true
}

任意 - ジョブを削除する

Required API token permissions

At least one of the following token permissions is required:

Logs Write

Delete Logpush jobbash

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

ジョブの削除は取り消せないため、慎重に行ってください。

レスポンス

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

任意 - ジョブを取得する

ジョブ ID を使って特定のジョブを取得します。

Required API token permissions

At least one of the following token permissions is required:

Logs Write

Get Logpush job detailsbash

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

レスポンス

{
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": <JOB_ID>,
      "dataset": "http_requests",
      "kind": "",
      "enabled": true,
      "name": "<DOMAIN_NAME>",
      "output_options": {
        "field_names": ["ClientIP", "ClientRequestHost", "ClientRequestMethod", "ClientRequestURI", "EdgeEndTimestamp","EdgeResponseBytes", "EdgeResponseStatus", "EdgeStartTimestamp", "RayID"],
        "timestamp_format": "rfc3339"
      },
      "destination_conf": "s3://<BUCKET_PATH>?region=us-west-2",
      "last_complete": null,
      "last_error": null,
      "error_message": null
    }
  ],
  "success": true
}

すべてのデータセットのジョブを取得します。

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"

レスポンス

{
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": <JOB_ID>,
      "dataset": "spectrum_events",
      "kind": "",
      "enabled": true,
      "name": "<DOMAIN_NAME>",
      "output_options": {
        "field_names": ["Application", "ClientAsn", "ClientIP", "ColoCode", "Event", "OriginIP", "Status"],
      },
      "destination_conf": "s3://<BUCKET_PATH>?region=us-west-2",
      "last_complete": "2019-10-01T00:25:00Z",
      "last_error": null,
      "error_message": null
    },
    {
      "id": <JOB_ID>,
      "dataset": "http_requests",
      "kind": "",
      "enabled": false,
      "name": "<DOMAIN_NAME>",
      "output_options": {
        "field_names": ["ClientIP", "ClientRequestHost", "ClientRequestMethod", "ClientRequestURI", "EdgeEndTimestamp","EdgeResponseBytes", "EdgeResponseStatus", "EdgeStartTimestamp", "RayID"],
        "timestamp_format": "rfc3339"
      },
      "destination_conf": "s3://<BUCKET_PATH>?region=us-west-2",
      "last_complete": "2019-09-24T21:15:00Z",
      "last_error": null,
      "error_message": null
    }
  ]
}

任意 - output_options を更新する

フィールドの追加や削除、タイムスタンプ形式の変更、Log4j - CVE-2021-44228 脆弱性への対策を有効にする場合は、まずゾーンの現在の output_options を取得します。

Required API token permissions

At least one of the following token permissions is required:

Logs Write

Get Logpush job detailsbash

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

レスポンス

{
  "errors": [],
  "messages": [],
  "result": {
    "id": <JOB_ID>,
    "dataset": "http_requests",
    "kind": "",
    "enabled": true,
    "name": "<DOMAIN_NAME>",
    "output_options": {
      "field_names": ["ClientIP", "ClientRequestHost", "ClientRequestMethod", "ClientRequestURI", "EdgeEndTimestamp","EdgeResponseBytes", "EdgeResponseStatus", "EdgeStartTimestamp", "RayID"],
      "timestamp_format": "rfc3339"
    },
    "destination_conf": "s3://<BUCKET_PATH>?region=us-west-2",
    "last_complete": "2021-12-14T19:56:49Z",
    "last_error": null,
    "error_message": null
  },
  "success": true
}

次に、output_options を目的どおりに編集し、PUT リクエストを作成します。次の例では、CVE-2021-44228 のリダクションオプションを有効にします。

Required API token permissions

At least one of the following token permissions is required:

Logs Write

Update Logpush jobbash

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/logpush/jobs/$JOB_ID" \
	--request PUT \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"output_options": {
				"field_names": [
						"ClientIP",
						"ClientRequestHost",
						"ClientRequestMethod",
						"ClientRequestURI",
						"EdgeEndTimestamp",
						"EdgeResponseBytes",
						"EdgeResponseStatus",
						"EdgeStartTimestamp",
						"RayID"
				],
				"timestamp_format": "rfc3339"
		}
	}'

現時点では、CVE-2021-44228 オプションは UI から設定できません。UI から Logpush ジョブを更新すると、このオプションは削除されます。

レスポンス

{
  "errors": [],
  "messages": [],
  "result": {
    "id": <JOB_ID>,
    "dataset": "http_requests",
    "kind": "",
    "enabled": true,
    "name": null,
    "output_options": {
      "field_names": ["ClientIP", "ClientRequestHost", "ClientRequestMethod", "ClientRequestURI", "EdgeEndTimestamp","EdgeResponseBytes", "EdgeResponseStatus", "EdgeStartTimestamp", "RayID"],
      "timestamp_format": "rfc3339"
    },
    "destination_conf": "s3://<BUCKET_PATH>?region=us-west-2",
    "last_complete": "2021-12-14T20:02:19Z",
    "last_error": null,
    "error_message": null
  },
  "success": true
}