使用 Planner REST APIUse the Planner REST API

你可以使用 Microsoft Graph 中的 Planner API 创建任务并将其分配给 Office 365 中某个组的用户。You can use the Planner API in Microsoft Graph to create tasks and assign them to users in a group in Office 365.

开始使用 Planner API 之前,需要了解主对象互相之间以及与 Office 365 组的关系。Before you get started with Planner API, you will want to understand how the main objects relate to each other as well as to Office 365 groups.

Office 365 组Office 365 Groups

Office 365 组是 Planner API 中的计划的所有者。Office 365 groups are the owners of the plans in the Planner API. 若要获取组所有的计划,请发出以下 HTTP 请求。To get the plans owned by a group, make the following HTTP request.

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

创建新计划时,通过在计划对象上设置 owner 属性,可使组成为其所有者。When creating a new plan, make a group its owner by setting the owner property on a plan object. 计划必须归组所有。Plans must be owned by groups.

注意: 正在创建计划的用户必须是拥有该计划的组的成员。Note: The user who is creating the plan must be a member of the group that will own the plan. 使用“创建组”创建新组时,系统不会将你添加为组成员。When you create a new group by using Create group, you are not added to the group as a member. 创建组后,使用“组帖子成员”将自己添加为成员。After the group is created, add yourself as a member by using group post members.

计划Plans

计划任务的容器。Plans are the containers of tasks. 若要在计划中创建一个任务,在创建任务时,将任务对象中的 planId 属性设置为计划的 ID。To create a task in a plan, set the planId property on the task object to the ID of the plan while creating the task. 目前无法在没有计划的情况下创建任务。Tasks currently cannot be created without plans. 若要检索计划的任务,请发出以下 HTTP 请求。To retrieve the tasks in a plan, make the following HTTP request.

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

任务Tasks

可以通过在任务对象的 assignments 属性中添加分配将每个任务分配给一位用户。要分配任务的用户 ID 是 assignments 上的开放属性的名称,且必须指定分配上的 orderHint 属性。Each task can be assigned to a user by adding an assignment in the assignments property on the task object. The ID of the user to assign the task is the name of the open property on assignments, and the orderHint property on the assignment must be specified.

任务和计划详细信息Task and plan details

Planner 资源会排列到基本对象和详细对象中。基本对象提供对适合列表视图的资源的通用属性的访问权限,而详细对象提供对适合深化视图的资源的大型属性的访问权限。Planner resources are arranged into basic objects and detail objects. Basic objects provide access to common properties of the resources, suitable for list views, while the detail objects provide access to large properties of the resources suitable for drill down views.

可视化Visualization

除任务和计划数据外,Planner API 还能提供资源,以便跨客户端创建数据的常见可视化。Aside from task and plan data, the Planner API also provides resources for creating a common visualization of data across clients. 有几种类型的可视化数据可用于如下表中所列的任务。Several types of visualization data are available for tasks, as listed in the following table.

任务如下所示Tasks are shown as 使用以下信息对任务进行排序Tasks are ordered with information from
简单列表(计划中的任务)Flat list (tasks in a plan) 任务的 orderHint 属性orderHint property on tasks
简单列表(分配给用户的任务)Flat list (tasks assigned to a user) 任务的 assigneePriority 属性assigneePriority property on tasks
包含受理人列的板块视图(分配给任务板块)Board view with columns for assignees (assigned to task board) assignedToTaskBoardTaskFormat 对象assignedToTaskBoardTaskFormat object
包含针对完成情况的任务进度列的板块视图(进度任务板块)Board view with columns for progress of the task towards completion (progress task board) progressTaskBoardTaskFormat 对象progressTaskBoardTaskFormat object
包含任务自定义列的板块视图(存储桶任务板块)Board view with custom columns of tasks (bucket task board): bucketTaskBoardTaskFormat 对象bucketTaskBoardTaskFormat object

存储桶任务板块中的自定义栏由 bucket 对象表示,其顺序由对象的 orderHint 属性表示。The custom columns in the bucket task board are represented by bucket objects, and their order by orderHint property on the object.

所有排序均由 Planner 顺序提示中介绍的原则指定。All the ordering is controlled by the principles described in Planner order hints.

Planner 资源版本控制Planner resource versioning

Planner 使用 etag 对所有资源进行版本控制。Planner versions all resources using etags. 这些 etag 在每个资源上返回 @odata.etag 属性。These etags are returned with @odata.etag property on each resource. PATCHDELETE 请求要求使用 If-Match 标头指定客户端已知的最后一个 etagPATCH and DELETE requests require the last etag known by the client to be specified with a If-Match header. 如果目标更改与相同资源上的 Planner 服务接受的较新更改不冲突,则 Planner 允许对资源的旧版本进行更改。Planner allows changes to older versions of resources, if the intended change does not conflict with newer changes accepted by the Planner service on the same resource. 客户端可以通过计算顺序字符串比较中的较大 etag 值,确定在相同的资源中,哪个 etag 较新。The clients can identify which etag for the same resource is newer by calculating which etag value is greater in ordinal string comparison. 每个资源都有唯一的 etagEach resource has a unique etag. 不同资源的 etag 值(包括具有包含关系的 etag 值)无法比较。Etag values for different resources, including those with containment relationships, cannot be compared. 按预期,客户端应用程序需要通过读取项的最新版本处理与错误代码 409412 相关的版本控制,并解决冲突的更改。The client apps are expected to handle versioning related error codes 409 and 412 by reading the latest version of the item and resolving the conflicting changes.

常见的 Planner 错误条件Common Planner error conditions

