ログをリクエストする

エンドポイント

Logpull API が対応する 3 つのエンドポイントは次のとおりです。

GET /logs/received - 指定したパラメーターに基づく HTTP リクエストのログデータを返します
GET /logs/received/fields - 利用できるすべてのログフィールドの一覧を返します
GET /logs/rayids/{ray_id} - {ray_id} に一致する HTTP リクエストのログデータを返します

必要な認証ヘッダー

すべてのエンドポイント呼び出しで、次のヘッダーが必要です。

X-Auth-Email - ドメインに紐づく Cloudflare アカウントのメールアドレス
X-Auth-Key - Cloudflare API キー

代わりに、Logs Read 権限を持つ API トークンでも認証できます。

Authorization: Bearer <API_TOKEN>

パラメーター

API は GET リクエストのクエリ文字列でエンドポイントパラメーターを受け取ります。形式の例は次のとおりです。

logs/received

https://api.cloudflare.com/client/v4/zones/{zone_id}/logs/received?start=<unix|rfc3339>&end=<unix|rfc3339>[&count=<int>][&sample=<float>][&fields=<FIELDS>][&timestamps=<string>][&CVE-2021-44228=<boolean>]

logs/rayids/{ray_id}

https://api.cloudflare.com/client/v4/zones/{zone_id}/logs/rayids/{ray_id}?[&fields=<FIELDS>][&timestamps=<string>]

利用できるパラメーターは次の表のとおりです。

パラメーター	説明	適用先	必須
start	- 開始を含む - タイムスタンプの形式は `UNIX`（定義上 UTC）、`UNIX Nano`、または `rfc3339` です。URL クエリパラメーターで `rfc3339` のタイムゾーンを指定するには、URL をエンコードする必要があります。例: `start=2024-08-07T07:00:00%2B08:00&end=2024-08-07T07:01:00%2B08:00`。 - 現在時刻から 7 日より前にはできません	/logs/received	はい
end	- 終了を含まない - 形式は start と同じです - 現在時刻より少なくとも 1 分前で、start より後である必要があります	/logs/received	はい
count	- 最大でこの件数のレコードを返します - すべてのレコードを返す場合は指定しないでください - 結果はソートされません。そのため、同じリクエストを繰り返してもデータが変わることがあります - サンプリング後の件数ではなく、返すレコードの総数に適用されます	/logs/received	いいえ
sample	- レコードのサンプルだけを返します - すべてのレコードを返す場合は指定しないでください - 値は `0.0`（含まない）から `1.0`（含む）までです - `sample=0.1` は、全レコードの 10%（10 件に 1 件）を返すことを意味します - 結果はランダムです。そのため、同じリクエストを繰り返しても件数は変わりやすくなります	/logs/received	いいえ
fields	- 返すフィールドのカンマ区切りリストです - 空の場合は、デフォルトの一覧を返します	/logs/received /logs/rayids	いいえ
timestamps	- タイムスタンプフィールドの返却形式です - 値の選択肢は `unixnano`（デフォルト）、`unix`、`rfc3339` です - `unix` と `unixnano` では整数、`rfc3339` では文字列として返します	/logs/received /logs/rayids	いいえ
CVE-2021-44228	- CVE-2021-44228 ↗ 向けの任意のリダクションです。このオプションは、文字列 `${` の出現をすべて `x{` に置き換えます。例: `CVE-2021-44228=true`	/logs/received	いいえ

cURL を使った API リクエストの例

logs/received

curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/logs/received?start=2017-07-18T22:00:00Z&end=2017-07-18T22:01:00Z&count=1&fields=ClientIP,ClientRequestHost,ClientRequestMethod,ClientRequestURI,EdgeEndTimestamp,EdgeResponseBytes,EdgeResponseStatus,EdgeStartTimestamp,RayID" \
--header "X-Auth-Email: <EMAIL>" \
--header "X-Auth-Key: <API_KEY>"

logs/rayids/{ray_id}

curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/logs/rayids/{ray_id}}?timestamps=rfc3339" \
--header "X-Auth-Email: <EMAIL>" \
--header "X-Auth-Key: <API_KEY>"

フィールド

fields パラメーターで指定しない限り、API は限られたログフィールドだけを返します。このデフォルトのフィールドセットは予告なく変わることがあります。利用できるすべてのフィールドの一覧は次の URL にあります。

https://api.cloudflare.com/client/v4/zones/{zone_id}/logs/received/fields

フィールドの指定順は意味を持ちません。レスポンス内のフィールド順も決まっていません。

bash のサブシェルと jq を使うと、フィールドを手でコピー＆ペーストせずに、利用できるすべてのフィールドでログをダウンロードできます。例:

FIELDS=$(curl https://api.cloudflare.com/client/v4/zones/{zone_id}/logs/received/fields \
--header "X-Auth-Email: <EMAIL>" \
--header "X-Auth-Key: <API_KEY>" \
| jq '. | to_entries[] | .key' -r | paste -sd "," -)

curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/logs/received?start=2017-07-18T22:00:00Z&end=2017-07-18T22:01:00Z&count=1&fields=$FIELDS" \
--header "X-Auth-Email: <EMAIL>" \
--header "X-Auth-Key: <API_KEY>"

jq の入手とインストールは Download jq ↗ を参照してください。

現在利用できるフィールドは HTTP リクエストを参照してください。