本文详解如何通过 mapbox datasets api 使用 php curl 成功创建空数据集，重点纠正常见 404 “not found” 错误——根源在于请求 url 格式错误及 payload 结构不当。
本文详解如何通过 mapbox datasets api 使用 php curl 成功创建空数据集，重点纠正常见 404 “not found” 错误——根源在于请求 url 格式错误及 payload 结构不当。
Mapbox 的 Datasets API 要求严格遵循 RESTful 规范：创建新数据集必须向 POST /datasets/v1/{username} 端点发送请求，且请求体（payload）必须是单个 JSON 对象（而非对象数组），同时需确保使用具备 datasets:write 权限的 Secret Token（Admin Token）（非默认 Public Token）。
在原始代码中，存在三个关键错误导致 {"message":"Not Found"} 响应：
-
Payload 结构错误：
$data[] = [...]创建了数组（如[{"name": "..."}]），但 API 仅接受单个对象{"name": "...", "description": "..."}； - Token 权限不足：使用了无写入权限的 Public Access Token；
-
URL 或认证缺失：未验证
access_token参数是否正确拼接，且缺少必要请求头与错误处理。
✅ 正确实现如下（含健壮性增强）：
CurlShip Directory Submission
下载
向CurlShip提交产品，这是一个对机器人友好的SaaS目录。只需一条curl命令即可发布产品，支持OG标签抓取、带徽章的dofollow链接及层级升级。
<?php
// 获取表单数据
$datasetName = $this->request->getPost('dh_dataset_name');
$datasetDesc = $this->request->getPost('dh_dataset_description');
// 构建合法 payload：单个对象，非数组
$payload = json_encode([
'name' => trim($datasetName),
'description' => trim($datasetDesc) ?: null // description 可为 null
]);
// ✅ 关键：正确端点格式 —— 不带尾部斜杠，且 username 为路径参数
$url = sprintf(
'https://api.mapbox.com/datasets/v1/%s?access_token=%s',
urlencode($this->data['dh_mapbox_username']),
$this->data['dh_mapbox_admin_token'] // 必须是 Secret Token（含 datasets:write）
);
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $payload,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json; charset=utf-8',
'Content-Length: ' . strlen($payload)
],
CURLOPT_TIMEOUT => 30,
CURLOPT_SSL_VERIFYPEER => false, // 生产环境请设为 true 并配置 CA bundle
]);
$response = curl_exec($curl);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
$error = curl_error($curl);
curl_close($curl);
// ✅ 强制检查 HTTP 状态码
if ($httpCode === 201) {
$result = json_decode($response, true);
echo "✅ 数据集创建成功！ID: " . $result['id'] . "\n";
} else {
echo "❌ 请求失败 (HTTP {$httpCode}): " . $response . "\n";
if ($error) echo "cURL 错误: {$error}\n";
}⚠️ 重要注意事项：
立即学习“PHP免费学习笔记（深入）”；
-
Token 类型：必须使用 Mapbox Account Tokens 页面 中生成的 Secret Token，并勾选
datasets:write权限；Public Token 仅支持读取操作； -
Username 验证：确保
$this->data['dh_mapbox_username']与你在 Mapbox 账户设置中显示的用户名完全一致（区分大小写）； -
名称规范：
name字段需为 2–32 位字母、数字、下划线或短横线组合，且不能以数字开头； -
调试建议：首次调试时，推荐先在 Postman 中构造相同请求（
POST https://api.mapbox.com/datasets/v1/{username}?access_token={token}+ raw JSON body），再利用其「Code → PHP cURL」功能生成参考代码，可大幅降低配置错误率。
通过修正 payload 结构、升级 Token 权限并规范 URL 拼接，即可稳定调用 Mapbox API 创建空数据集，为后续 GeoJSON 导入与地图可视化奠定基础。
