Verwenden der Planner-REST-APIUse the Planner REST API

Mit der Planner-API in Microsoft Graph können Sie Aufgaben erstellen und diese Benutzern in einer Office 365-Gruppe zuweisen.You can use the Planner API in Microsoft Graph to create tasks and assign them to users in a group in Office 365.

Bevor Sie mit der Arbeit in der Planner-API beginnen, sollten Sie wissen, wie die wichtigsten Objekte in der Planner-API zueinander und zu Office 365-Gruppen in Beziehung stehen.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-GruppenOffice 365 Groups

Office 365-Gruppen sind die Besitzer der Pläne in der Planner-API.Office 365 groups are the owners of the plans in the Planner API. Um die im Besitz einer Gruppe befindlichen Pläne abzurufen, stellen Sie die folgende HTTP-Anforderung.To get the plans owned by a group, make the following HTTP request.

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

Wenn Sie einen neuen Plan erstellen, definieren Sie eine Gruppe als dessen Besitzer, indem Sie einfach die owner-Eigenschaft für ein Planobjekt festlegen.When creating a new plan, make a group its owner by setting the owner property on a plan object. Pläne müssen im Besitz von Gruppen sein.Plans must be owned by groups.

Hinweis: Der Benutzer, der den Plan erstellt, muss ein Mitglied der Gruppe sein, die den Plan besitzt.Note: The user who is creating the plan must be a member of the group that will own the plan. Wenn Sie eine neue Gruppe über Gruppe erstellen erstellen, werden Sie nicht automatisch als Mitglied zur Gruppe hinzugefügt.When you create a new group by using Create group, you are not added to the group as a member. Nachdem die Gruppe erstellt wurde, fügen Sie sich selbst mithilfe der Option zum Veröffentlichen der Gruppenmitglieder als Mitglied hinzu.After the group is created, add yourself as a member by using group post members.

PlänePlans

Pläne sind die Container von Aufgaben.Plans are the containers of tasks. Um eine Aufgabe in einem Plan zu erstellen, legen Sie die planId-Eigenschaft des Aufgabenobjekts beim Erstellen der Aufgabe auf die ID des Plans fest.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. Aufgaben können derzeit nicht ohne Pläne erstellt werden.Tasks currently cannot be created without plans. Um die Aufgaben in einem Plan abzurufen, stellen Sie die folgende HTTP-Anforderung.To retrieve the tasks in a plan, make the following HTTP request.

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

AufgabenTasks

Jede Aufgabe kann einem Benutzer zugewiesen werden, indem eine Zuweisung in der assignments-Eigenschaft des Aufgabenobjekts hinzugefügt wird. Die ID des Benutzers, dem die Aufgabe zugewiesen werden soll, ist der Name der offenen Eigenschaft von assignments, und die orderHint-Eigenschaft der Zuweisung muss angegeben werden.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.

Aufgaben- und PlandetailsTask and plan details

Planner-Ressourcen sind in einfache Objekte und Detailobjekte unterteilt. Einfache Objekte bieten Zugriff auf allgemeine Eigenschaften der Ressourcen, geeignet für Listenansichten, während die Detailobjekte Zugriff auf umfassende Eigenschaften der Ressourcen bieten, die für Drilldownansichten geeignet sind.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.

VisualisierungVisualization

Neben Aufgaben- und Plandaten stellt die Planner-API auch Ressourcen zum Erstellen einer allgemeinen Visualisierung von Daten für alle Clients bereit.Aside from task and plan data, the Planner API also provides resources for creating a common visualization of data across clients. Für Aufgaben stehen mehrere Arten von Visualisierungsdaten zur Verfügung, wie in der folgenden Tabelle aufgeführt.Several types of visualization data are available for tasks, as listed in the following table.

