よく使う API 呼び出し

次のセクションは、よく使う API 呼び出しのリクエスト例です。利用できる API エンドポイントの一覧は Endpoints を参照してください。

すべてのプログラムを一覧する

この例は、アカウント内のすべての Programmable Flow Protection プログラムを取得します。

リクエスト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": []
}

プログラムを更新する

この例は、既存のプログラムを新しいソースコードで更新します。1 つ以上のルールで使用中のプログラムでも更新できます。新しいプログラムのコンパイルまたは検証に失敗すると、更新は失敗し、既存のプログラムが引き続き有効です。

リクエスト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": []
}

すべてのルールを一覧する

この例は、アカウント内のすべての Programmable Flow Protection ルールを取得します。

リクエスト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 モードの Programmable Flow Protection ルールを作成します。

リクエスト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 objects を参照してください。

リージョンスコープのルールを作成する

この例は、西ヨーロッパリージョンにスコープし、式フィルター付きのルールを作成します。

リクエスト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 objects を参照してください。

ルールを更新する

この例は既存のルールを更新します。mode、scope、expression は更新できますが、program は変更できません。program を変えるには、ルールを削除して新しく作成します。

リクエスト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 objects を参照してください。

ルールを削除する

この例は既存のルールを削除します。

リクエスト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 ヘッダーのオフセットバイト数を指定します（例: Ethernet フレームでは 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: このパケットにプログラムが設定した、カスタムの network analytics タグ（ある場合）
Challenge packet: プログラムからクライアントへ送出したチャレンジパケット（ある場合）