Verwenden der Planner-REST-API

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 Planner-API beginnen, ist es hilfreich zu verstehen, wie die Hauptobjekte miteinander und mit Microsoft 365-Gruppen zusammenhängen.

Plancontainer

In Microsoft Planner sind Pläne immer in einer anderen Ressource enthalten. Die enthaltende Ressource, plannerPlanContainer, bestimmt die Berechtigungsregeln des Plans und aller darin enthaltenen Aufgaben sowie den Lebenszyklus des Plans. Sie können einen Plan in einem Container eines der folgenden Typen erstellen: driveItem, Microsoft 365 group, plannerTask, Planner project, roster, teamsChannel oder user.

Der häufigste Containertyp ist eine Gruppe.

Containertyp: Microsoft 365-Gruppen

Pläne sind in der Planner-API häufig in Gruppen enthalten.

Gruppenmitglieder können Aufgaben im Plan erstellen, bearbeiten, auflösen und löschen. Gruppenmitglieder können auch einige Eigenschaften auf Planebene ändern, z. B. den Namen des Plans oder Bezeichnungsnamen. Wenn die Gruppe gelöscht wird, werden außerdem alle Pläne in der Gruppe automatisch gelöscht. Umgekehrt, wenn eine Gruppe wiederhergestellt wird, werden alle Pläne automatisch wiederhergestellt.

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 enthält. Wenn Sie mithilfe von "Gruppe erstellen" eine neue Gruppe erstellen, werden Sie der Gruppe nicht als Mitglied hinzugefügt. Nachdem die Gruppe erstellt wurde, fügen Sie sich selbst mithilfe der Option zum Veröffentlichen der Gruppenmitglieder als Mitglied hinzu.

Containertyp: Planner-Aufgabe

Der plannerTask Containertyp unterstützt Pläne, die in einer Planner-Aufgabe enthalten sind. Pläne, die in einer Planner-Aufgabe enthalten sind, werden gelöscht, wenn die Aufgabe gelöscht wird.

Um einen neuen Plan im Container einer Planner-Aufgabe zu erstellen, legen Sie die Containereigenschaft für ein Planobjekt fest, dessen Typ auf festgelegt ist plannerTask, und legen Sie id auf die ID der Planner-Aufgabe fest.

{
    "container": {
        "id": "{task-id}",
        "type": "plannerTask"
    }
}

Alternativ können Sie die URL für eine Planner-Aufgabe angeben.

{
    "container": {
        "url": "https://graph.microsoft.com/beta/planner/tasks/{task-id}"
    }
}

Containertyp: Teams-Kanal

Der teamsChannel Containertyp unterstützt Pläne, die in freigegebenen Kanälen in Teams erstellt wurden, wobei der Kanal der Container für den Plan ist. Pläne, die in freigegebenen Kanälen angeheftet sind, werden gelöscht, wenn der Kanal gelöscht wird.

Um einen neuen Plan im Container eines Teams-Kanals zu erstellen, legen Sie die Containereigenschaft für ein Planobjekt mit dem Typ als teamsChannelfest, und die ID sollte als "{team-id}/channels/{channel-id}" formatiert sein.

{
    "container": {
        "id": "{team-id}/channels/{channel-id}",
        "type": "teamsChannel"
    }
}

Alternativ können Sie die URL für einen freigegebenen Kanal in Teams angeben.

{
    "container": {
        "url": "https://graph.microsoft.com/beta/teams/{team-id}/channels/{channel-id}"
    }
}

Containertyp: Benutzer

Der Benutzercontainertyp unterstützt persönliche Pläne, bei denen der Benutzer der einzige Benutzer ist, der seine individuellen Aufgaben verfolgt. Dies bietet Benutzern die Flexibilität, ihre persönlichen Pläne freizugeben oder gemeinsam zu bearbeiten. Pläne, die für einen einzelnen Benutzer erstellt werden, werden automatisch gelöscht, wenn der Benutzer gelöscht wird.

Um einen neuen Plan im Container eines Benutzers zu erstellen, legen Sie die Containereigenschaft für ein Planobjekt mit dem Typuser.

{
    "container": {
        "id": "00000000-0000-0000-0000-000000000000",
        "type": "user"
    }
}

Alternativ können Sie die URL für einen Benutzer angeben.

{
    "container": {
        "url": "https://graph.microsoft.com/beta/users/{id}"
    }
}

Benutzer können ihre persönlichen Pläne in gruppenbasierte Pläne aktualisieren, indem sie den Plan aus dem Benutzercontainer in einen Gruppencontainer verschieben und den Containertyp für den Plan von user in groupändern.

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

Ziele

Ziele drücken die allgemeinen Ergebnisse aus, die mit einer Reihe von Aufgaben in einem Plan erreicht werden sollen. Ein Plan kann mehrere Ziele haben, und eine Aufgabe kann mehreren Zielen zugeordnet sein.

Um die Ziele in einem Plan abzurufen, stellen Sie die folgende HTTP-Anforderung.

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

Verwenden Sie die schreibgeschützte goalIds-Eigenschaft für ein plannerTask-Objekt , um die Ziele zu identifizieren, die der Aufgabe zugeordnet sind.

Aufgaben

Jede Aufgabe kann einem Benutzer zugewiesen werden, indem in der Zuweisungseigenschaft des Aufgabenobjekts eine Zuweisung hinzugefügt wird. Die ID des Benutzers, dem die Aufgabe zugewiesen werden 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 Basisobjekte und Detailobjekte unterteilt. Basisobjekte 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.

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