Aufgaben werden angezeigt alsTasks are shown as Aufgaben werden sortiert mit Informationen ausTasks are ordered with information from
Flache Liste (Aufgaben in einem Plan)Flat list (tasks in a plan) orderHint-Eigenschaft für AufgabenorderHint property on tasks
Flache Liste (einem Benutzer zugewiesene Aufgaben)Flat list (tasks assigned to a user) assigneePriority-Eigenschaft für AufgabenassigneePriority property on tasks
Boardansicht mit Spalten für Beauftragte (zugewiesen zum Task Board)Board view with columns for assignees (assigned to task board) assignedToTaskBoardTaskFormat-ObjektassignedToTaskBoardTaskFormat object
Boardansicht mit Spalten für den Fortschritt der Aufgabe auf dem Weg zur Fertigstellung (Fortschritts-Task Board)Board view with columns for progress of the task towards completion (progress task board) progressTaskBoardTaskFormat-ObjektprogressTaskBoardTaskFormat object
Boardansicht mit benutzerdefinierten Spalten von Aufgaben (Bucket-Task Board):Board view with custom columns of tasks (bucket task board): bucketTaskBoardTaskFormat-ObjektbucketTaskBoardTaskFormat object

Die benutzerdefinierten Spalten im Bucket-Task Board werden durch bucket-Objekte dargestellt und ihre Reihenfolge durch die orderHint-Eigenschaft des Objekts.The custom columns in the bucket task board are represented by bucket objects, and their order by orderHint property on the object.

Die gesamte Sortierung wird durch die unter ORDER-Hinweise in Planner genannten Grundsätze gesteuert.All the ordering is controlled by the principles described in Planner order hints.

Versionsverwaltung für Planner-RessourcenPlanner resource versioning

Planner verwendet für alle Ressourcen ETags zur Versionsverwaltung.Planner versions all resources using etags. Diese ETags werden mit der @odata.etag-Eigenschaft in jeder Ressource zurückgegeben.These etags are returned with @odata.etag property on each resource. PATCH- und DELETE-Anfragen erfordern, dass das letzte ETag, das dem Client bekannt ist, mit einer If-Match-Kopfzeile angegeben wird.PATCH and DELETE requests require the last etag known by the client to be specified with a If-Match header. Planner erlaubt Änderungen an älteren Versionen von Ressourcen, sofern die beabsichtigte Änderung nicht in Konflikt mit neueren Änderungen steht, die vom Planner-Dienst für dieselbe Ressource akzeptiert wurden.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. Die Clients können ermitteln, welches ETag für eine bestimmte Ressource neuer ist, indem sie berechnen, welcher Etag-Wert in einem Vergleich von Ordnungszeichenfolgen größer ist.The clients can identify which etag for the same resource is newer by calculating which etag value is greater in ordinal string comparison. Jede Ressource verfügt über ein eigenes ETag.Each resource has a unique etag. ETag-Werte für verschiedene Ressourcen, einschließlich solcher mit Einschlussbeziehungen, können nicht verglichen werden.Etag values for different resources, including those with containment relationships, cannot be compared. Die Client-Apps müssen die Fehlercodes 409 und 412 im Zusammenhang mit der Versionsverwaltung verarbeiten können, indem sie die aktuelle Version des Elements lesen und in Konflikt stehende Änderungen beheben.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.

Häufige Planner-FehlerbedingungenCommon Planner error conditions

Neben allgemeinen Fehlern, die für Microsoft Graph gelten, sind einige Fehlerbedingungen für die Planner-API spezifisch.In addition to general errors that apply to Microsoft Graph, some error conditions are specific to the Planner API.

400 Ungültige Anforderung400 Bad request

In einigen häufigen Szenarios können POST- und PATCH-Anforderungen auch den Fehlerstatuscode 400 zurückgeben.In some common scenarios, POST and PATCH requests can return a 400 status code. Nachfolgend sehen Sie die häufigsten Ursachen:The following are some of the common causes:

  • Eigenschaften mit offenem Typ weisen nicht den richtigen Typ auf, der Typ ist nicht angegeben oder sie enthalten keine Eigenschaften. Beispielsweise müssen plannerAssignments-Eigenschaften mit komplexen Werten die -Eigenschaft mit dem Wert deklarieren.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.
  • Werte von Anordnungshinweisen weisen nicht das richtige Format auf. Beispiel: Ein Anordnungshinweiswert ist direkt auf den vom Client zurückgegebenen Wert festgelegt.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.
  • Die Daten sind logisch inkonsistent. Das Startdatum einer Aufgabe liegt z. B. nach dem Fälligkeitsdatum der Aufgabe.The data is logically inconsistent. For example, start date of task is later than due date of the task.

403 Verboten403 Forbidden

