就在大家以为“Power Automate 里处理 SharePoint 列表拖个‘获取列表项’就够用”的时候我们这些天天跟列表数据打交道的人早就已经把目光转向了 REST API。原因很简单列表超过 5000 行之后内置操作开始卡顿、超时、被阈值限制拦住而当你需要在几十条甚至几百条数据里做批量更新、条件过滤、字段变形时标准连接器的操作组合会让你怀疑人生。这篇文章不讲花哨概念只讲一件事怎么在 Power Automate 里用 SharePoint REST API 把列表数据批量处理干净并且把 JSON 解析这部分拆开揉碎说清楚。适合正在做审批流、数据同步、定时批量更新或者被“failed to deserialize the json body”这类报错折磨过的朋友。1. 为什么放着现成连接器不用非要自己发 REST API 请求1.1 内置“获取列表项”操作在批量场景中的瓶颈先别急着否定传统方式。Power Automate 自带的 SharePoint 连接器里“获取列表项”“创建列表项”“更新列表项”这些操作确实方便拖拽就能用。问题出在“批量”和“复杂条件”上。连接器里的“获取列表项”默认一次只拿回一部分数据即使你在设置里把行数拉到 5000它背后也只是简单地对列表做了一次查询。遇到以下几种情况就会很难受列表项总数超过列表视图阈值默认 5000查询直接报错或需要走索引设置你需要按多个字段组合筛选比如“状态等于进行中且负责人等于当前用户”内置筛选器的搭建过程非常绕你希望把列表字段按照 InternalName内部名称精确读取但连接器默认暴露的是显示名称字段一旦改名流程就断了你想批量更新几十条记录常规做法只能套一个“Apply to each”循环一次一次调用“更新列表项”跑起来慢调用次数还难看。相比之下直接用 HTTP 请求调 SharePoint REST API相当于把底层接口的操作权拿回自己手里。筛选、排序、取前 N 条、走 $batch 批量全部在 URL 和参数层面完成不仅逻辑更清晰性能和可控性也完全不一样。1.2 REST API 在批量场景里的不可替代性要我说REST API 在 Power Automate 里的真正价值不在于它能做连接器做不到的事而在于它能用更少的步骤做连接器能做但很费劲的事。举一个最常见的场景每天早上八点把所有“状态 待处理”的审批项汇总出来经过某个简单的判定后批量更新为“处理中”。用内置连接器写出来的流程大概是获取列表项筛选状态等于待处理套循环逐个“更新列表项”每次更新前还得先取一遍当前项的数据避免把其他字段覆盖掉最后再按需发送通知。三步操作循环里还嵌套请求流程一长及时性、出错率、调试成本全上来了。用 REST API 写就不一样一个 HTTP 请求通过$filter把目标数据一次性拉回来在表达式层面对 JSON 响应做解析和判断再利用另一个 HTTP 请求或者 $batch 批量更新。核心思路就是减少“人和数据之间的来回”。把筛选逻辑交给 OData 查询把数据结构化交给 JSON 解析把批量写入交给批量接口。三层分开每一层都干净出错也知道去哪找。2. 组装一个能跑的 HTTP 请求URL、Headers、OData 参数2.1 URI 怎么拼Power Automate 里的“HTTP”操作发 SharePoint REST API 请求最关键的就是拼 URL。很多人第一次写就栽在路径上多一个空格、少一个_api都会收到 404 或者 400。一个标准的读取列表项请求长这样GET https://你的域名.sharepoint.com/sites/你的网站/_api/web/lists/getbytitle(列表名称)/items?$filterStatus eq Pending$selectId,Title,Status域名和网站路径在浏览器地址栏就能看到。列表名称这个位置推荐写列表的英文/内部名称千万不要写带空格的显示名称否则 URL 转义会让你怀疑人生。如果是中文列表名最好先到列表设置里确认“名称”字段的值再用getbytitle(中文名称)Power Automate 会自动做编码但保险起见内部名称是首选。有人会问为什么不用_api/lists/getbytitle而要用_api/web/lists/getbytitle两者都能用但web的作用是明确指定当前网站上下文在多级网站结构里能避免“找不到目标列表”的问题。我个人的习惯是永远带web。2.2 OData 查询参数才是批量处理的核心REST API 的强大很大程度来自 OData 查询参数。下面这张表是我在项目里反复使用的参数组合参数作用示例$filter筛选框定目标数据$filterStatus eq Pending$select只取需要的字段瘦身响应$selectId,Title,Status,Manager/EMail$orderby排序让数据有顺序$orderbyCreated desc$top只取前 N 条防止一次拉太多$top100$expand展开查炫字段或人员字段的子属性$expandManager$skip跳过前 N 条配合分页$skip100这里面最容易被忽略、也最容易出问题的就是$expand。当你的列表里有人物类字段、查炫字段时REST API 默认返回的是一个对象而不是一个字符串。比如负责人字段你直接$select负责人返回的往往长得像{ 负责人Id: 12, 负责人: { Id: 12, Title: 张三, EMail: zhangsanexample.com } }如果你只想要负责人的邮箱就得用$select负责人/EMail加上$expand负责人否则取不到内部属性。这一步搞不明白后面所有 JSON 解析都会跟着错。2.3 用 $batch 把几十个请求压缩成一次真正的批量更新靠循环一个个发 HTTP 请求效率太低了。SharePoint REST API 提供$batch端点允许你在一个请求里携带多个操作。POST https://你的域名.sharepoint.com/sites/你的网站/_api/$batch请求体比较特殊是multipart/mixed格式Power Automate 里写起来略繁琐但实用性极高。举例你要批量把 10 个 ID 的列表项状态改成“已完成”可以用下面的请求体模板--batch_abc123 Content-Type: application/http Content-Transfer-Encoding: binary MERGE https://你的域名.sharepoint.com/sites/你的网站/_api/web/lists/getbytitle(任务列表)/items(1) HTTP/1.1 Content-Type: application/json;odataverbose If-Match: * {Status: 已完成} --batch_abc123 Content-Type: application/http Content-Transfer-Encoding: binary MERGE https://你的域名.sharepoint.com/sites/你的网站/_api/web/lists/getbytitle(任务列表)/items(2) HTTP/1.1 Content-Type: application/json;odataverbose If-Match: * {Status: 已完成} --batch_abc123--每块都以--边界开头最后以--边界--结尾。边界字符串随便起但必须在整段里保持一致。实际项目里我会先在 JSON 解析环节把要更新的 ID 和状态整理成一个数组然后用表达式拼接出上面的批量体再发给$batch端点。这样的操作从“循环 50 次调用连接器”降为“一个请求 50 块逻辑”在速度和稳定性上是质的区别。2.4 认证方式选择与安全提示Power Automate 的“HTTP”操作要做 SharePoint 请求认证方式我建议直接选“Microsoft Entra ID 集成验证”或者“Azure AD 集成验证”具体名称根据租户版本略有不同。这一步会调用流程运行时身份通常就是你拥有该站点权限的账号。有个安全细节值得注意不要在 URL 或者自定义 Headers 里写任何人可见的明文 Token。即使你拿着别人的请求示例也要把域名、列表名这种信息换成自己的。另外如果是生产环境流程建议给 HTTP 操作配置“重试策略”例如指数退避重试 3 次因为 SharePoint REST API 在高并发下偶尔会返回 429 或 503重试几次就过去了。3. JSON 响应拆解从“一团文本”到“一个可循环的结构”3.1 先把响应结构画出来请求发出去了返回的数据长什么样决定了后续所有逻辑怎么写。SharePoint REST API 默认返回的 JSON 结构通常是这样的{ d: { results: [ { __metadata: { id: ... }, Id: 1, Title: 第一条, Status: Pending, Created: 2025-01-01T08:00:00Z }, { __metadata: { id: ... }, Id: 2, Title: 第二条, Status: Completed, Created: 2025-01-02T09:30:00Z } ] } }记住两个关键点外层永远是d列表数据永远在d.results数组里。只要你能在 Power Automate 的表达式里拿到body(获取数据)[d][results]就等于拿到了所有列表项。很多新手会犯一个错误把原始响应全部塞到变量里再慢慢找。其实完全没必要直接用表达式引用即可。比如我想把results数组存进一个变量初始化的表达式就是body(HTTP_获取数据)?[d][results]注意我用了?安全引用运算符这样即使返回结果里没有d也不会立刻让流程崩掉最多给个null。3.2 用 Parse JSON 建立 schema把动态字段变成固定通道光有原始 JSON 还不够Power Automate 里的“解析 JSON”操作才是把数据结构化的核心工具。做法很简单在“解析 JSON”操作的“内容”里填上你的响应 Body然后点击“根据示例生成架构”把刚才那段返回结果粘贴进去就会自动生成 schema。生成 schema 之后它会在后续表达式的自动补全里给你推荐字段。比如你想拿Status字段表达式会变成body(解析JSON)?[Status]注意如果你拿到的是整个results数组那么 Parse JSON 的 schema 应该定义成数组类型。这样后续在“Apply to each”里item()对象自然就拥有Id、Title、Status这些子属性写起来特别顺手。这里有个容易踩的坑生成 schema 时如果粘贴的示例太短比如只粘贴了一条数据而实际数据里有可选的查炫字段Power Automate 并不会自动把字段标记为可空。等流程跑起来某一条数据正好没有那个字段就会触发类型转换错误或者直接返回 null。所以生成架构后建议手工检查一下字段类型把可能为空的字段改成可空。如果字段没有出现在 schema 里不管你在 JSON 里能不能看到它表达式里都取不到。3.3 循环中如何使用索引和属性拿到数组之后“Apply to each”是批量处理的主战场。循环里item()代表当前这一条记录你可以直接访问它的属性。{item()?[Id]}如果你需要知道当前是第几条可以用以下表达式range(0, length(body(解析JSON)))[iterationIndexes(Apply_to_each)]不常用但在生成 JSON 数组、拼接批量请求时特别有用。这里有一个大家很容易忽略的操作循环里再次调用 HTTP 请求。如果循环体内要发请求请务必注意颜面值也就是并发度。Power Automate 的“Apply to each”默认并发度是 1也就是一条一条跑慢但稳定。如果你希望批量操作快一点可以在循环设置里打开并发控制调高到 10 或 20。但 SharePoint REST API 并不欢迎无限并发建议控制在 10 到 15 之间太高的并发度会触发限流。3.4 JSON 数组、嵌套字段和特殊列的处理JSON 数组是我们在批量处理里见得最多的东西。当列表项里的人字段返回多个值例如多选人员列展开后可能是一个 JSON 数组{ 负责人: { results: [ { EMail: aexample.com, Title: 张三 }, { EMail: bexample.com, Title: 李四 } ] } }这种时候最简单的做法是利用 Power Automate 的“Select”操作把数组映射成一个字符串数组再根据需要 join 成字符串。join(body(Select), ;)还有一种特殊列是 Choice 字段里的多选值它返回的通常是一串以分号分隔的字符串。如果你需要把它转成真正的 JSON 数组可以用split(item()?[标签], ;#)这里的;分隔符是 SharePoint 内部格式的一部分经常长成#标签1;#标签2;#的样子所以要拆成上下两个分隔符的中间部分处理时可以先replace把;#统一替代成,再拆数组。3.5 如何查看解析后的中间值做流程调试的时候最怕看到的就是“变量在手但不知道里面到底装了什么”。我特别推荐在关键步骤之后加一个“Compose”操作把中间结果输出出来然后在运行历史里展开 Compose 的输出查看数据。举个场景我在 Expressions 里写了body(解析JSON)?[results]不确定这个表达式拿到的到底是一个数组还是一个对象那就专门用一个 Compose 来装它运行之后展开看是[...]还是{...}一目了然。这一点和工具使用习惯有关。Power Automate 并没有独立的“JSON 查看器”面板但它自带的运行历史输出面板就是最直接的查看工具。你完全可以把任意阶段的 JSON 输出复制到外部 JSON 格式化工具里重新缩进、折叠、搜索字段。格式化的意义不只是好看更重要的是能帮你快速确认某字段是否存在、类型是什么、是字符串还是对象。4. 高频 JSON 错误现场反序列化失败、缺失字段、空值与类型4.1 failed to deserialize the json body into the target type 是怎么发生的这个报错大概是我收到私信最多的问题原话经常是failed to deserialize the json body into the target type: input: missing field xxx这个错误的字面意思是系统尝试把一个 JSON 文本转换成目标对象时发现缺少了目标里要求的一个字段。在 Power Automate 里它最常出现在两个地方Parse JSON 操作的 schema 里定义了某个必填字段但运行时回来的 JSON 里没有这个字段。你创建或更新 SharePoint 项时请求体里期望的是一个特定结构但实际传过去的 JSON 没有包含必要的属性。我遇到过最典型的案子是项目里有个列表字段在原有基础上改过一次名。显示名称从“审批人”改成了“审批负责人”但 REST API 返回的InternalName并没有变还是老的。结果 Parse JSON 的 schema 里我写的是新显示名对应的内部名而响应里根本没有这个字段流程一跑就报 missing field。排查这个问题的思路很简单不要瞎猜先把返回的 Body 用一个 Compose 整体打出来把 Body 内容复制出来格式化逐个字段对照 schema检查字段名大小写JSON 区分大小写id和ID完全不同检查是否为嵌套字段比如Manager/EMail这种如果没$expand即使字段存在也取不到把 schema 里非必填字段都改成可空做到“有这个字段就用没有就给默认值”。4.2 missing field 的兜底方法我在编写表达式时会优先使用安全引用和默认值让流程在缺字段时先活下来再考虑要不要报错。举个例子某个响应字段叫Remark但部分列表项没有填备注直接item()?[Remark]会得到null。如果你想把它转换为一个字符串并参与后续拼接最好写成if(empty(item()?[Remark]), , item()?[Remark])如果你连字段是否存在都不能确定可以先contains(item(), Remark)判断一下if(contains(item(), Remark), item()?[Remark], )这样做即便字段真的缺失也不会再触发反序列化相关报错而是给一个空字符串兜底。流程的健壮性能瞬间提升不少。4.3 日期、数字、引号形式的类型坑JSON 类型出错是批量处理另一个高频雷区。SharePoint 里的日期时间字段在 REST API 返回中通常是 ISO 8601 字符串比如2025-06-01T08:00:00Z。Power Automate 表达式函数utcNow()、formatDateTime()、addDays()都可以直接处理它但直接拿来比较时要注意时区问题。例如你想筛出“最近 7 天创建”的列表项OData 请求里应该这样写$filterCreated ge datetime2025-01-01T00:00:00Z日期时间要用datetime...裹起来而不是普通字符串引号这是很多人忽略的点。数字类型也有坑。列表里有个数字字段叫数量REST API 返回的是5而不是5。但如果你在 OData 更新时传了数量: 5这种带引号的字符串部分版本会直接拒绝或者维度不一致。写请求体的时候请务必保证类型一致该用数字就用数字该用布尔就用布尔。另外SharePoint 的多选人员字段通常不是一个数组而是一个对象加results。如果你拿着这种结构去更新很容易因为字段结构不匹配而报错。我处理这类字段的办法是先用表达式把用户邮箱列表拼装成 JSON 数组再构造 OData 更新数据。例如把一个分号分隔的邮箱字符串转成 JSON 数组json(concat([, join(split(variables(邮箱字符串), ;), ,), ]))每次转完以后务必用 Compose 输出检查生成的数组是否合法。4.4 一套完整的排错思考流程我遇到 JSON 相关报错的时候从来不会直接开改流程。先按下面这个顺序来查看失败步骤的“输入”和“输出”确认实际数据是什么把输出 Body 复制到 JSON 格式化工具中重新缩进并检查字段树对照自己的 Parse JSON schema逐个字段看是否存在、类型是否一致如果问题出在请求构造把发送出去的那段 JSON 原样拿回来放到格式化工具里校验语法用多个 get 来逐步缩小问题半径优先定位是数据问题还是结构问题。这个流程看起来慢但其实是最高效的。因为 JSON 报错往往不是最后一环出了问题而是前面某一步已经把数据结构破坏掉了。5. 完整用例用 REST API 批量更新多个列表的“待处理状态”5.1 场景设定与流程设计假设你要在每天下班前扫描两个不同的 SharePoint 列表“任务清单”和“审批记录”把所有“状态 待处理”且“截止日期小于今天”的项找出来批量更新为“已超时”。这个场景用内置连接器至少要做两套“获取列表项 遍历更新”的逻辑。但用 REST API我可以设计成一个 HTTP 请求查“任务清单”一个 HTTP 请求查“审批记录”分别解析 JSON把需要更新的 ID 和状态整理出来合并数组后调$batch批量更新。流程的核心优势是所有筛选都在请求层面完成不把脏数据和无关数据推进流程里。5.2 配置实操和关键表达式注释先写第一个 HTTP 请求GET https://你的域名.sharepoint.com/sites/你的网站/_api/web/lists/getbytitle(任务清单)/items?$filterStatus eq 待处理 and DueDate lt datetimeutcNow(concat(yyyy-MM-dd,T00:00:00Z))$selectId,Status第二段列表“审批记录”的请求结构完全一样只是列表名不同。接下来初始化一个数组变量用来存最终要更新的 ID 集合。为了避免重复我通常这样处理union(body(解析任务清单)?[results], body(解析审批记录)?[results])其实union是靠对象引用去重的对数值 ID 不敏感所以更稳妥的办法是用intersection不行而是直接用两个数组各自取出Idbody(解析任务清单)?[results]然后在“追加到数组变量”操作里把每条数据的 Id 和 Status 组装成一个对象addProperty(item(), Status, 已超时)循环结束后变量 ID 集合里就有了一组要更新的记录。最后用$batch请求把所有 “MERGE” 逐个发出去。你的批量体拼接表达式可以这样写具体拼接方式视版本而定常见思路是创建一个字符串变量并持续concat追加concat(--batch_1 Content-Type: application/http Content-Transfer-Encoding: binary MERGE https://你的域名.sharepoint.com/sites/你的网站/_api/web/lists/getbytitle(任务清单)/items(, item()?[Id], ) HTTP/1.1 Content-Type: application/json;odataverbose If-Match: * {Status: 已超时} )再把这个字符串作为 POST 请求的 Body 发给_api/$batch在 Header 里设置Content-Type: multipart/mixed; boundarybatch_1。这里有个细节$batch批量体第一行不能有任何多余空格否则服务端解析 multipart 会失败。很多同学照着案例抄明明逻辑没问题却一直 400排查到最后发现是批量体开头多了一个换行或空格。5.3 运行结果验证跑完流程后最直接的验证方式是回到 SharePoint 列表页面刷新筛选条件看“待处理”的项是不是变少了“已超时”的项是不是出现了。如果项目比较多也可以直接用 REST API 再发一次$filterStatus eq 已超时的请求统计条数与预期匹配。另外一个建议在流程里预留一个“是否真实执行”的开关变量。测试阶段设为false只输出将要更新的 ID 列表确认无误后再切为true真正发起批量更新。这个习惯帮我避免了很多“手滑把全表清空”的惨案。6. 几个写在最后的实操心得6.1 测试时别用大列表先用小型副本我见过很多人拿着生产列表直接测流程几百上千条数据在那里跑一旦表达式写错一半数据变成脏数据恢复成本极高。我的建议是先复制一个只有十几条数据的小列表把所有逻辑跑通再用“测试连接器”模式模拟数据量大的情况。尤其是涉及更新操作时小列表调试既快又安全。6.2 关于 JSON 格式化工具的使用习惯平时收到 JSON 响应以后我不会直接塞进表达式而是先丢进格式化工具里看一眼结构。格式化不只是改改缩进关键是能帮你快速定位嵌套层级和字段名。很多“为什么取不到值”的问题本质上就是因为没看清结构把对象当数组或把字符串当对象。我的习惯是外部格式化之后先在 Compose 里输出一次再决定用.还是?[]去访问。这一步看着多余其实能帮你省下大量排查时间。6.3 遇到批量更新优先考虑 $batch最后再强调一次批量更新永远优先考虑$batch不要用循环套 HTTP 请求。循环套请求不是不行但当数据量到达几百条、几千条时运行时长和 API 调用量都会成为问题。$batch虽然请求体拼接麻烦一点但它带来的稳定性和性能提升足以覆盖那点学习成本。你只要把批量体的模板固定下来后续复制修改列表名和字段名即可是一次性投入、长期受益的事情。