使用Graph API设置SharePoint元数据字段时的命名问题

场景与实现代码 #

我正在使用C#中的Graph API设置SharePoint中文档的元数据字段，实现代码如下：

public async Task SetMetaData(SharePointFile file, params MetaDataField[] fields)
{
    FieldValueSet fieldValueSet = new()
    {
        AdditionalData = fields.ToDictionary(x => x.Name, x => x.Value)
    };
    
    await _graphClient.Drives[file.Library.Id].Items[file.Id].ListItem.Fields
        .Request()
        .UpdateAsync(fieldValueSet);
}

多数情况下该代码运行正常，但遇到两个问题：

问题1：重命名字段后新名称无法识别 #

重命名字段后，使用新名称无法识别该字段，查看库设置发现URL未更新，使用旧名称仍可正常操作，获取元数据时也显示旧名称。请问如何获取新名称并关联到旧名称？

解决方案 #

SharePoint字段重命名后，**显示名称（Display Name）会更新，但内部名称（Internal Name）**不会改变——这就是新名称失效、旧名称仍可用的核心原因。

要关联新显示名称与旧内部名称，需先获取字段的完整属性：

• 调用Graph API的/sites/{site-id}/lists/{list-id}/fields接口，获取目标文档库的所有字段信息
• 遍历返回的字段集合，通过DisplayName匹配新名称，找到对应的InternalName
• 后续操作元数据时，始终使用InternalName作为字段键名

示例代码片段：

// 获取指定列表的所有字段
var fields = await _graphClient.Sites[siteId].Lists[listId].Fields.Request().GetAsync();
// 根据新显示名称匹配对应的内部名称
var targetField = fields.FirstOrDefault(f => f.DisplayName == "新字段名称");
if (targetField != null)
{
    string internalName = targetField.InternalName;
    // 使用internalName作为键设置元数据
}

问题2：字段名含冒号时设置无效果 #

若字段名包含冒号，请求显示“成功”但字段值未更改。我了解位置类字段会拆分为如“TestLocation:Country”这类格式，这是否存在冲突？该如何解决？（本次测试使用的是简单文本字段）

解决方案 #

Graph API中，冒号是复杂字段（如位置、分类字段）的子属性分隔符，普通文本字段名称含冒号会被API误解析为复杂字段的子属性，导致设置失效。

有两种可行的解决方式：

1. 修改字段内部名称：在SharePoint库设置中重新创建不含冒号的字段；或通过PowerShell修改现有字段的内部名称（注意：修改内部名称需谨慎，可能影响现有依赖逻辑）
2. 使用字段ID替代名称：调用/sites/{site-id}/lists/{list-id}/fields获取目标字段的Id，更新元数据时用fields({field-id})的方式指定字段：

// 假设已获取到目标字段的Id
var fieldId = "xxxx-xxxx-xxxx-xxxx";
var fieldValueSet = new FieldValueSet
{
    AdditionalData = new Dictionary<string, object>
    {
        { $"fields({fieldId})", "要设置的字段值" }
    }
};
await _graphClient.Drives[file.Library.Id].Items[file.Id].ListItem.Fields
    .Request()
    .UpdateAsync(fieldValueSet);

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