Zusätzlich zu den allgemeinen Fehlern gibt die Planner-API auch den Statuscode 403 zurück, wenn ein von einem Dienst definierter Grenzwert überschritten wurde.In addition to the general errors, the Planner API also returns the 403 status code when a service-defined limit has been exceeded. In diesem Fall gibt die code-Eigenschaft des error-Ressourcentyps den Typ des Grenzwerts an, der von der Anforderung überschritten wurde.If this is the case, the code property on the error resource type will indicate the type of the limit exceeded by the request. Nachfolgend finden Sie die möglichen Werte für die Grenzwerttypen.The following are the possible values for the limit types.

WertValue BeschreibungDescription
MaximumProjectsOwnedByUserMaximumProjectsOwnedByUser Der Grenzwert für die maximale Anzahl von Plänen, die im Besitz eines Gruppe sein können, wurde überschritten. Dieser Grenzwert basiert auf der owner-Eigenschaft der plannerPlan-Ressource.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 Der Grenzwert für die maximale Anzahl von Plänen, die für einen Benutzer freigegeben werden können, wurde überschritten. Dieser Grenzwert basiert auf der sharedWith-Eigenschaft der plannerPlanDetails-Ressource.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 Der Grenzwert für die maximale Anzahl von Aufgaben, die von einem Benutzer erstellt werden können, wurde überschritten. Dieser Grenzwert basiert auf der createdBy-Eigenschaft der plannerTask-Ressource.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 Der Grenzwert für die maximale Anzahl von Aufgaben, die einem Benutzer zugewiesen werden können, wurde überschritten. Dieser Grenzwert basiert auf der assignments-Eigenschaft der plannerTask-Ressource.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 Der Grenzwert für die maximale Anzahl von Aufgaben in einem Plan wurde überschritten. Dieser Grenzwert basiert auf der planId-Eigenschaft der plannerTask-Ressource.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 Der Grenzwert für die maximale Anzahl von nicht abgeschlossenen Aufgaben in einem Plan wurde überschritten. Dieser Grenzwert basiert auf den Eigenschaften planId und percentComplete der plannerTask-Ressource.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 Der Grenzwert für die maximale Anzahl von Buckets in einem Plan wurde überschritten. Dieser Grenzwert basiert auf der planId-Eigenschaft der plannerBucket-Ressource.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 Die sharedWith-Eigenschaft der plannerPlanDetails-Ressource enthält zu viele Werte.The sharedWith property on the plannerPlanDetails resource contains too many values.
MaximumReferencesOnTaskMaximumReferencesOnTask Die references-Eigenschaft der plannerTaskDetails-Ressource enthält zu viele Werte.The references property on the plannerTaskDetails resource contains too many values.
MaximumChecklistItemsOnTaskMaximumChecklistItemsOnTask Die checklist-Eigenschaft der plannerTaskDetails-Ressource enthält zu viele Werte.The checklist property on the plannerTaskDetails resource contains too many values.
MaximumAssigneesInTasksMaximumAssigneesInTasks Die assignments-Eigenschaft der plannerTask-Ressource enthält zu viele Werte.The assignments property on the plannerTask resource contains too many values.
MaximumPlannerPlansMaximumPlannerPlans Die Gruppe enthält bereits einen Plan.The group already contains a Plan. Gruppen können derzeit nur einen Plan enthalten.Currently, groups can only contain one Plan. Hinweis: Einige Microsoft-Apps können diesen Grenzwert überschreiten.Note: Some Microsoft apps can exceed this limit. Diese Funktion wird in Zukunft auf alle Apps erweitert.In the future, we will extend this capability to all apps.

412 Fehler bei Vorbedingung412 Precondition Failed

Alle POST-, PATCH- und DELETE Anforderungen in der Planner-API erfordern, dass im If-Match-Header der letzte bekannte Etag-Wert der Ressource angegeben wird, für die die Anforderung gilt.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. Der Statuscode 412 kann auch zurückgegeben werden, wenn der in der Anforderung angegeben Etag-Wert nicht mehr einer Version der Ressource im Dienst entspricht.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. In diesem Fall sollten die Clients die Ressource erneut lesen und ein neues Etag abrufen.In this case, the clients should read the resource again and get a new etag.