如何通过Kobo API向KoboToolbox表单提交含图片的数据？

问题背景 #

我需要通过Postman从CSV批量提交带图片的KoboToolbox表单，CSV中图片字段对应的是本地文件名（图片和CSV同目录）。参考教程完成了文本字段的提交，但尝试将图片转为base64放入JSON提交后，虽然提交成功，KoboToolbox中点击图片却无法加载——开发者工具显示图片链接指向https://kobo.humanitarianresponse.info/undefined（返回404），而正常提交的图片链接是https://kobo.humanitarianresponse.info/api/v2/assets/<_uuid>/data/<_id>/attachments/<unknown_id_9digit>/（返回200）。

我用的提交JSON格式如下：

{    
    "id": "aaaaaaaaaaaaaaaaaaa", // form ID from the kobo    
    "submission": {          
        "q1": "{{q1}}" ,
        "image": "data:image/jpg;base64,/9j/4AAQSkZJx..............==",
        "meta": {           
            "instanceID": "uuid:{{_uuid}}"
         }      
    } 
} 

问题原因及解决方案 #

1. 核心问题：Kobo不支持JSON中直接传base64图片 #

KoboToolbox的表单提交接口对附件（图片、文件）有特殊处理逻辑：不能将base64字符串塞进JSON的字段值里。JSON提交仅适用于纯文本类字段，附件必须通过multipart/form-data格式单独上传，否则后端不会将其识别为合法附件，只会当作普通文本存储，最终导致前端找不到资源，出现undefined链接。

2. 正确的提交方式（Postman中） #

• 请求方法设为POST，接口URL使用https://kobo.humanitarianresponse.info/api/v1/submissions
• 切换到Body标签，选择form-data类型
• 添加以下字段：
  • id：填写你的Kobo表单ID
  • submission：类型选Text，内容为包含纯文本字段和meta信息的JSON，示例：

    {
      "q1": "{{q1}}",
      "meta": {
        "instanceID": "uuid:{{_uuid}}"
      }
    }
    

  • 图片字段（比如你的image）：字段名必须和表单中图片问题的变量名完全一致，类型选File，然后选择本地对应的图片文件

3. 批量提交适配CSV的处理 #

• 使用Postman的Collection Runner，导入你的CSV文件
• CSV中图片字段列填写图片的本地路径（建议用绝对路径，或相对Postman工作目录的路径）
• 在form-data的图片字段设置中，用{{你的图片字段变量名}}引用CSV中的路径值，Postman会自动读取对应文件完成批量上传

内容的提问来源于stack exchange，提问作者ralph346526