读取域名的 DNS 记录
查询 A、AAAA、CNAME 等解析记录,供部署检查和配置归档。
← 返回平台功能接入准备
- Token 具备 Zone → DNS → Read 或 Edit,并包含目标 Zone。
准备环境变量
示例值需要替换为自己的凭证或资源 ID。代码在本机或服务端运行;密钥不应放进公开网页。
CLOUDFLARE_API_TOKEN- 使用自定义 API Token,并限制到指定 Zone;不要使用 Global API Key。
CLOUDFLARE_ZONE_ID- 域名 Overview 页的 Zone ID,或按本站获取 Zone ID 场景查询 result[].id;这里是虚构值。
export CLOUDFLARE_API_TOKEN='replace_with_scoped_api_token'
export CLOUDFLARE_ZONE_ID='00000000000000000000000000000000'以上 export 适用于 macOS / Linux 的终端,在同一终端内运行后续代码。Python 示例保存为 request.py 后执行 python3 request.py。
调用步骤
- 01
登录 Cloudflare 控制台 → My Profile → API Tokens → Create Token → Create Custom Token。
- 02
Permissions 只添加 Zone → DNS → Read;Zone Resources 选择 Include → Specific zone → 你的域名。
- 03
按需要限制客户端 IP、有效时间,确认摘要后生成;只在本地或服务器环境变量保存 CLOUDFLARE_API_TOKEN。
- 04
在域名 Overview 页取得 Zone ID,保存为 CLOUDFLARE_ZONE_ID;也可按本站上一场景查询。
- 05
执行列表请求后按 result_info.total_pages 翻页;应用端比较记录,不需要为读取操作授予写权限。
列出 DNS 记录
示例每页 100 条,返回记录 ID、类型、名称、内容、TTL 和代理状态。
https://api.cloudflare.com/client/v4/zones/${CLOUDFLARE_ZONE_ID}/dns_records?per_page=100&page=1请求头
AuthorizationBearer ${CLOUDFLARE_API_TOKEN}
参数说明
参数表可左右滑动,查看完整说明。
| 字段 / 位置 | 类型 / 必填 | 说明 |
|---|---|---|
zone_idPath | string必填 | 目标域名的 Zone ID,不是 Account ID。 |
per_page / pageQuery | integer可选 | 本例 100 条、第 1 页;从 result_info 获取分页状态。 |
typeQuery | string可选 | 可按记录类型筛选,如 A;省略为全部类型。 |
调用代码
替换示例 ID 与请求体内容后运行。cURL 会报 HTTP 错误,业务状态还需按下方返回示例核对。
# 执行后核对返回 JSON 的业务状态;HTTP 200 仍可能包含业务错误。
curl --silent --show-error --fail-with-body \
--request GET \
--url "https://api.cloudflare.com/client/v4/zones/${CLOUDFLARE_ZONE_ID}/dns_records?per_page=100&page=1" \
--header "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}"
import json
import os
import re
import urllib.request
import urllib.error
def expand(value):
return re.sub(r"\$\{([A-Z][A-Z0-9_]*)\}",
lambda match: os.environ[match.group(1)], value)
url = expand("https://api.cloudflare.com/client/v4/zones/${CLOUDFLARE_ZONE_ID}/dns_records?per_page=100&page=1")
headers = {
"Authorization": expand("Bearer ${CLOUDFLARE_API_TOKEN}"),
}
data = None
request = urllib.request.Request(url, data=data, headers=headers, method="GET")
try:
with urllib.request.urlopen(request, timeout=30) as response:
result = json.load(response)
except urllib.error.HTTPError as error:
print(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}")
raise SystemExit(1)
print(json.dumps(result, ensure_ascii=False, indent=2))
if isinstance(result, dict) and "success" in result and result["success"] != True:
raise SystemExit("平台返回业务错误,请结合下方排错说明检查响应")
// Node.js 22+,保存为 request.mjs 后运行 node request.mjs
function expand(value) {
return value.replace(/\$\{([A-Z][A-Z0-9_]*)\}/g, (_, name) => {
if (!process.env[name]) throw new Error(`缺少环境变量 ${name}`);
return process.env[name];
});
}
const url = expand("https://api.cloudflare.com/client/v4/zones/${CLOUDFLARE_ZONE_ID}/dns_records?per_page=100&page=1");
const headers = Object.fromEntries(
Object.entries({
"Authorization": "Bearer ${CLOUDFLARE_API_TOKEN}"
}).map(([key, value]) => [key, expand(value)])
);
const response = await fetch(url, {
method: "GET",
headers,
signal: AbortSignal.timeout(30000),
});
const text = await response.text();
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`);
const result = JSON.parse(text);
console.log(JSON.stringify(result, null, 2));
if (Object.hasOwn(result, "success") && result["success"] !== true) {
throw new Error('平台返回业务错误,请结合下方排错说明检查响应');
}
返回示例
按官方字段整理的响应结构示意,ID、文本和数字均为虚构,非接口实测结果。result[].id 是后续查询单条记录所需的标识;本例只读。 以下为结构示意,非本站实测结果。
{
"success": true,
"errors": [],
"messages": [],
"result": [
{
"id": "22222222222222222222222222222222",
"type": "A",
"name": "www.example.com",
"content": "192.0.2.1",
"ttl": 1,
"proxied": true
}
],
"result_info": {
"page": 1,
"per_page": 100,
"total_pages": 1,
"count": 1,
"total_count": 1
}
}常见错误与排查
HTTP 401 / 403认证或权限校验未通过。- 核对 Bearer Token、资源范围、有效期与 IP 限制;读取返回 errors[].message 确认具体原因。
HTTP 429管理 API 触发限流。- 遵守 retry-after,降低并发;全局额度与产品专属配额分别检查。
调用注意
- 读取的是 Cloudflare 保存的配置,不证明全球递归 DNS 缓存已更新,也不能据此判断网站源站健康。
- 代理记录的 content 仍是源站配置,需按自己系统的数据访问规则保存;不要将完整区域配置随意公开。
注意事项
- 一般管理 API 为每用户或账号 Token 每 5 分钟 1,200 次,另有每 IP 每秒 200 次限制;产品端点可能更严格。
- 这里仅使用域名管理 API;套餐的 DNS/CDN 等资源规则继续适用,不把 Token 本身当成产品套餐。
核验来源
本站按官方资料整理本场景的必要调用步骤与代码,覆盖范围以本页列出的接口为准。官方资料用于追溯规范及查看变更。
- 01创建 API Token 并限制资源范围核验日期 2026-10-15
- 02Cloudflare 管理 API 限流核验日期 2026-10-15
- 03List DNS Records核验日期 2026-10-15