除了适用于 Microsoft Graph 的常规错误外,某些错误条件特定于 Planner API。In addition to general errors that apply to Microsoft Graph, some error conditions are specific to the Planner API.

400 错误的请求400 Bad request

在某些常见方案中,POSTPATCH 请求可能会返回 400 状态代码。In some common scenarios, POST and PATCH requests can return a 400 status code. 以下是一些常见原因:The following are some of the common causes:

  • 开放类型属性的类型不正确,或该类型未指定,或它们不包含任何属性。例如,包含复杂值的 plannerAssignments 属性需要声明包含 值的 属性。Open Type properties are not of correct types, or the type isn't specified, or they do not contain any properties. For example, plannerAssignments properties with complex values need to declare @odata.type property with value microsoft.graph.plannerAssignment.
  • 顺序提示值不具有正确格式。例如,顺序提示值被直接设置为返回到客户端的值。Order hint values do not have the correct format. For example, an order hint value is being set directly to the value returned to the client.
  • 数据在逻辑上不一致。例如,任务的开始日期晚于任务的到期日期。The data is logically inconsistent. For example, start date of task is later than due date of the task.

403 已禁止403 Forbidden

除常规错误外,当超出服务定义的限制时,Planner API 也会返回 403 状态代码。In addition to the general errors, the Planner API also returns the 403 status code when a service-defined limit has been exceeded. 如果出现这种情况,错误资源类型上的 code 属性将标识请求超出的限制类型。If this is the case, the code property on the error resource type will indicate the type of the limit exceeded by the request. 以下是限制类型的可能值。The following are the possible values for the limit types.

Value 说明Description
MaximumProjectsOwnedByUserMaximumProjectsOwnedByUser 已超出组所有的最大 Plan 数限制。此限制基于 plannerPlan 资源上的 owner 属性。The maximum number of Plans owned by a group limit has been exceeded. This limit is based on the owner property on the plannerPlan resource.
MaximumProjectsSharedWithUserMaximumProjectsSharedWithUser 已超出与用户共享的最大 Plan 数限制。此限制基于 plannerPlanDetails 资源上的 sharedWith 属性。The maximum number of Plans shared with a user limit has been exceeded. This limit is based on the sharedWith property on the plannerPlanDetails resource.
MaximumTasksCreatedByUserMaximumTasksCreatedByUser 已超出用户创建的最大 Task 数限制。此限制基于 plannerTask 资源上的 createdBy 属性。The maximum number of Tasks created by a user limit has been exceeded. This limit is based on the createdBy property on the plannerTask resource.
MaximumTasksAssignedToUserMaximumTasksAssignedToUser 已超出分配给用户的最大 Task 数限制。此限制基于 plannerTask 资源上的 assignments 属性。The maximum number of Tasks assigned to a user limit has been exceeded. This limit is based on the assignments property on the plannerTask resource.
MaximumTasksInProjectMaximumTasksInProject 已超出 Plan 中的最大 Task 数限制。此限制基于 plannerTask 资源上的 planId 属性。The maximum number of Tasks in a Plan limit has been exceeded. This limit is based on the planId property on the plannerTask resource.
MaximumActiveTasksInProjectMaximumActiveTasksInProject 已超出 Plan 中未完成的最大 Task 数限制。此限制基于 plannerTask 资源上的 planIdpercentComplete 属性。The maximum number of Tasks that aren't completed in a Plan limit has been exceeded. This limit is based on the planId and percentComplete properties on the plannerTask resource.
MaximumBucketsInProjectMaximumBucketsInProject 已超出 Plan 中的最大 Bucket 数限制。此限制基于 plannerBucket 资源上的 planId 属性。The maximum number of Buckets in a Plan limit has been exceeded. This limit is based on the planId property on the plannerBucket resource.
MaximumUsersSharedWithProjectMaximumUsersSharedWithProject plannerPlanDetails 资源上的 sharedWith 属性包含的值过多。The sharedWith property on the plannerPlanDetails resource contains too many values.
MaximumReferencesOnTaskMaximumReferencesOnTask plannerTaskDetails 资源上的 references 属性包含的值过多。The references property on the plannerTaskDetails resource contains too many values.
MaximumChecklistItemsOnTaskMaximumChecklistItemsOnTask plannerTaskDetails 资源上的 checklist 属性包含的值过多。The checklist property on the plannerTaskDetails resource contains too many values.
MaximumAssigneesInTasksMaximumAssigneesInTasks plannerTask 资源上的 assignments 属性包含的值过多。The assignments property on the plannerTask resource contains too many values.
MaximumPlannerPlansMaximumPlannerPlans 组已包含一个计划。The group already contains a Plan. 目前,组只能包含一个计划。Currently, groups can only contain one Plan. 注意: 某些 Microsoft 应用程序可能超出此限制。Note: Some Microsoft apps can exceed this limit. 将来,我们会将此功能扩展到所有应用程序。In the future, we will extend this capability to all apps.

412 前提条件不满足412 Precondition Failed

所有 Planer API POSTPATCHDELETE 请求都需要使用受请求约束的资源的最后一个已知 etag 值指定 If-Match 标头。All Planer API POST, PATCH, and DELETE requests require the If-Match header to be specified with the last known etag value of the resource that is subject to the request. 如果请求中指定的 etag 值不再匹配服务中资源的版本,也会返回 412 状态代码。The 412 status code can also be returned if the etag value specified in the request no longer matches a version of the resource in the service. 在这种情况下,客户端应该再次读取资源并获取新的 etag。In this case, the clients should read the resource again and get a new etag.