如何通过UploadMedia mutation向Sitecore XM Cloud上传媒体时指定ItemId

核心思路 #

XM Cloud的uploadMedia mutation本身不支持直接指定自定义ItemId，但可以通过两步操作实现保留原ItemId的需求：先创建带原ItemId的空媒体项框架，再上传媒体内容关联到该框架。

具体步骤 #

1. 用createItem mutation创建空媒体项

   • 构造请求时，将id参数设为Sitecore 9.3导出的原ItemId（需符合Sitecore GUID格式，带大括号或标准GUID格式）
   • 设置template为对应媒体类型的模板ID（比如图片模板ID为{D14B0C0E-0A85-432D-8DD1-1E3477733991}）
   • 指定parent为目标媒体库文件夹的ItemId
   • 同时可通过fields参数提前填入Alt Text等元数据

   示例mutation：

   mutation CreateMediaItem($input: CreateItemInput!) {
     createItem(input: $input) {
       item {
         id
         name
       }
     }
   }
   

   对应变量示例：

   {
     "input": {
       "id": "{原媒体项的GUID}",
       "template": "{对应媒体类型模板ID}",
       "parent": "{目标父文件夹ItemId}",
       "name": "媒体文件名",
       "fields": [
         {
           "name": "Alt",
           "value": "原Alt Text内容"
         }
       ]
     }
   }
   

2. 用uploadMedia mutation关联媒体内容

   • 调用uploadMedia时，通过itemId参数指定刚创建的带原ItemId的空媒体项ID
   • 传入媒体文件二进制数据、文件名等参数，上传的内容会直接关联到已存在的指定ItemId媒体项，不会生成新ID

   示例mutation：

   mutation UploadMedia($input: UploadMediaInput!) {
     uploadMedia(input: $input) {
       mediaItem {
         id
         name
       }
     }
   }
   

   对应变量示例：

   {
     "input": {
       "itemId": "{原媒体项的GUID}",
       "file": "二进制文件数据",
       "fileName": "媒体文件名",
       "uploadAsNewVersion": false
     }
   }
   

注意事项 #

• 确保原ItemId在XM Cloud中未被占用，否则createItem会执行失败
• 媒体类型模板ID需与原Sitecore 9.3中的媒体类型匹配，避免元数据丢失
• 若原媒体项存在多版本，可将uploadAsNewVersion设为true来保留版本信息

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