← Cloudflare Logs / logs / logpush / examples

Управлять Logpush с помощью cURL

Управлять службой Cloudflare Logpush можно из командной строки с помощью cURL.

Прежде чем начать, ознакомьтесь со следующей документацией:

Настройка API

Шаг 1: получение запроса для подтверждения владения

Необходимые разрешения API-токена

Хотя бы одно из следующих права доступа токена требуется:

Logs Write

Получение проверки владения

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 - См. Назначение для получения подробностей.

Ответ

В место назначения будет записан challenge-файл, а имя файла будет указано в ответе (имя файла может быть представлено в виде пути, если это уместно для вашего места назначения). Например:

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

На следующем шаге при создании задания потребуется указать токен, содержащийся в этом файле.

Шаг 2: создание задания

Необходимые разрешения API-токена

Хотя бы одно из следующих права доступа токена требуется:

Logs Write

Создать задание Logpush

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

Параметры

имя (необязательно) - Рекомендуем использовать имя своего домена в качестве имени задания, поскольку после создания задания изменить его нельзя.
destination_conf - См. Назначение для получения подробностей.
dataset - Категория журналов, которые вы хотите получать. См. Наборы данных для полного списка поддерживаемых наборов данных; этот параметр нельзя изменить после создания задания.
output_options (необязательно) - См. Параметры вывода журнала.
- Обычно включает нужные поля и формат временной метки.
- Установите формат временной метки на RFC 3339 ("timestamp_format": "rfc3339") для:
  - Использование Google BigQuery.
  - Автоматический разбор временных меток в Sumo Logic. См. временные метки из Sumo Logic ↗ для получения подробностей.
ownership_challenge - Токен подтверждения, необходимый для доказательства владения получателем.
тип (необязательно) - Используется для различения заданий Logpush и Edge Log Delivery. См. Тип для получения подробностей.
фильтр (необязательно) - См. Фильтры для получения подробностей.

Ответ

В ответе вы получите 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 задания:

Необходимые разрешения API-токена

Хотя бы одно из следующих права доступа токена требуется:

Logs Write

Получение сведений о задании Logpush

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 зоны:

Необходимые разрешения API-токена

Хотя бы одно из следующих права доступа токена требуется:

Logs Write

Список заданий Logpush

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

Далее, чтобы включить задание, отправьте запрос на обновление:

Необходимые разрешения API-токена

Хотя бы одно из следующих права доступа токена требуется:

Logs Write

Обновление задания Logpush

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 инфо

Необходимые разрешения API-токена

Хотя бы одно из следующих права доступа токена требуется:

Logs Write

Получение сведений о задании Logpush

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
}

Необязательно: удаление задания

Необходимые разрешения API-токена

Хотя бы одно из следующих права доступа токена требуется:

Logs Write

Удалить задание Logpush

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 задания:

Необходимые разрешения API-токена

Хотя бы одно из следующих права доступа токена требуется:

Logs Write

Получение сведений о задании Logpush

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
}

Получите все задания по всем наборам данных:

Необходимые разрешения API-токена

Хотя бы одно из следующих права доступа токена требуется:

Logs Write

Список заданий Logpush

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 для вашей зоны.

Необходимые разрешения API-токена

Хотя бы одно из следующих права доступа токена требуется:

Logs Write

Получение сведений о задании Logpush

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 параметр скрытия данных.

Необходимые разрешения API-токена

Хотя бы одно из следующих права доступа токена требуется:

Logs Write

Обновление задания Logpush

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 параметр недоступен через интерфейс, и обновление задания 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
}