API の設定

次の表は、Logpush ジョブと Edge Log Delivery ジョブの両方で使えるジョブ操作の概要です。アカウントスコープのデータセットは /accounts/{account_id} を、ゾーンスコープのデータセットは /zone/{zone_id} を使ってください。詳細は データセット を参照してください。

{zone_id} と {account_id} の引数は、ゾーン ID とアカウント 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>

サポートするスキームは次のとおりです。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）: サービスレベルの SAS URL の https を azure に置き換え、クエリ文字列の前に任意のディレクトリを追加。例: azure://<BLOB_CONTAINER_PATH>/[dir]?<QUERY_STRING>
• New Relic（スキーム https を使用）: New Relic エンドポイント URL（米国は https://log-api.newrelic.com/log/v1、EU は https://log-api.eu.newrelic.com/log/v1）+ ライセンスキー + フォーマット。例: 米国は "https://log-api.newrelic.com/log/v1?Api-Key=<NR_LICENSE_KEY>&format=cloudflare"、EU は "https://log-api.eu.newrelic.com/log/v1?Api-Key=<NR_LICENSE_KEY>&format=cloudflare"
• Splunk（スキーム splunk）: Splunk エンドポイント URL + Splunk チャネル 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（スキーム sumo）: HTTP ソースアドレス URL の https を sumo に置き換え。例: sumo://<SUMO_ENDPOINT_URL>/receiver/v1/http/<UNIQUE_HTTP_COLLECTOR_CODE>
• SentinelOne（スキーム 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 に置き換わりました。これらのオプションの設定方法と、既存ジョブをこれらのオプションへ更新する手順は、ログ出力オプション を参照してください。

まだ 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 が有効かを確認するには:

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 分以内にログへ現れます。この時間は目安であり、システムの負荷によって変わることがあります。

フィルターを使うと、ログに含める（または除外する）イベントを選べます。詳細は フィルター を参照してください。

値の範囲は 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 を下げます。
• ファイル数を減らし、1 ファイルを大きくしたい場合（R2 や S3 などのオブジェクトストレージへ送る場合など）は、max_upload_records を上げます。
• Datadog のようにペイロード制限が厳しい宛先では、Logpush は自動で小さなバッチサイズ（例: 1,000 行）を使います。

HTTP リクエストヘッダー、HTTP レスポンスヘッダー、Cookie の形で、HTTP リクエストログエントリにカスタムフィールドを追加できます。カスタムフィールドの設定は、HTTP requests データセットを使うゾーン内のすべての Logpush ジョブに適用されます。詳細は カスタムフィールド を参照してください。

次の Logpush 操作は Cloudflare Audit Logs に記録されます。ジョブの作成、更新、削除です。