Lists API 端点

要调用 Lists API 操作，请将端点追加到 Cloudflare API 基础 URL：

https://api.cloudflare.com/client/v4/

有关身份验证说明，请参阅 Cloudflare API 的 快速入门 页面。

有关发起 API 调用以及分页结果的帮助，请参阅 发起 API 调用。

Lists API 支持以下操作。请访问相关链接查看示例。

• 操作：Create a list
• 方法与端点：POST accounts/{account_id}/rules/lists
• 说明：创建空列表。

• 操作：Get lists
• 方法与端点：GET accounts/{account_id}/rules/lists
• 说明：
  • 获取该账户下的所有列表。
  • 此请求不会获取列表中的条目。

• 操作：Get a list
• 方法与端点：GET accounts/{account_id}/rules/lists/{list_id}
• 说明：
  • 按 ID 获取列表。
  • 此请求不会显示列表中的条目。

• 操作：Update a list
• 方法与端点：PUT accounts/{account_id}/rules/lists/{list_id}
• 说明：
  • 更新列表的 description。
  • 您无法编辑 name 或 kind，也无法通过此操作更新列表中的条目。要更新列表中的条目，请使用 Update all list items 操作。

• 操作：Delete a list
• 方法与端点：DELETE accounts/{account_id}/rules/lists/{list_id}
• 说明：删除列表，但仅当没有 filters 引用它时才能删除。

几乎所有用于管理列表条目的操作都是异步的。当您向列表添加或从列表删除大量条目时，批量操作完成前可能会有延迟。

异步列表操作会返回 operation_id，您可用它来监控 API 操作的状态。要监控异步操作的状态，请使用 Get bulk operation status 端点，并指定要监控的操作 ID。

当某个列表上的批量操作进行中时，若再向该列表发出请求，这些请求会排队并按顺序处理（先进先出）。成功的异步操作请求返回 HTTP 201 状态码。

• 操作：Get list items
• 方法与端点：GET accounts/{account_id}/rules/lists/{list_id}/items[?search={query}]
• 说明：
  • 获取列表中的条目（默认获取全部条目）。
  • 条目按升序排序。
  • 对于 IP 列表，CIDR 先按 IP 地址排序，再按子网掩码排序。
  • 要筛选返回的条目，请使用可选的 search 查询字符串参数。更多信息请参阅 Get list items API 操作。

• 操作：Get a list item
• 方法与端点：GET accounts/{account_id}/rules/lists/{list_id}/items/{item_id}
• 说明：按 ID 从列表中获取一个条目

• 操作：Create list items
• 方法与端点：POST accounts/{account_id}/rules/lists/{list_id}/items
• 说明：
  • 向列表追加一个或多个新条目。
  • 会替换列表中已存在的条目，但不会删除任何条目。
  • 会覆盖原有条目的 comment。
  • 响应包含 operation_id。

• 操作：Update all list items
• 方法与端点：PUT accounts/{account_id}/rules/lists/{list_id}/items
• 说明：
  • 删除列表中的当前全部条目，并用 items 替换。
  • 当 items 为空时，删除列表中的全部条目。
  • 响应包含 operation_id。

• 操作：Delete list items
• 方法与端点：DELETE accounts/{account_id}/rules/lists/{list_id}/items
• 说明：
  • 删除指定的列表条目。
  • 响应包含 operation_id。