如何通过PUT REST API更新Strapi CMS的可重复项/媒体资源

问题背景 #

现有Strapi文档数据如下：

{
  "data": {
    "id": 5,
    "documentId": "bui11070zyexg20k1xg9fdxx",
    "name": "Test Document",
    "createdAt": "2024-12-13T05:52:18.359Z",
    "updatedAt": "2024-12-13T21:15:20.414Z",
    "publishedAt": "2024-12-13T21:15:20.966Z",
    "locale": "en",
    "assets": [
      {
        "id": 8,
        "documentId": "pku4d0m6e5x43ehr0f6o6ar7",
        "name": "142bdf157191583.63749e49bcb3a.jpg",
        "alternativeText": null,
        "caption": null,
        "width": 2048,
        "height": 2048,
        ...
      },
      {
        "id": 7,
        "documentId": "noz98h30ln5qatv7gc5nqhhp",
        "name": "27a5197bdaf301a49d1fa23eb2391256.png",
        "alternativeText": null,
        "caption": null,
        "width": 900,
        "height": 900,
        ...
      }
    ]
  },
  "meta": {}
}

尝试通过文档的PUT接口更新时，遇到Invalid relations或Invalid key documentId的400错误，仅更新name字段可正常执行。

错误原因 #

Strapi中，assets属于关联字段，文档的PUT接口仅负责管理资产与文档的关联关系（添加/移除资产），无法直接通过该接口修改资产本身的属性（如caption）。直接传递资产对象会被判定为无效关联，而传递documentId这类Strapi内部字段会触发验证错误。

正确更新方式 #

1. 更新单个媒体资源的属性 #

每个媒体资源（Asset）都有独立的API接口，直接调用该接口修改指定属性：

• 请求地址：https://localhost/api/upload/files/{assetId}（替换{assetId}为目标资产的id，比如8或7）
• 请求方法：PUT
• 请求体（仅传需要修改的字段）：

{
  "data": {
    "caption": "Test 1"
  }
}

2. 批量更新关联到文档的媒体资源属性 #

若要修改文档关联的所有资产属性，需逐个调用单个资产的PUT接口，无法通过文档接口一次性完成。

3. 修改文档与资产的关联关系（添加/替换资产） #

如果只是要调整文档关联的资产列表（而非修改资产属性），则在文档的PUT接口中传递资产的id数组：

• 请求地址：https://localhost/api/documents/bui11070zyexg20k1xg9fdxx
• 请求体：

{
  "data": {
    "name": "Test Document Updated",
    "assets": [8, 7] // 此处为资产的id，用于指定关联的资产
  }
}

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