本文详解如何通过 Mapbox Datasets API 正确使用 PHP cURL 创建新空数据集，重点解决因 URL 错误、请求体格式不当或认证缺失导致的 {"message":"Not Found"} 错误。
本文详解如何通过 mapbox datasets api 正确使用 php curl 创建新空数据集，重点解决因 url 错误、请求体格式不当或认证缺失导致的 `{"message":"not found"}` 错误。
在 Mapbox 的 Datasets API v1 中，创建空数据集需向 POST https://api.mapbox.com/datasets/v1/{username} 发送 JSON 格式的请求体（不含数组包裹），并携带有效的 Admin Access Token（非默认 Secret Token）。常见错误如 {"message":"Not Found"} 通常并非权限问题，而是由以下三个关键原因导致：
✅ 1. 请求 URL 格式错误
原始代码中 $url 拼接为：
$url = "https://api.mapbox.com/datasets/v1/[snip:username]?access_token=[snip]";
⚠️ 错误点：[snip:username] 未被真实用户名替换，且未确认是否使用了 Admin 类型 Token（仅 Admin Token 支持写操作）。
✅ 正确写法（含变量安全拼接）：
$username = urlencode($this->data['dh_mapbox_username']); // 防止特殊字符破坏 URL
$token = $this->data['dh_mapbox_admin_token'];
$url = "https://api.mapbox.com/datasets/v1/{$username}?access_token={$token}";✅ 2. 请求体结构非法（最常见根源）
原始代码将数据封装为数组再 JSON 编码：
$data[] = array('name' => ..., 'description' => ...); // ❌ 错误：生成 [ { ... } ] 数组
$payload = json_encode($data); // → [{"name":"x","desc":"y"}]⚠️ Mapbox API 要求 直接提交单个对象（非数组），否则返回 404 Not Found（API 会静默拒绝非法 payload，不报 400）。
✅ 正确写法：
$data = [
'name' => trim($this->request->getPost('dh_dataset_name')),
'description' => trim($this->request->getPost('dh_dataset_description'))
];
$payload = json_encode($data); // → {"name":"x","description":"y"}✅ 3. cURL 配置不完整或缺少错误处理
原始代码缺少超时、重定向、错误捕获等健壮性设置，且未检查 HTTP 状态码。推荐使用 curl_setopt_array() 统一配置，并始终验证响应：
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true, // 明确声明 POST
CURLOPT_POSTFIELDS => $payload,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'Accept: application/json'
],
CURLOPT_TIMEOUT => 30,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_SSL_VERIFYPEER => false, // 生产环境请设为 true 并配置 CA 证书
]);
$response = curl_exec($curl);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
$error = curl_error($curl);
curl_close($curl);
if ($httpCode === 201) {
$result = json_decode($response, true);
echo "✅ 数据集创建成功！ID: {$result['id']}, 名称: {$result['name']}";
} else {
echo "❌ 请求失败 (HTTP {$httpCode}): {$error}\n";
echo "响应内容: {$response}";
}? 重要注意事项：
向CurlShip提交产品，这是一个对机器人友好的SaaS目录。只需一条curl命令即可发布产品，支持OG标签抓取、带徽章的dofollow链接及层级升级。
- ? 必须使用 Admin Access Token（在 Mapbox Account Tokens 页面 创建时勾选
datasets:write权限）；普通 Secret Token 或 Default Token 无权创建数据集。 - ?
name字段需符合规范：仅允许字母、数字、下划线、短横线，长度 2–32 字符，且全局唯一（同一用户名下不可重复）。 - ?️ 生产环境务必启用
CURLOPT_SSL_VERIFYPEER => true并配置系统 CA 证书路径（如curl_setopt($curl, CURLOPT_CAINFO, '/path/to/cacert.pem');）。 - ? 建议先用 Postman 测试：选择
POST→ URL →Body > raw > JSON→ 输入{"name":"test","description":"demo"}→ Headers 添加Authorization: Bearer <admin_token></admin_token>，验证通过后再迁移至 PHP。
通过修正 URL、净化请求体结构、完善 cURL 配置及权限校验，即可稳定调用 Mapbox Datasets API 创建空数据集。
