如何正确在 Autodesk Forge 中创建 Bucket 存储桶

本文详解 Forge OSS 服务中创建 Bucket 的完整流程，涵盖身份认证、请求构造、命名规范与常见 400 错误排查，帮助开发者快速定位并解决 createBucket 接口调用失败问题。

本文详解 forge oss 服务中创建 bucket 的完整流程，涵盖身份认证、请求构造、命名规范与常见 400 错误排查，帮助开发者快速定位并解决 `createbucket` 接口调用失败问题。

在 Autodesk Platform Services（APS，原 Autodesk Forge）中，Bucket 是对象存储（OSS）服务的核心容器，用于上传、存储和管理模型文件（如 .rvt、.ifc、.dwg 等）及其转换后的可视化资源（如 SVF/SVF2）。但许多开发者在调用 POST /buckets 接口时频繁遭遇 HTTP 400 Bad Request 错误——这通常并非代码逻辑错误，而是由认证配置或参数合规性引发的“静默拒绝”。

✅ 正确创建 Bucket 的关键前提

1. OAuth 2.0 凭据必须具备 data:write 权限
   创建 Bucket 需要 bucket:create 作用域（scope），该权限必须在获取 2-legged 或 3-legged 访问令牌（access token）时显式声明。例如，使用 2-legged 流程获取 token 时，scope 参数应至少包含：

   ["bucket:create", "data:write"]

   若仅申请了 data:read，则 createBucket 调用将直接返回 400（而非 403），因 APS 服务端校验 scope 失败后统一返回 Bad Request。

2. Callback URL 必须严格一致
   如答案所强调：APS 开发者门户中应用的 Callback URL，必须与你后端服务实际发起 OAuth 请求时使用的重定向地址完全一致（含协议、端口、路径及尾部斜杠）。即使仅修改了本地开发环境的 http://localhost:3000/auth/callback 为 http://127.0.0.1:3000/auth/callback，也会导致后续所有 API 调用（包括 createBucket）因 token 绑定失效而失败。请务必在 APS Dashboard → Your App → Authentication 中核对并同步更新。

3. Bucket Key 命名必须符合规范
   bucketKey 是全局唯一标识符，需满足以下强制要求：

   • 全小写（a–z）、数字（0–9）、连字符（-）和下划线（_）
   • 长度 3–128 字符
   • 必须以字母或数字开头和结尾
   • 不能包含连续连字符（如 my--bucket ❌）
   • 不能是保留字（如 public、shared）

   在你的代码中：

   payload.bucketKey = config.credentials.client_id.toLowerCase() + '-' + req.body.bucketKey;

   若 req.body.bucketKey 为空、含非法字符（如空格、大写字母、点号），或拼接后以 - 开头/结尾（例如 abc- 或 -test），均会触发 400。建议添加服务端校验：

   const bucketKey = (config.credentials.client_id.toLowerCase() + '-' + req.body.bucketKey)  .replace(/[^a-z0-9-_]/g, '-') // 替换非法字符为 -  .replace(/^-+|-+$/g, '')        // 去首尾 -  .replace(/-{2,}/g, '-');         // 合并连续 -if (!/^[a-z0-9]/.test(bucketKey) || !/[a-z0-9]$/.test(bucketKey)) {  return res.status(400).json({ error: 'Invalid bucketKey format' });}payload.bucketKey = bucketKey;

? 完整可运行示例（Node.js + APS SDK）

// routes/buckets.jsconst { BucketsApi, PostBucketsPayload } = require('forge-apis');const config = require('../config');router.post('/api/forge/oss/buckets', async (req, res) => {  try {    // ✅ 1. 校验请求体    const { bucketKey } = req.body;    if (!bucketKey || typeof bucketKey !== 'string') {      return res.status(400).json({ error: 'Missing or invalid bucketKey' });    }    // ✅ 2. 构造合法 bucketKey    const safeKey = `${config.credentials.client_id.toLowerCase()}-${bucketKey.trim()}`      .toLowerCase()      .replace(/[^a-z0-9-_]/g, '-')      .replace(/^-+|-+$/g, '')      .replace(/-{2,}/g, '-');    // ✅ 3. 构建 payload（policyKey 必须为 'transient' 或 'persistent'）    const payload = new PostBucketsPayload();    payload.bucketKey = safeKey;    payload.policyKey = 'persistent'; // 数据长期保留（推荐用于生产）    // ✅ 4. 调用 API（确保 req.oauth_token 已通过 auth middleware 注入且含 bucket:create scope）    const bucketsApi = new BucketsApi();    const result = await bucketsApi.createBucket(      payload,      {}, // options（空对象即可）      req.oauth_client,      req.oauth_token    );    res.status(201).json({ bucketKey: result.body.bucketKey });  } catch (err) {    console.error('Failed to create bucket:', err.response?.body || err.message);    res.status(err.status || 500).json({       error: err.response?.body?.reason || 'Bucket creation failed'     });  }});

⚠️ 注意事项与最佳实践

• 不要复用测试环境的 Client ID/Secret 到生产：更换凭证后，务必重新生成访问令牌，并确认新 token 的 scope 包含 bucket:create。
• policyKey 选型：
  • 'transient'：对象 24 小时后自动清理（适合临时测试）；
  • 'persistent'：对象长期保留（生产环境首选）。
• 错误日志优先看 err.response.body.reason：APS 的 400 响应体通常包含明确原因，例如：

  { "reason": "The bucket key is invalid. It must be 3-128 characters long and contain only lowercase letters, numbers, and hyphens." }

• 前端调用需携带有效认证头：若前端直接调用 /api/forge/oss/buckets，确保请求已附带 Authorization: Bearer <token>，且该 token 由后端安全签发（避免前端暴露 client_secret）。

掌握以上要点，即可稳定创建 Bucket，为后续模型上传、翻译（Derivative API）与 Forge Viewer 集成奠定坚实基础。记住：Forge 的“不可见约束”（如 scope、callback 一致性、命名规则）往往比代码逻辑更易成为故障根源——严谨验证，方得始终。