使用 Planner REST API

项目
03/26/2023

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

在开始使用 Planner API 之前，了解主对象相互之间以及与 Microsoft 365 组之间的关系将会有所帮助。

Plan 容器

在 Microsoft Planner 中，计划始终被包含在另一个资源中。包含该计划的资源决定了该计划和其中所有任务的授权规则，以及该计划的生命周期。例如，对于 Microsoft 365 组包含的计划，组成员可以在计划中创建、编辑、解析和删除任务，还可以更改某些计划级属性（例如计划名称或标签名称）。另外，删除组时，会自动删除组中的所有计划，如果恢复组，则会自动恢复所有计划。

最常见的容器类型是 Microsoft 365 组。

容器类型：Microsoft 365 组

计划通常包含在 Planner API 中的 Microsoft 365 组中。若要获取组所有的计划，请发出以下 HTTP 请求。

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

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

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

计划

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

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

任务

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

任务和计划详细信息

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

可视化

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

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

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

所有排序均由 Planner 顺序提示中介绍的原则指定。

Planner 资源版本控制

Planner 使用 etag 对所有资源进行版本控制。这些 etag 在每个资源上返回 @odata.etag 属性。 PATCH 和 DELETE 请求要求使用 If-Match 标头指定客户端已知的最后一个 etag。如果目标更改与相同资源上的 Planner 服务接受的较新更改不冲突，则 Planner 允许对资源的旧版本进行更改。客户端可以通过计算顺序字符串比较中的较大 etag 值，确定在相同的资源中，哪个 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 状态代码。如果出现这种情况，错误资源类型上的代码属性将标识请求超出的限制类型。有关限制的详细信息，请参阅Planner限制。以下是限制类型的可能值。

值	说明
MaximumProjectsOwnedByUser	已超出组包含的最大 Plan 数限制。此限制适用于基于 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 属性包含的值过多。
MaximumPlannerPlans	该组已包含用户拥有的最大计划数，当前为 200 个。有关限制的详细信息，请参阅Planner限制。

412 前提条件不满足

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