使用 Planner REST APIUse the Planner REST API

重要

Microsoft Graph 中/beta的版本下的 api 可能会发生更改。APIs under the /beta version in Microsoft Graph are subject to change. 不支持在生产应用程序中使用这些 API。Use of these APIs in production applications is not supported.

你可以使用 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 之前,需要了解 Planner API 中主对象互相之间以及与 Office 365 组的关系。Before you get started with the Planner API, it will be helpful 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.

使用 delta 查询跟踪更改Track changes using delta query

Planner 的 delta 查询功能支持查询用户订阅的对象。Planner's delta query supports querying objects that the user is subscribed to.

用户订阅了以下对象。Users are subscribed to the following objects.

Planner 资源类型Planner resource type 已订阅的实例Subscribed instances
任务Tasks
  • 由用户创建Created by the user
  • 已分配给用户Assigned to the user
  • 属于用户拥有的计划Belong to a plan that the user owns
  • 包含在通过计划的 SharedWith 集合与用户共享的计划中Contained in a plan shared with the user through the plan's SharedWith collection
计划Plans
  • 通过计划的 SharedWith 集合与用户共享Shared with the user through the plan's SharedWith collection
BucketsBuckets
  • 包含在通过计划的 SharedWith 集合与用户共享的计划中Contained in a plan shared with the user through the plan's SharedWith collection

填充 delta 查询的对象缓存Populate the object cache for delta queries

如果要使用 Planner delta 查询 API,请保留用户有兴趣查看的对象的本地缓存,以便应用 delta 响应源中的更改。If you want to use the Planner delta query API, maintain a local cache of objects that the user is interested in observing in order to apply the changes from the delta response feed.

Planner delta 查询当前可以返回的 delta 有效负载对象将为以下类型:The delta payload objects that the Planner delta query can currently return will be of the following types:

使用资源中的相应 GET 方法获取要填充到本地缓存的对象初始状态。Use the corresponding GET methods on the resource to obtain the initial state of objects to be populated into the local cache.

区分对象创建和对象修改Differentiating between object creation and object modification

在某些情况下,调用方可能希望区分 Planner 的 delta 查询源中的对象创建和对象修改。In certain scenarios, the caller might want to distinguish between object creation and object modification within Planner's delta query feed.

可使用以下准则推断对象创建:These guidelines can be used to infer object creation:

  • createdBy 属性仅出现在新创建的对象上。The createdBy property will only appear on newly created objects.
  • 新创建的 plannerTask 对象后面将跟随其对应的 plannerTaskDetails 对象。A newly created plannerTask object will be followed by its corresponding plannerTaskDetails object.
  • 新创建的 plannerPlan 对象后面将跟随其对应的 plannerPlanDetails 对象。A newly created plannerPlan object will be followed by its corresponding plannerPlanDetails object.

用法Usage

调用方期望有一个包含订阅对象的缓存。The caller is expected to have a cache containing subscribed objects. 有关如何填充订阅对象的本地缓存的详细信息,请参阅填充 delta 查询的对象缓存For details about how to fill the local cache of subscribed objects, see Populate the object cache for delta queries.

Planner 的 delta 查询调用流如下所示:Planner's delta query call flow is as follows:

  1. 调用方启动 delta 同步查询,以便获取 nextLink 和空的更改集合。The caller initiates a delta sync query, obtaining a nextLink and an empty collection of changes.
  2. 调用方必须使用用户订阅的对象填充 delta 查询的对象缓存,从而更新其缓存。The caller must populate the object cache for delta queries with objects that the user is subscribed to, updating its cache.
  3. 调用方遵循初始 delta 同步查询中提供的 nextLink,以便获得自上一步以来所做的任何更改的新 deltaLinkThe caller follows the nextLink provided in the initial delta sync query to obtain a new deltaLink to any changes since previous step.
  4. 调用方将返回的 delta 响应中的更改应用于其缓存中的对象。The caller applies the changes in the returned delta response to the objects in its cache.
  5. 调用方遵循新的 deltaLink 以获取下一个 deltaLink,以及自生成当前 deltaLink 以来所做的更改。The caller follows the new deltaLink to obtain the next deltaLink and changes since the current deltaLink was generated.
  6. 调用方应用更改(如果有)并等待一小段时间,然后重新执行上一步和此步骤。The caller applies the changes (if any) and waits a short time before rerunning the previous step and this step.

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.
MaximumFavoritePlansForUserMaximumFavoritePlansForUser plannerUser 资源上的 favoritePlanReferences 属性包含的值过多。The favoritePlanReferences property on the plannerUser resource contains too many values.
MaximumRecentPlansForUserMaximumRecentPlansForUser plannerUser 资源上的 recentPlanReferences 属性包含的值过多。The recentPlanReferences property on the plannerUser resource contains too many values.
MaximumContextsOnPlanMaximumContextsOnPlan plannerPlan 资源上的 contexts 属性包含的值过多。The contexts property on the plannerPlan 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.