INTEGRITY Документация

← Cloudflare DDoS Protection / ddos-protection / advanced-ddos-systems / api / programmable-flow-protection

Типичные вызовы API

В следующих разделах приведены примеры запросов для распространённых вызовов API. Список доступных конечных точек API см. в Конечные точки.

Получить список всех программ

В этом примере получаются все программы Programmable Flow Protection в аккаунте.

Запрос
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/magic/programmable_flow_protection/configs/programs" \
--header "Authorization: Bearer <API_TOKEN>"
Ответ
{
  "result": [
    {
      "id": "<PROGRAM_ID>",
      "name": "rate-limiter",
      "status": "success",
      "created_on": "<TIMESTAMP>",
      "modified_on": "<TIMESTAMP>"
    }
  ],
  "success": true,
  "errors": [],
  "messages": []
}

Загрузить программу

В этом примере загружается новая программа eBPF, написанная на C. Исходный код программы отправляется в теле запроса с Content-Type: text/plain.

Добавьте необязательный X-Program-Name заголовок, чтобы указать понятное человеку имя программы. Если он не указан, API создаёт UUID в качестве имени программы.

Запрос
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/magic/programmable_flow_protection/configs/programs" \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: text/plain" \
--header "X-Program-Name: my-rate-limiter" \
--data-binary "@/path/to/program.c"
Ответ
{
  "result": {
    "id": "<PROGRAM_ID>",
    "name": "my-rate-limiter",
    "status": "success",
    "created_on": "<TIMESTAMP>",
    "modified_on": "<TIMESTAMP>"
  },
  "success": true,
  "errors": [],
  "messages": []
}

Если программа не проходит компиляцию или проверку, API возвращает подробное сообщение об ошибке:

Пример ответа с ошибкой
{
  "result": null,
  "success": false,
  "errors": [
    {
      "code": 1001,
      "message": "Program verification failed: invalid memory access at line 42"
    }
  ],
  "messages": []
}

Обновить программу

В этом примере обновляется существующая программа с новым исходным кодом. Программу можно обновить, даже если она используется одним или несколькими правилами. Если новая программа не проходит компиляцию или проверку, обновление завершается ошибкой, а существующая программа остается активной.

Запрос
curl --request PATCH \
"https://api.cloudflare.com/client/v4/accounts/{account_id}/magic/programmable_flow_protection/configs/programs/{program_id}" \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: text/plain" \
--data-binary "@/path/to/updated-program.c"
Ответ
{
  "result": {
    "id": "<PROGRAM_ID>",
    "name": "program",
    "status": "success",
    "created_on": "<TIMESTAMP>",
    "modified_on": "<TIMESTAMP>"
  },
  "success": true,
  "errors": [],
  "messages": []
}

Удаление программы

В этом примере удаляется программа. Нельзя удалить программу, на которую ссылается активное правило.

Запрос
curl --request DELETE \
"https://api.cloudflare.com/client/v4/accounts/{account_id}/magic/programmable_flow_protection/configs/programs/{program_id}" \
--header "Authorization: Bearer <API_TOKEN>"
Ответ
{
  "result": null,
  "success": true,
  "errors": [],
  "messages": []
}

Получить список всех правил

В этом примере получаются все правила Programmable Flow Protection в аккаунте.

Запрос
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/magic/programmable_flow_protection/configs/rules" \
--header "Authorization: Bearer <API_TOKEN>"
Ответ
{
  "result": [
    {
      "id": "<RULE_ID>",
      "program_id": "<PROGRAM_ID>",
      "scope": "global",
      "name": "global",
      "mode": "enabled",
      "expression": "",
      "created_on": "<TIMESTAMP>",
      "modified_on": "<TIMESTAMP>"
    }
  ],
  "success": true,
  "errors": [],
  "messages": []
}

Создание правила

В этом примере создается правило Programmable Flow Protection с глобальной областью действия в режиме мониторинга.

Запрос
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/magic/programmable_flow_protection/configs/rules" \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{
  "program_id": "<PROGRAM_ID>",
  "scope": "global",
  "name": "global",
  "mode": "monitoring"
}'
Ответ
{
  "result": {
    "id": "<RULE_ID>",
    "program_id": "<PROGRAM_ID>",
    "scope": "global",
    "name": "global",
    "mode": "monitoring",
    "expression": "",
    "created_on": "<TIMESTAMP>",
    "modified_on": "<TIMESTAMP>"
  },
  "success": true,
  "errors": [],
  "messages": []
}

См. Объекты JSON для получения дополнительной информации о полях в теле JSON.

Создание правила с региональной областью действия

В этом примере создается правило с областью действия, ограниченной регионом Западная Европа, с фильтром по выражению.

Запрос
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/magic/programmable_flow_protection/configs/rules" \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{
  "program_id": "<PROGRAM_ID>",
  "scope": "region",
  "name": "WEUR",
  "mode": "enabled",
  "expression": "ip.dst in { 192.0.2.0/24 }"
}'
Ответ
{
  "result": {
    "id": "<RULE_ID>",
    "program_id": "<PROGRAM_ID>",
    "scope": "region",
    "name": "WEUR",
    "mode": "enabled",
    "expression": "ip.dst in { 192.0.2.0/24 }",
    "created_on": "<TIMESTAMP>",
    "modified_on": "<TIMESTAMP>"
  },
  "success": true,
  "errors": [],
  "messages": []
}

См. Объекты JSON для получения дополнительной информации о полях в теле JSON.

Обновить правило

В этом примере обновляется существующее правило. Можно изменить режим, область действия и выражение, но не программу. Чтобы изменить программу, удалите правило и создайте новое.

Запрос
curl --request PATCH \
"https://api.cloudflare.com/client/v4/accounts/{account_id}/magic/programmable_flow_protection/configs/rules/{rule_id}" \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{
  "mode": "enabled"
}'
Ответ
{
  "result": {
    "id": "<RULE_ID>",
    "program_id": "<PROGRAM_ID>",
    "scope": "global",
    "name": "global",
    "mode": "enabled",
    "expression": "",
    "created_on": "<TIMESTAMP>",
    "modified_on": "<TIMESTAMP>"
  },
  "success": true,
  "errors": [],
  "messages": []
}

См. Объекты JSON для получения дополнительной информации о полях в теле JSON.

Удаление правила

В этом примере удаляется существующее правило.

Запрос
curl --request DELETE \
"https://api.cloudflare.com/client/v4/accounts/{account_id}/magic/programmable_flow_protection/configs/rules/{rule_id}" \
--header "Authorization: Bearer <API_TOKEN>"
Ответ
{
  "result": null,
  "success": true,
  "errors": [],
  "messages": []
}

Отладка программы с помощью PCAP

В этом примере программа запускается на файле PCAP для отладки. API возвращает аннотированный файл PCAP с вердиктом программы для каждого пакета.

Тело запроса должно содержать файл PCAP в двоичном формате. API автоматически определяет смещение IP-заголовка на основе входного файла PCAP. Чтобы переопределить автоматическое определение, используйте необязательный ip_offset для указания количества байт смещения заголовка IP в каждом пакете (например, 14 для кадров Ethernet).

Запрос
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/magic/programmable_flow_protection/configs/programs/{program_id}/pcap" \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/vnd.tcpdump.pcap" \
--data-binary "@/path/to/input.pcap" \
--output output.pcap

Выходной файл PCAP содержит те же пакеты, что и входной файл, но с аннотациями к каждому пакету. Аннотация Packet Comment может содержать: