Shopify Admin API

批量 mutation 上传 JSONL 后启动失败怎么查

现象#

stagedUploadsCreate 已经返回了 url,但把 JSONL POST 上去得到 400,随后 bulkOperationRunMutation 提示 stagedUploadPath 无效,文件其实只有 3MB。

原因#

  • 上传时没有带上返回的 parameters 表单字段,签名对不上被存储端拒绝
  • resource 申请成 FILE,JSONL 输入要用 BULK_MUTATION_VARIABLES
  • 把 url 当成 stagedUploadPath 传入,实际要用返回里的 resourceUrl
  • JSONL 某一行不是合法 JSON,或键名与内层 mutation 的变量对不上,整行静默失败

处理步骤#

  1. 用 stagedUploadsCreate 申请,参数含 resource、filename 与 httpMethod
  2. 按返回顺序先追加所有 parameters,最后再追加名为 file 的文件字段
  3. 上传成功后取 resourceUrl,原样作为 stagedUploadPath 使用
  4. 校验每行是一个 variables 对象,键名与内层 mutation 参数完全一致,文件小于 100MB
  5. 启动后查 bulkOperation.status,已有任务在跑时先取消再提交

验收标准#

bulkOperationRunMutation 的 userErrors 为空,状态进入 RUNNING,完成后结果文件行数等于输入行数。

本文由 风格技术 技术团队整理,适用于 Shopify 标准版与 Plus 店铺。Shopify 平台能力迭代较快,具体操作路径与字段以官方文档和店铺后台实际版本为准。