使用Migration API迁移至SharePoint Online时配置Lookup及用户字段类型

我之前在做SPO文件迁移项目时也碰到过一模一样的问题——Migration API搞定文件迁移没问题，但Lookup、用户这类带关联的字段就是没法直接通过迁移时的元数据设置生效。下面是我总结的几种可行方案，亲测有效：

方案1：迁移完成后用CSOM/Graph API批量更新字段 #

这是最直接的方式，因为Migration API的核心是文件内容迁移，复杂字段的更新交给更适合处理列表项的API来做会更稳妥。

具体步骤： #

• 迁移文件时，记录每个文件对应的目标文档库Item ID（可以通过Migration API的返回结果获取，或者后续通过文件名+路径匹配查找）
• 用CSOM连接到SPO站点，针对每个Item更新复杂字段：
  • Lookup字段：创建FieldLookupValue对象，设置LookupId为关联列表中目标项的ID
  • 用户字段：创建FieldUserValue对象，设置LookupId为用户的SPO ID，或者用LoginName指定用户身份

C#代码示例（CSOM）： #

using Microsoft.SharePoint.Client;
using System.Security;

// 初始化CSOM上下文
var siteUrl = "https://yourtenant.sharepoint.com/sites/yoursite";
var username = "admin@yourtenant.onmicrosoft.com";
var password = "your-secure-password";

var securePassword = new SecureString();
foreach (char c in password) securePassword.AppendChar(c);
var credentials = new SharePointOnlineCredentials(username, securePassword);

using (var ctx = new ClientContext(siteUrl))
{
    ctx.Credentials = credentials;

    // 获取目标文档库中的文件项
    var list = ctx.Web.Lists.GetByTitle("Documents");
    var item = list.GetItemById(123); // 替换为实际的Item ID

    // 更新Lookup字段（假设字段内部名称为"ProjectLookup"，关联项ID为456）
    var lookupValue = new FieldLookupValue { LookupId = 456 };
    item["ProjectLookup"] = lookupValue;

    // 更新用户字段（假设字段内部名称为"AssignedTo"，用户ID为789）
    var userValue = new FieldUserValue { LookupId = 789 };
    item["AssignedTo"] = userValue;

    // 提交更改
    item.Update();
    ctx.ExecuteQuery();
}

方案2：迁移时通过Migration API的元数据映射直接设置 #

其实Migration API并非完全不能处理复杂字段，只是需要按照SPO字段的特定格式传递元数据，而不是普通的文本值。

关键要点： #

• Lookup字段：元数据值需要传入"LookupId:XXX"格式的字符串，其中XXX是关联列表中目标项的ID
• 用户字段：可以传入用户的登录名（格式如i:0#.f|membership|user@tenant.onmicrosoft.com），或者用户ID对应的字符串

迁移时设置元数据的示例片段： #

// 构建迁移元数据字典
var metadata = new Dictionary<string, object>();
// 设置Lookup字段（内部名称"ProjectLookup"）
metadata["ProjectLookup"] = "LookupId:456";
// 设置用户字段（内部名称"AssignedTo"）
metadata["AssignedTo"] = "i:0#.f|membership|john.doe@yourtenant.onmicrosoft.com";

// 将元数据传入Migration API的迁移请求中
// 这里替换为你之前使用的Migration API代码，将metadata附加到文件迁移请求里

注意事项 #

• 确保你使用的账号拥有文档库的编辑权限以及关联列表的读取权限（Lookup字段需要读取关联项的ID）
• 所有字段请使用内部名称，而不是显示名称（可以通过SPO站点的列表设置→字段设置查看内部名称）
• 如果是批量迁移，建议采用批量更新的方式（CSOM的LoadBatch或Graph API的批量请求），避免频繁调用API导致性能问题或阈值限制

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