跳转到内容
搜索文档
↵选择
↑↓导航
ESC关闭

常用 API 调用

最后更新 查看 MarkdownAgent 设置

以下各节包含常用 API 调用的示例请求。有关可用 API 端点的列表，请参阅端点。

获取所有程序列表

此示例获取账户中的所有可编程流防护程序。

请求bash
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/magic/programmable_flow_protection/configs/programs" \
--header "Authorization: Bearer <API_TOKEN>"
响应json
{
  "result": [
    {
      "id": "<PROGRAM_ID>",
      "name": "rate-limiter",
      "status": "success",
      "created_on": "<TIMESTAMP>",
      "modified_on": "<TIMESTAMP>"
    }
  ],
  "success": true,
  "errors": [],
  "messages": []
}

上传一个程序

此示例上传一个以 C 语言编写的新 eBPF 程序。程序源代码作为请求主体发送，其中 Content-Type: text/plain。

包含可选的 X-Program-Name 请求头以指定易于阅读的程序名称。如果省略，API 将生成一个 UUID 作为程序名称。

请求bash
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"
响应json
{
  "result": {
    "id": "<PROGRAM_ID>",
    "name": "my-rate-limiter",
    "status": "success",
    "created_on": "<TIMESTAMP>",
    "modified_on": "<TIMESTAMP>"
  },
  "success": true,
  "errors": [],
  "messages": []
}

如果程序编译或校验失败，API 将返回详细的错误消息：

示例错误响应json
{
  "result": null,
  "success": false,
  "errors": [
    {
      "code": 1001,
      "message": "Program verification failed: invalid memory access at line 42"
    }
  ],
  "messages": []
}

更新一个程序

此示例使用新的源代码更新现有程序。即使该程序当前正被一个或多个规则使用，您也可以更新它。如果新程序编译或校验失败，更新将失败，现有程序仍保持活跃状态。

请求bash
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"
响应json
{
  "result": {
    "id": "<PROGRAM_ID>",
    "name": "program",
    "status": "success",
    "created_on": "<TIMESTAMP>",
    "modified_on": "<TIMESTAMP>"
  },
  "success": true,
  "errors": [],
  "messages": []
}

删除一个程序

此示例删除一个程序。您无法删除当前被活跃规则引用的程序。

请求bash
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>"
响应json
{
  "result": null,
  "success": true,
  "errors": [],
  "messages": []
}

获取所有规则列表

此示例获取账户中的所有可编程流防护规则。

请求bash
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/magic/programmable_flow_protection/configs/rules" \
--header "Authorization: Bearer <API_TOKEN>"
响应json
{
  "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": []
}

创建规则

此示例在监控 (monitoring) 模式下创建一条具有全局范围的可编程流防护规则。

请求bash
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"
}'
响应json
{
  "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 对象。

创建具有区域范围的规则

此示例创建一条作用域限定为西欧 (Western Europe) 区域且带有一个表达式过滤器的规则。

请求bash
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 }"
}'
响应json
{
  "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 对象。

更新一条规则

此示例更新一条现有规则。您可以更新模式、范围和表达式，但不能更新程序本身。要更改程序，请删除该规则并创建一条新规则。

请求bash
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"
}'
响应json
{
  "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 对象。

删除一条规则

此示例删除一条现有规则。

请求bash
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>"
响应json
{
  "result": null,
  "success": true,
  "errors": [],
  "messages": []
}

使用 PCAP 调试程序

此示例针对 PCAP 文件运行程序以进行调试。API 将返回一个带注释的 PCAP 文件，其中包含每个数据包的程序裁定。

请求主体必须包含二进制格式的 PCAP 文件。API 会根据输入的 PCAP 自动检测 IP 请求头偏移量。要覆盖自动检测，请使用可选的 ip_offset 查询参数来指定每个数据包中 IP 请求头偏移的字节数（例如，以太网帧为 14）。

请求bash
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) 注释可能包含：

  • 程序返回值：CF_EBPF_PASS 或 CF_EBPF_DROP
  • Ignored：如果传入的数据包不是 UDP
  • Analytics tag：程序在此数据包上设置的自定义网络分析标记（如有）
  • Challenge packet：从程序发射回客户端的质询数据包（如有）

这篇文档对您有帮助吗？