如何在POST请求中使用query parameter「fields」批量设置视频章节？

一、「fields」参数的核心作用 #

「fields」用来指定API处理请求时需要聚焦的字段——批量更新视频章节时，通过这个参数告诉API只关注章节相关数据，避免冗余的数据处理或返回。

二、批量设置章节的具体步骤 #

1. 确认API配置信息
   先查阅对应API的官方文档，明确：

   • 批量更新视频的接口地址（例如PUT /api/videos/batch）
   • 章节数据对应的字段名（通常是chapters，也可能是chapter_list这类命名，必须和API定义完全一致）

2. 构造请求内容

   • 在URL的query参数中添加fields=chapters（如果需要同时处理其他字段，用逗号分隔即可，比如fields=id,chapters）
   • 请求体中传入要更新的视频ID和对应的章节数组（格式参考你提供的示例）

三、示例请求（Curl） #

curl -X PUT "https://your-api-domain.com/api/videos/batch?fields=chapters" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "videos": [
      {
        "id": "video_001",
        "chapters": [
          {
            "timecode": 15,
            "title": "Chapter title 3"
          },
          {
            "timecode": 25,
            "title": "Chapter title 4"
          }
        ]
      },
      {
        "id": "video_002",
        "chapters": [
          {
            "timecode": 5,
            "title": "Opening"
          },
          {
            "timecode": 120,
            "title": "Conclusion"
          }
        ]
      }
    ]
  }'

四、关键注意事项 #

• 章节数据格式必须严格匹配API要求：比如timecode是否为整数秒、title是否有字符长度限制
• 如果API要求「fields」参数指定所有待修改字段，不要遗漏视频ID字段（例如fields=id,chapters）
• 建议先通过单视频更新请求验证格式正确性，再执行批量操作

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