Verwenden der Planner-REST-API

  • Artikel

Mit der Planner-API in Microsoft Graph können Sie Aufgaben erstellen und diese Benutzern in einer Microsoft 365-Gruppe zuweisen.

Bevor Sie mit der Arbeit in der Planner-API beginnen, sollten Sie wissen, wie die wichtigsten Objekte in der Planner-API zueinander und zu Microsoft 365-Gruppen in Beziehung stehen.

Plancontainer

In Microsoft Planner sind Pläne immer in einer anderen Ressource enthalten. Die enthaltende Ressource bestimmt die Autorisierungsregeln des Plans mit allen darin enthaltenen Aufgaben sowie den Lebenszyklus des Plans. Beispielsweise können Gruppenmitglieder bei Plänen, die in Microsoft 365-Gruppen enthalten sind, Aufgaben in dem Plan erstellen, bearbeiten, auflösen und löschen sowie einige Eigenschaften auf Planebene ändern, z. B. den Namen des Plans oder Bezeichnungsnamen. Zusätzlich werden alle Pläne in einer Gruppe, wenn diese gelöscht wird, automatisch auch gelöscht, bzw. wenn eine Gruppe wiederhergestellt wird, werden auch alle Pläne automatisch wiederhergestellt.

Der gängigste Containertyp ist eine Microsoft 365-Gruppe.

Containertyp: Microsoft 365-Gruppen

Pläne sind in der Planner-API gängigerweise in Microsoft 365-Gruppen enthalten. Um die im Besitz einer Gruppe befindlichen Pläne abzurufen, stellen Sie die folgende HTTP-Anforderung.

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

Wenn Sie einen neuen Plan erstellen, legen Sie die Eigenschaft container für ein Planobjekt fest, um eine Gruppe zu ihrem Container zu machen. Pläne müssen in einer unterstützen Ressource enthalten sein.

Hinweis: Der Benutzer, der den Plan erstellt, muss Mitglied der Gruppe sein, die den Plan aufnehmen soll. Wenn Sie eine neue Gruppe über Gruppe erstellen erstellen, werden Sie nicht automatisch als Mitglied zur Gruppe hinzugefügt. Nachdem die Gruppe erstellt wurde, fügen Sie sich selbst mithilfe der Option zum Veröffentlichen der Gruppenmitglieder als Mitglied hinzu.

Pläne

Pläne sind die Container von Aufgaben. Um eine Aufgabe in einem Plan zu erstellen, legen Sie die Eigenschaft planId des Aufgabenobjekts beim Erstellen der Aufgabe auf die ID des Plans fest. Aufgaben können derzeit nicht ohne Pläne erstellt werden. Um die Aufgaben in einem Plan abzurufen, stellen Sie die folgende HTTP-Anforderung.

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

Aufgaben

Jede Aufgabe kann einem Benutzer zugewiesen werden, indem eine Zuweisung in der Assignments-Eigenschaft für das Aufgabenobjekt hinzugefügt wird. Die ID des Benutzers, der die Aufgabe zuweisen soll, ist der Name der offenen Eigenschaft für Zuweisungen, und die orderHint-Eigenschaft für die Zuweisung muss angegeben werden.

Aufgaben- und Plandetails

Planner Ressourcen sind in grundlegende Objekte und Detailobjekte angeordnet. Grundlegende Objekte bieten Zugriff auf allgemeine Eigenschaften der Ressourcen, die für Listenansichten geeignet sind, während die Detailobjekte Zugriff auf große Eigenschaften der Ressourcen bieten, die für Drilldownansichten geeignet sind.

Visualisierung

Neben Aufgaben- und Plandaten stellt die Planner-API auch Ressourcen zum Erstellen einer allgemeinen Visualisierung von Daten für alle Clients bereit. Für Aufgaben stehen mehrere Arten von Visualisierungsdaten zur Verfügung, wie in der folgenden Tabelle aufgeführt.

Aufgaben werden angezeigt als Aufgaben werden sortiert mit Informationen aus
Flache Liste (Aufgaben in einem Plan) orderHint-Eigenschaft für Aufgaben
Flache Liste (einem Benutzer zugewiesene Aufgaben) assigneePriority-Eigenschaft für Aufgaben
Boardansicht mit Spalten für Beauftragte (zugewiesen zum Task Board) assignedToTaskBoardTaskFormat-Objekt
Boardansicht mit Spalten für den Fortschritt der Aufgabe auf dem Weg zur Fertigstellung (Fortschritts-Task Board) progressTaskBoardTaskFormat-Objekt
Boardansicht mit benutzerdefinierten Spalten von Aufgaben (Bucket-Task Board): bucketTaskBoardTaskFormat-Objekt

Die benutzerdefinierten Spalten im Bucket-Task Board werden durch bucket-Objekte dargestellt, und ihre Reihenfolge durch die orderHint-Eigenschaft des Objekts.

Die gesamte Sortierung wird durch die unter ORDER-Hinweise in Planner genannten Grundsätze gesteuert.

Versionsverwaltung für Planner-Ressourcen

