cURL コマンドのガイドライン

cURL コマンドには、次の表記ルールを使います。

例にこのルールを自動で取り入れるには、次を使います。

• APIRequest: Cloudflare API スキーマのエンドポイントを叩く例向け。
• CURL: それ以外の cURL コマンド向け。

わかりやすさのため、長いパラメーター名を使います。

• --header（-H の代わり）
• --request（必要な場合。-X の代わり）
• --data（-d の代わり）

メインの cURL パラメーターなので、--url パラメーターは不要です。また、URL を二重引用符（""）で囲む必要もありません。ただし、URL に ? が含まれる場合（クエリ文字列がある場合）は囲みます。

リクエストまたはレスポンスのボディ（リクエスト／レスポンスに含まれる追加データ）は、2 スペースでインデントします。

ボディがあるリクエストでは、ボディ部分（このページの例では --data の次の行）からインデントを始めます。つまり、URL、ヘッダー、--data パラメーターのある行はインデントしません。

ボディのないリクエストもインデントしません。ボディのあるリクエストと揃えるためです。

jq ↗ は別ツールであり、全員がインストールしているわけではありません。cURL の例に、jq によるレスポンス整形を含めないでください。

このツールの利用を案内する必要がある場合は、Fundamentals の API を呼び出す ページ（このツールに言及しています）へリンクしてください。cURL の例の近くで、jq についての既存の説明を繰り返さないでください。

• cURL コマンドにタイポグラフィカル引用符やスマートクォートを使わないでください。コマンドが失敗します。
• URL 内のプレースホルダーは、API ドキュメントと同じ形式にします: $ZONE_ID
• リクエストボディ（POST / PUT / PATCH リクエストに含めるデータ）のプレースホルダーには、山括弧: <RULE_ID> を使います

同じプレースホルダー名は同じ値に対応させます。異なる ID 値には、異なるプレースホルダー名を使います。リクエストの値と一致させるべき場合は、レスポンスでも同じリクエスト用プレースホルダーを使えます。

Email + API Key 認証を使う場合は、必要な 2 つの HTTP ヘッダーをリクエストに追加するため、cURL コマンドに次の引数を含めます。

--header "X-Auth-Email: $CLOUDFLARE_EMAIL" \
--header "X-Auth-Key: $CLOUDFLARE_API_KEY" \

API トークン（推奨の認証方法）を使う場合は、必要な HTTP ヘッダーをリクエストに追加するため、cURL コマンドに次の引数を含めます。

--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \

GET リクエストでは、--request GET コマンドライン引数を含めないでください。ボディのないリクエストではこれが既定であり、GET / POST リクエストでは推奨されません。

curl {full_url_with_placeholders} \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

curl https://api.cloudflare.com/client/v4/zones/$ZONE_ID/firewall/rules \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

curl --request DELETE \
{full_url_with_placeholders} \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

ボディのないリクエストにシンタックスハイライトは不要ですが、区切られた複数の文字列を目立たせるため bash のシンタックスハイライトを使います。

リクエストにボディがある場合は、Content-Type ヘッダーを含めてください。JSON コンテンツのリクエストでは、ヘッダーは Content-Type: application/json です。

このヘッダーは、認証ヘッダーの後に置きます。

ボディのある POST リクエストでは、--request POST コマンドライン引数を含めないでください。ボディがあるリクエストではこれが既定です。

curl {full_url_with_placeholders} \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--header "Content-Type: application/json" \
--data '({|[)
  (...JSON content, pretty printed, using 2-space indents...)
(}|])'

curl https://api.cloudflare.com/client/v4/zones/$ZONE_ID/firewall/rules \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--header "Content-Type: application/json" \
--data '[
  {
    "filter": {
      "id": "<FILTER_ID>"
    },
    "action": "allow",
    "description": "Do not challenge login from office"
  }
]'

curl --request (PUT/PATCH) \
{full_url_with_placeholders} \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--header "Content-Type: application/json" \
--data '({|[)
  (...JSON content, pretty printed, using 2-space indents...)
(}|])'

JSON ペイロード（--data コマンドライン引数）は、二重引用符ではなく単一引用符（'）で囲みます。エスケープが少なくて済むためです（JSON の文字列は二重引用符で区切る必要があります）。

ボディ内のシングルクォートをエスケープする推奨方法は次のとおりです（利用者が bash 系ターミナルでコマンドを実行することを想定しています）。

• シングルクォート ' を '\'' に置き換えます

「文字列を閉じ、エスケープしたシングルクォートを追加し、再び文字列を開始する」という意味です。

curl https://api.cloudflare.com/api/v4/zones/$ZONE_ID/page_shield/policies \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "value": "script-src myapp.example.com cdnjs.cloudflare.com https://www.google-analytics.com/analytics.js '\''self'\''"
}'

ボディのない POST リクエストでは、cURL コマンドに --request POST 引数を明示的に追加する必要があります。

curl --request POST \
{full_url_with_placeholders} \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

JSON ボディを含むリクエスト例のコードブロックは、ボディのないリクエスト例と同様に bash シンタックスを使います。

curl https://api.cloudflare.com/api/v4/zones/$ZONE_ID/page_shield/policies \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "description": "My first policy in log mode",
  "action": "log",
  "expression": "http.host eq \"myapp.example.com\"",
  "enabled": "true",
  "value": "script-src myapp.example.com cdnjs.cloudflare.com https://www.google-analytics.com/analytics.js '\''self'\''"
}'

空の error 配列や message 配列がある場合も含め、レスポンス全体を json シンタックスハイライトで示します。

レスポンスはオブジェクト（{ ... }）またはリスト（[ ... ]）で始まります。先頭の文字と末尾の文字は、それぞれ独立した行に置きます。

({|[)
  (...JSON content, pretty printed, using 2-space indents...)
(}|])

• 前のコマンドで取得した ID や、現在の文脈で正確な値が重要でない場合は、ID の代わりにプレースホルダー（例: <RULE_ID>）を使います。同じプレースホルダー名は同じ値に対応させます。異なる ID 値には、異なるプレースホルダー名を使います。
• レスポンスボディの最も重要な部分だけを抜き出した抜粋やスニペットでは、レスポンス全体ではないことを明記します。

{
  "result": {
    "id": "<RULE_ID>",
    "paused": false,
    "description": "do not challenge login from office",
    "action": "allow",
    "priority": null,
    "filter": {
      "id": "<FILTER_ID>",
      "expression": "ip.src in {2400:cb00::/32 2803:f800::/32 2c0f:f248::/32 2a06:98c0::/29} and (http.request.uri.path ~ \"^.*/wp-login.php$\" or http.request.uri.path ~ \"^.*/xmlrpc.php$\")",
      "paused": false,
      "description": "Login from office"
    }
  },
  "success": true,
  "errors": [],
  "messages": []
}