MapBox API：使用 PHP cURL 创建空数据集的完整教程-php教程-PHP中文网

MapBox API：使用 PHP cURL 创建空数据集的完整教程

本文详解如何通过 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 Directory Submission

向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 ，验证通过后再迁移至 PHP。