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

cURL 命令指南

最后更新 查看 MarkdownAgent 设置

We follow several formatting conventions for cURL commands.

组件

要自动将我们的约定融入您的示例中，请使用：

  • APIRequest：用于命中 Cloudflare API 架构中端点的示例。
  • CURL：用于其他 cURL 命令。

参数名称

为清晰起见，请使用长参数名称：

  • --header（而不是 -H）
  • --request（需要时，而不是 -X）
  • --data（而不是 -d）

您不需要使用 --url 参数，因为它是主要的 cURL 参数。此外，URL 不需要用双引号（""）括起来，除非它包含 ? 字符（即包含查询字符串时）。

缩进

使用两个空格缩进请求或响应体（包含在请求/响应中的额外数据）。

对于包含正文内容的请求，从正文部分（本页示例中 --data 之后的行）开始缩进。这意味着 URL、任何标头以及包含 --data 参数的行都不应缩进。

不包含正文的请求也不应该缩进，以便与包含正文的请求保持一致。

不要将 jq 作为 cURL 示例的一部分

jq ↗ 是一个独立的工具，并非所有人都会安装。cURL 示例不应将通过 jq 格式化响应作为示例的一部分。

如果您必须建议使用此工具，可以添加一个指向 Fundamentals 中 发起 API 调用 页面的链接，该页面提及了此工具。不要在 cURL 示例附近重复关于 jq 的现有内容。

请求指南

准备说明

  • 确保不要在 cURL 命令中使用排版引号或智能引号，否则命令将失败。
  • URL 中的占位符应遵循与 API 文档相同的格式：$ZONE_ID
  • 请求正文（即 POST/PUT/PATCH 请求中包含的数据）中的占位符应使用尖括号：<RULE_ID>。

相同的占位符名称应对应相同的值——为不同的 ID 值使用不同的占位符名称。如果您希望响应中的值与请求中的值相匹配，可以在响应中使用相同的请求占位符。

身份验证 HTTP 标头

如果使用 Email + API Key 身份验证，请在 cURL 命令中包含以下参数，以向请求中添加两个必需的 HTTP 标头：

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

如果使用 API 令牌（API Token，首选身份验证方法），请在 cURL 命令中包含以下参数，以向请求中添加所需的 HTTP 标头：

--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \

不包含正文内容的请求（GET、DELETE）

对于 GET 请求，请勿包含 --request GET 命令行参数，因为在请求不包含正文时这是默认行为，且不建议在 GET/POST 请求中使用：

GET 请求模板

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

DELETE 请求模板

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

没有正文的请求不需要语法高亮，但我们使用 bash 语法高亮来突出显示多个有界定符的字符串。

带有 JSON 正文内容的请求（POST、PUT、PATCH）

如果请求包含正文，请务必包含 Content-Type 标头。对于包含 JSON 内容的请求，该标头应为 Content-Type: application/json。

此标头应出现在身份验证标头之后。

对于包含正文的 POST 请求，请勿包含 --request POST 命令行参数，因为当请求包含正文时这是默认行为。

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...)
(}|])'
Examplebash
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"
  }
]'

PUT/PATCH 请求模板

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 的终端中运行该命令）：

  • 将单引号 ' 替换为 '\''

意思是“关闭字符串，添加转义的单引号，重新开始字符串”。

Examplebash
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 请求

如果您发起不包含正文的 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'\''"
}'

响应指南

使用 json 语法高亮包含完整的响应（包括任何空的 error 和 message 数组，如果存在的话）。

响应要么以对象（{ ... }）开头，要么以列表（[ ... ]）开头。首字符和尾字符应各自独占一行。

({|[)
  (...JSON content, pretty printed, using 2-space indents...)
(}|])
  • 如果存在通过先前命令获取的 ID，或者它们的精确值在当前上下文中并不重要，请使用占位符（例如 <RULE_ID>）代替实际 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": []
}

这篇文档对您有帮助吗？