Graph API v1 Planner/Task端点PATCH数据更新时机存疑及任务更新异常

我来帮你拆解遇到的几个问题，一步步解决任务状态更新的困惑：

1. 为什么加percentageCompleted会报错？ #

首先要纠正一个关键拼写错误：Graph API里的完成百分比字段是percentComplete，不是percentageCompleted！这就是你添加该字段后报错的核心原因。

正确的PATCH请求写法是这样的：

• 把任务设为待办：将percentComplete设为0
• 把任务设为已完成：将percentComplete设为100，还可以顺便设置completedDateTime（可选，但能让任务状态显示更清晰）

举个实际请求的例子（假设你的任务ID是task-abc123）：

PATCH https://graph.microsoft.com/v1.0/planner/tasks/task-abc123
Content-Type: application/json

{
  "percentComplete": 0
}

另外，请求返回204 No Content是正常现象，Graph API的PATCH操作成功后通常不会返回内容，只要状态码是204，就说明任务已经被更新了。

2. AJAX调用记录请求时的异常怎么排查？ #

AJAX出错通常逃不开这几个原因，你可以逐一检查：

• 请求头没设置对：必须带上Content-Type: application/json，不然API没法解析你的请求体
• 权限不够：确认你的应用已经拿到了Group.ReadWrite.All或者Tasks.ReadWrite权限（Planner任务大多属于群组，所以Group相关权限更常用）
• 跨域问题：如果是前端页面发起的AJAX，得在Azure AD里给你的应用配置好正确的CORS策略
• 没做错误捕获：一定要在AJAX里加错误回调，看看具体的错误响应——Graph API会返回很详细的错误信息，比如字段名写错的提示

给你个jQuery AJAX的示例代码，包含成功和错误处理：

$.ajax({
  url: "https://graph.microsoft.com/v1.0/planner/tasks/task-abc123",
  method: "PATCH",
  headers: {
    "Authorization": "Bearer " + yourAccessToken,
    "Content-Type": "application/json"
  },
  data: JSON.stringify({
    "percentComplete": 0
  }),
  success: function() {
    // 注意：成功时response是空的，因为204无内容
    console.log("任务状态更新成功！");
    // 想确认更新结果的话，立刻发个GET请求查任务
    fetchTaskStatus("task-abc123");
  },
  error: function(xhr) {
    const errorInfo = JSON.parse(xhr.responseText);
    console.error("更新失败：", errorInfo.error.message);
  }
});

function fetchTaskStatus(taskId) {
  $.ajax({
    url: `https://graph.microsoft.com/v1.0/planner/tasks/${taskId}`,
    method: "GET",
    headers: { "Authorization": "Bearer " + yourAccessToken },
    success: function(task) {
      console.log("当前任务完成百分比：", task.percentComplete);
    }
  });
}

3. 怎么确定PATCH更新什么时候完成？ #

Graph API的PATCH操作是即时生效的，几乎没有延迟（最多毫秒级的分布式一致性同步时间）。如果你要确保更新完成，可以在收到204响应后立刻发起GET请求查询任务状态，就像上面示例里的fetchTaskStatus函数那样。

如果用的是Graph SDK（比如JavaScript或.NET的SDK），有些SDK支持在PATCH调用后直接返回更新后的任务数据，不用额外发GET请求，你可以看看SDK文档里有没有相关参数。

额外提醒 #

• 任务的bucketId和planId不能通过PATCH修改，要移动任务得用专门的移动端点
• 确保你的access token没过期，权限足够
• 如果要批量更新多个任务，用Graph API的批量请求能减少网络请求次数

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