Die Sortierprinzipien werden in Planner-Bestellhinweisen beschrieben.

Nachverfolgen von Änderungen mithilfe einer Delta-Abfrage

Die Delta-Abfrage von Planner unterstützt das Abfragen von Objekten, die der Benutzer abonniert hat.

Benutzer haben die folgenden Objekte abonniert.

Auffüllen des Objektcaches für Delta-Abfragen

Wenn Sie die Delta-Abfrage-API von Planner verwenden möchten, verwalten Sie einen lokalen Cache von Objekten, die der Benutzer beobachten möchte, um die Änderungen aus dem Delta-Antwortfeed anzuwenden.

Die Delta-Nutzlastobjekte, die die Planner-Delta-Abfrage derzeit zurückgeben kann, sind von den folgenden Typen:

• plannerTask
• plannerTaskDetails
• plannerPlan
• plannerPlanDetails
• plannerBucket
• plannerAssignedToTaskBoardTaskFormat
• plannerBucketTaskBoardTaskFormat
• plannerAssignedToTaskBoardTaskFormat

Verwenden Sie die entsprechenden GET-Methoden in der Ressource, um den ursprünglichen Status von Objekten abzurufen, die im lokalen Cache aufgefüllt werden sollen.

Blick auf die Historie für den Plan

Planner unterstützt eine API zum Abrufen des Verlaufs der Änderungen an Aufgaben innerhalb eines Plans.

Unterscheidung zwischen Objekterstellung und Objektänderung

In bestimmten Szenarien möchte der Aufrufer innerhalb des Delta-Abfragefeeds von Planner vielleicht zwischen Objekterstellung und Objektänderung unterscheiden.

Die folgenden Richtlinien können für das Ableiten der Objekterstellung verwendet werden:

• Die createdBy-Eigenschaft wird für neu erstellte Objekte angezeigt.
• Auf ein neu erstelltes plannerTask-Objekt folgt das entsprechende plannerTaskDetails-Objekt .
• Auf ein neu erstelltes plannerPlanPlan-Objekt folgt das entsprechende plannerPlanDetails-Objekt .

Verwendung

Vom Aufrufer wird erwartet, dass er einen Cache aufweist, der abonnierte Objekte enthält. Weitere Informationen zum Füllen des lokalen Caches abonnierter Objekte finden Sie unter Auffüllen des Objektcaches für Delta-Abfragen.

Der Aufruffluss von Delta-Abfragen in Planner ist wie folgt:

1. Der Aufrufer initiiert eine Delta-Synchronisierungsabfrage, wodurch ein nextLink-Element und eine leere Auflistung von Änderungen abgerufen wird.
2. Der Aufrufer muss den Objektcache für Delta-Abfragen mit Objekten auffüllen, die der Benutzer abonniert hat, wodurch der Cache aktualisiert wird.
3. Der Aufrufer folgt dem in der ursprünglichen Delta-Synchronisierungsabfrage bereitgestellten nextLink, um einen neuen deltaLink für alle Änderungen seit dem vorherigen Schritt abzurufen.
4. Der Aufrufer wendet die Änderungen in der zurückgegebenen Delta-Antwort auf die Objekte im Cache an.
5. Der Aufrufer folgt dem neuen deltaLink, um den nächsten deltaLink und Änderungen abzurufen, seit das aktuelle deltaLink generiert wurde.
6. Der Aufrufer wendet die Änderungen (sofern vorhanden) an und wartet einen Moment, bevor der vorherige Schritt und dieser Schritt erneut ausgeführt werden.

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 ermöglicht Änderungen an älteren Versionen von Ressourcen, wenn die beabsichtigte Änderung nicht mit neueren Änderungen in Konflikt steht, die vom Planner-Dienst für dieselbe Ressource akzeptiert werden. 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 Ressourcen mit Containment-Beziehungen, können nicht verglichen werden. Von den Client-Apps wird erwartet, dass sie Versionsfehlercodes409 verarbeiten, 412 die neueste Version des Elements lesen und die in Konflikt stehenden Änderungen beheben.

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:

• Bei den Open Type-Eigenschaften war der falsche Typ angegeben, oder es wurde kein Typ angegeben, oder sie enthielten keine Eigenschaften. Beispielsweise müssen plannerAssignments-Eigenschaften mit komplexen Werten @odata.type-Eigenschaft mit dem Wert microsoft.graph.plannerAssignmentdeklarieren.
• Die Werte für Bestellhinweise hatten nicht das richtige Format. Beispielsweise wurde ein Bestellhinweiswert direkt auf den an den Client zurückgegebenen Wert festgelegt.
• Die Daten sind logisch inkonsistent. So liegt beispielsweise das Startdatum der Aufgabe nach dem Fälligkeitsdatum der Aufgabe.

403 Verboten

Zusätzlich zu den allgemeinen Fehlern gibt die Planner-API auch den 403 Status zurück, wenn ein dienstdefinierter Grenzwert überschritten wird. Ist dies der Fall, gibt die Code-Eigenschaft des Fehlerressourcentyps den Typ des Grenzwerts an, der von der Anforderung überschritten wurde. Nachfolgend finden Sie die möglichen Werte für die Grenzwerttypen.

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.