Planner verwendet für alle Ressourcen ETags zur Versionsverwaltung. Diese ETags werden mit der Eigenschaft @odata.etag in jeder Ressource zurückgegeben. PATCH- und DELETE-Anfragen erfordern, dass das letzte ETag, das dem Client bekannt ist, mit einer If-Match-Kopfzeile angegeben wird. 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. 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. Jede Ressource verfügt über ein eigenes ETag. ETag-Werte für verschiedene Ressourcen, einschließlich solcher mit Einschlussbeziehungen, können nicht verglichen werden. Es wird erwartet, dass die Client-Apps versionsbezogene Fehlercodes409 verarbeiten und 412 die neueste Version des Elements lesen und die in Konflikt stehenden Änderungen auflösen.

Häufige Planner-Fehlerbedingungen

Neben allgemeinen Fehlern, die für Microsoft Graph gelten, sind einige Fehlerbedingungen für die Planner-API spezifisch.

400 Ungültige Anforderung

In einigen häufigen Szenarios können POST- und PATCH-Anforderungen auch den Fehlerstatuscode 400 zurückgeben. Nachfolgend sehen Sie die häufigsten Ursachen:

  • Open Type-Eigenschaften sind nicht von den richtigen Typen, oder der Typ ist nicht angegeben, oder sie enthalten keine Eigenschaften. Beispielsweise müssen plannerAssignments-Eigenschaften mit komplexen Werten @odata.type-Eigenschaft mit dem Wert microsoft.graph.plannerAssignmentdeklarieren.
  • Die Werte der Reihenfolgenhinweise weisen nicht das richtige Format auf. Beispielsweise wird ein Auftragshinweiswert direkt auf den Wert festgelegt, der an den Client zurückgegeben wird.
  • Die Daten sind logisch inkonsistent. Das Startdatum des Vorgangs liegt beispielsweise nach dem Fälligkeitsdatum des Vorgangs.

403 Verboten

Zusätzlich zu den allgemeinen Fehlern gibt die Planner-API auch den 403-Statuscode zurück, wenn ein von einem Dienst definierter Grenzwert überschritten wurde. In diesem Fall gibt die Eigenschaft code des Fehlerressourcentyps den Typ des Grenzwerts an, der von der Anforderung überschritten wurde. Ausführliche Informationen zu den Grenzwerten finden Sie unter Planner Grenzwerte . Nachfolgend finden Sie die möglichen Werte für die Grenzwerttypen.

Wert Beschreibung
MaximumProjectsOwnedByUser Die maximale Anzahl von Plänen, die in einem Gruppenlimit enthalten sind, wurde überschritten. Dieser Grenzwert gilt für Pläne, die in einer Gruppe enthalten sind, die auf der Eigenschaft container der Ressource plannerPlan basiert.
MaximumProjectsSharedWithUser Die maximale Anzahl von Plänen, die für einen Benutzer freigegeben wurden, wurde überschritten. Dieser Grenzwert basiert auf der sharedWith-Eigenschaft der PlannerPlanDetails-Ressource .
MaximumTasksCreatedByUser Die maximale Anzahl von Aufgaben, die von einem Benutzerlimit erstellt wurden, wurde überschritten. Dieser Grenzwert basiert auf der createdBy-Eigenschaft der plannerTask-Ressource .
MaximumTasksAssignedToUser Die maximale Anzahl von Aufgaben, die einem Benutzer zugewiesen sind, wurde überschritten. Dieser Grenzwert basiert auf der Assignments-Eigenschaft der plannerTask-Ressource .
MaximumTasksInProject Die maximale Anzahl von Vorgängen in einem Planlimit wurde überschritten. Dieser Grenzwert basiert auf der planId-Eigenschaft der plannerTask-Ressource .
MaximumActiveTasksInProject Die maximale Anzahl von Aufgaben, die in einem Planlimit nicht abgeschlossen werden, wurde überschritten. Dieser Grenzwert basiert auf den Eigenschaften planId und percentComplete für die plannerTask-Ressource .
MaximumBucketsInProject Die maximale Anzahl von Buckets in einem Planlimit wurde überschritten. Dieser Grenzwert basiert auf der planId-Eigenschaft der plannerBucket-Ressource .
MaximumUsersSharedWithProject Die Eigenschaft sharedWith der Ressource plannerPlanDetails enthält zu viele Werte.
MaximumReferencesOnTask Die Eingenschaft references der Ressource plannerTaskDetails enthält zu viele Werte.
MaximumChecklistItemsOnTask Die Eigenschaft checklist der Ressource plannerTaskDetails enthält zu viele Werte.
MaximumAssigneesInTasks Die Eigenschaft assignments der Ressource plannerTask enthält zu viele Werte.
MaximumPlannerPlans Die Gruppe enthält bereits die maximale Anzahl von Plänen , die einem Benutzer gehören, die derzeit 200 sind. Ausführliche Informationen zu Grenzwerten finden Sie unter Planner Grenzwerte.

412 Fehler bei Vorbedingung

Alle POST-, PATCH- und DELETE-Anforderungen in der Planner-API erfordern, dass der If-Match-Header mit dem letzten bekannten ETag-Wert der Ressource angegeben wird, für welche die Anforderung gilt. 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. In diesem Fall sollten die Clients die Ressource erneut lesen und ein neues Etag abrufen.