使用GRAPH API V1向SharePoint Online列表添加项时创建空项

核心问题定位 #

POST返回201但列表项为空，大概率是请求体字段映射错误或者字段格式不符合SharePoint列表要求——Graph API对SP自定义字段的引用有特定规则，不能直接用字段显示名。

解决步骤 #

1. 获取字段内部名称 #

Teams创建的SP列表，自定义字段的显示名和内部名称往往不一致（比如显示名"客户名称"，内部名可能是客户名称_x0020_），必须用内部名称作为请求体的字段键：

• 发送GET请求获取列表字段详情：

  GET https://graph.microsoft.com/v1.0/sites/{site-id}/lists/{list-id}/fields
  

• 在返回结果中找到目标字段的internalName属性，比如"internalName": "CustomerName"

2. 修正POST请求体结构 #

创建SP列表项的请求体必须把字段嵌套在fields对象下，示例格式：

{
  "fields": {
    "Title": "测试标题",
    "CustomerName": "ABC公司",
    "OrderDate": "2024-05-20"
  }
}

注意事项：

• 系统默认字段（如Title）直接使用内部名称即可
• 日期字段必须传入ISO 8601格式的字符串
• 选项/查找类型字段需传入对应的值ID，而非显示文本

3. 验证权限配置 #

虽然GET请求正常，但POST操作可能需要更具体的权限：

• 确认Azure应用已授予Sites.ReadWrite.All或Sites.Manage.All应用权限（应用权限适合后台同步场景，委派权限仅适用于当前用户上下文）
• 确保权限已完成管理员同意，否则会出现看似成功但实际无写入权限的异常

4. Postman请求配置检查 #

• 请求方法为POST，URL需正确：POST https://graph.microsoft.com/v1.0/sites/{site-id}/lists/{list-id}/items
• 请求头必须设置Content-Type: application/json
• 令牌需使用应用权限令牌（获取令牌时grant_type设为client_credentials），而非委派权限令牌

5. BPA平台适配要点 #

后续通过BPA的Web Service工具同步数据时，需：

• 将上述正确的请求体格式固化到BPA的请求模板中
• 动态替换字段值时，确保日期、数字等类型格式符合Graph API要求
• 捕获返回的201状态及列表项ID，用于后续的更新/删除操作

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