使用 Planner REST API

  • 项目

重要

Microsoft Graph /beta 版本下的 API 可能会发生更改。 不支持在生产应用程序中使用这些 API。 若要确定 API 是否在 v1.0 中可用，请使用 版本 选择器。

可以使用 Microsoft Graph 中的 Planner API 创建任务，并将其分配给 Microsoft 365 中某个群组的用户。

在开始使用 Planner API 之前，了解main对象彼此和 Microsoft 365 组之间的关系会很有帮助。

Plan 容器

在Microsoft Planner中，计划始终包含在另一个资源中。 包含的资源 plannerPlanContainer 确定计划的授权规则及其中的所有任务，以及计划的生命周期。 可以在以下类型之一的容器中创建计划：driveItem、Microsoft 365 组、Planner项目、名单或用户。

最常见的容器类型是组。

容器类型：Microsoft 365 组

计划通常包含在 Planner API 中的组中。

组成员可以在计划中创建、编辑、解析和删除任务。 组成员还可以更改某些计划级属性，例如计划名称或标签名称。 此外，删除组后，将自动删除组中的所有计划。 相反，如果还原组，则会自动还原所有计划。

若要获取组所有的计划，请发出以下 HTTP 请求。

GET /groups/{group-id}/planner/plans

创建新计划时，请在计划对象上设置容器属性，使组成为其容器。 计划必须包含在支持的资源中。

注意：正在创建计划的用户必须是将包含计划的组的成员。 使用“创建组”创建新组时，系统不会将你添加为组成员。 创建组后，使用“组帖子成员”将自己添加为成员。

容器类型：用户

用户容器类型支持个人计划，其中用户是唯一跟踪其单个任务的用户。 这为用户提供了共享或协作处理其个人计划的灵活性。 删除用户时，会自动删除为单个用户创建的计划。

若要在用户的容器中创建新计划，请在类型为 user的计划对象上设置容器属性。

{
    "container": {
        "id": "00000000-0000-0000-0000-000000000000",
        "type": "user"
    }
}

或者，可以指定用户的 URL。

{
    "container": {
        "url": "https://graph.microsoft.com/beta/users/me"
    }
}

通过将计划从用户容器 移动到 组容器，将计划的类型从 usergroup更改为 ，用户可以将其个人计划升级到基于组的计划。

计划

计划是任务的容器。 若要在计划中创建任务，请在创建任务时将任务对象上的 planId 属性设置为计划的 ID。 如果没有计划，当前无法创建任务。 若要检索计划的任务，请发出以下 HTTP 请求。

GET /planner/plans/{plan-id}/tasks

任务

通过在任务对象的 assignments 属性中添加分配，可以将每个任务分配给用户。 要分配任务的用户的 ID 是 工作分配上的打开属性的名称，并且必须指定分配上的 orderHint 属性。

任务和计划详细信息

Planner资源排列为基本对象和详细信息对象。 基本对象提供对适用于列表视图的资源公共属性的访问权限，而详细信息对象提供对适合向下钻取视图的资源的大型属性的访问权限。

可视化

除任务和计划数据外，Planner API 还能提供资源，以便跨客户端创建数据的常见可视化。 有几种类型的可视化数据可用于如下表中所列的任务。

任务如下所示 使用以下信息对任务进行排序
简单列表（计划中的任务） 任务的 orderHint 属性
简单列表（分配给用户的任务） 任务的 assigneePriority 属性
包含受理人列的板块视图（分配给任务板块） assignedToTaskBoardTaskFormat 对象
包含针对完成情况的任务进度列的板块视图（进度任务板块） progressTaskBoardTaskFormat 对象
包含任务自定义列的板块视图（存储桶任务板块） bucketTaskBoardTaskFormat 对象

存储桶任务板中的自定义列由 存储桶 对象表示，其顺序由对象的 orderHint 属性表示。

排序原则在Planner顺序提示中介绍。

使用 delta 查询跟踪更改

Planner 的 delta 查询功能支持查询用户订阅的对象。

用户订阅了以下对象。

Planner 资源类型 已订阅的实例
任务
  • 由用户创建
  • 已分配给用户
  • 属于用户拥有的计划
  • 包含在通过计划的 SharedWith 集合与用户共享的计划中
计划
  • 通过计划的 SharedWith 集合与用户共享
存储桶
  • 包含在通过计划的 SharedWith 集合与用户共享的计划中

填充 delta 查询的对象缓存

如果要使用 Planner delta 查询 API，请保留用户有兴趣查看的对象的本地缓存，以便应用 delta 响应源中的更改。

Planner增量查询当前可以返回的增量有效负载对象属于以下类型：

使用资源中的相应 GET 方法获取要填充到本地缓存的对象初始状态。

区分对象创建和对象修改

在某些情况下，调用方可能希望区分 Planner 的 delta 查询源中的对象创建和对象修改。

