# API 参考
## 客户端初始化
### TypeScript
typescript
import Cloudflare from 'cloudflare';
const client = new Cloudflare({
apiToken: process.env.CLOUDFLARE_API_TOKEN,
});
### Python
python
from cloudflare import Cloudflare
client = Cloudflare(api_token=os.environ.get("CLOUDFLARE_API_TOKEN"))
# 异步方式:
from cloudflare import AsyncCloudflare
client = AsyncCloudflare(api_token=os.environ["CLOUDFLARE_API_TOKEN"])
### Go
go
import (
"github.com/cloudflare/cloudflare-go/v4"
"github.com/cloudflare/cloudflare-go/v4/option"
)
client := cloudflare.NewClient(
option.WithAPIToken(os.Getenv("CLOUDFLARE_API_TOKEN")),
)
## 认证
### API Token (推荐)
**创建 Token**: 控制面板 → 我的个人资料 → API Tokens → 创建 Token
bash
export CLOUDFLARE_API_TOKEN='your-token-here'
curl "https://api.cloudflare.com/client/v4/zones"
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
**Token 范围**: 始终使用最小权限（特定区域、限时）。
### API Key (旧版)
bash
curl "https://api.cloudflare.com/client/v4/zones"
--header "X-Auth-Email:
[email protected]"
--header "X-Auth-Key: $CLOUDFLARE_API_KEY"
**不推荐：** 拥有完全账户访问权限，无法限制权限范围。
## 自动分页
所有 SDK 均支持列表操作的自动分页。
typescript
// TypeScript: for await...of
for await (const zone of client.zones.list()) {
console.log(zone.id);
}
python
# Python: 迭代器协议
for zone in client.zones.list():
print(zone.id)
go
// Go: ListAutoPaging
iter := client.Zones.ListAutoPaging(ctx, cloudflare.ZoneListParams{})
for iter.Next() {
zone := iter.Current()
fmt.Println(zone.ID)
}
## 错误处理
typescript
try {
const zone = await client.zones.get({ zone_id: 'xxx' });
} catch (err) {
if (err instanceof Cloudflare.NotFoundError) {
// 404
} else if (err instanceof Cloudflare.RateLimitError) {
// 429 - SDK 会自动重试并退避
} else if (err instanceof Cloudflare.APIError) {
console.log(err.status, err.message);
}
}
**常见错误类型：**
- `AuthenticationError` (401) - Token 无效
- `PermissionDeniedError` (403) - 权限不足
- `NotFoundError` (404) - 资源未找到
- `RateLimitError` (429) - 超出速率限制
- `InternalServerError` (≥500) - Cloudflare 服务器错误
## 区域管理
typescript
// 列出区域
const zones = await client.zones.list({
ac
粤公网安备44030002003366号