可使用以下准则推断对象创建：

  • createdBy 属性显示在新创建的对象上。
  • 新创建的 plannerTask 对象后跟其相应的 plannerTaskDetails 对象。
  • 新创建的 plannerPlan 对象后跟其对应的 plannerPlanDetails 对象。

用法

调用方期望有一个包含订阅对象的缓存。 有关如何填充订阅对象的本地缓存的详细信息，请参阅填充 delta 查询的对象缓存。

Planner 的 delta 查询调用流如下所示：

  1. 调用方启动 delta 同步查询，以便获取 nextLink 和空的更改集合。
  2. 调用方必须使用用户订阅的对象填充 delta 查询的对象缓存，从而更新其缓存。
  3. 调用方遵循初始 delta 同步查询中提供的 nextLink，以便获得自上一步以来所做的任何更改的新 deltaLink。
  4. 调用方将返回的 delta 响应中的更改应用于其缓存中的对象。
  5. 调用方遵循新的 deltaLink 以获取下一个 deltaLink，以及自生成当前 deltaLink 以来所做的更改。
  6. 调用方应用更改（如果有）并等待一小段时间，然后重新执行上一步和此步骤。

Planner 资源版本控制

Planner 使用 etag 对所有资源进行版本控制。 这些 etag 在每个资源上返回 @odata.etag 属性。 PATCH 和 DELETE 请求要求使用 If-Match 标头指定客户端已知的最后一个 etag。 如果预期的更改与同一资源上Planner服务接受的新更改不冲突，Planner允许对旧版资源进行更改。 客户端可以通过计算顺序字符串比较中的较大 etag 值，确定在相同的资源中，哪个 etag 较新。 每个资源都有唯一的 etag。 无法比较不同资源（包括具有包含关系的资源）的 Etag 值。 客户端应用应处理与版本控制相关的 错误代码409 ，并 412 读取项目的最新版本并解决冲突更改。

常见的 Planner 错误条件

除了适用于 Microsoft Graph 的常规错误外，某些错误条件特定于 Planner API。

400 错误的请求

在某些常见方案中，POST 和 PATCH 请求可能会返回 400 状态代码。 以下是一些常见原因：

  • Open Type 属性指定了错误的类型或未指定类型，或者不包含任何属性。 例如，具有复杂值的 plannerAssignments 属性需要使用值 microsoft.graph.plannerAssignment声明 @odata.type 属性。
  • 顺序提示值的格式 不正确。 例如，订单提示值直接设置为返回到客户端的值。
  • 数据在逻辑上不一致。 例如，任务的开始日期晚于任务的截止日期。

403 已禁止

除了常规错误之外，当超出服务定义的限制时，Planner API 还会返回403状态代码。 如果是这样，则错误资源类型的 code 属性指示请求超出的限制类型。 以下是限制类型的可能值。

值 说明
MaximumProjectsOwnedByUser 超出了组限制包含的最大计划数。 plannerPlan 资源的容器属性确定此限制。
MaximumProjectsSharedWithUser 已超出与用户限制共享的最大计划数。 plannerPlanDetails 资源上的 sharedWith 属性确定此限制。
MaximumTasksCreatedByUser 超出了用户限制创建的最大任务数。 plannerTask 资源上的 createdBy 属性确定此限制。
MaximumTasksAssignedToUser 已超出分配给用户限制的最大任务数。 plannerTask 资源上的 assignments 属性确定此限制。
MaximumTasksInProject 超出计划限制中的最大任务数。 plannerTask 资源上的 planId 属性确定此限制。
MaximumActiveTasksInProject 超出计划限制中未完成的最大任务数。 plannerTask 资源上的 planId 和 percentComplete 属性决定了此限制。
MaximumBucketsInProject 超出计划限制中的最大存储桶数。 plannerBucket 资源上的 planId 属性确定此限制。
MaximumUsersSharedWithProject plannerPlanDetails 资源上的 sharedWith 属性包含的值过多。
MaximumReferencesOnTask plannerTaskDetails 资源上的 references 属性包含的值过多。
MaximumChecklistItemsOnTask plannerTaskDetails 资源上的 checklist 属性包含的值过多。
MaximumAssigneesInTasks plannerTask 资源上的 assignments 属性包含的值过多。
MaximumFavoritePlansForUser plannerUser 资源上的 favoritePlanReferences 属性包含的值太多。
MaximumRecentPlansForUser plannerUser 资源上的 recentPlanReferences 属性包含的值太多。
MaximumContextsOnPlan plannerPlan 资源上的 contexts 属性包含的值过多。

412 前提条件不满足

所有 Planner API POST、PATCH 和 DELETE 请求都需要使用受请求约束的资源的最后一个已知 etag 值指定 If-Match 标头。 如果请求中指定的 etag 值不再匹配服务中资源的版本，也会返回 412 状态代码。 在这种情况下，客户端应该再次读取资源并获取新的 etag。