Verwenden der Planner-REST-API

Artikel
11/18/2023

Wichtig

Die APIs unter der /beta Version in Microsoft Graph können sich ändern. Die Verwendung dieser APIs in Produktionsanwendungen wird nicht unterstützt. Um festzustellen, ob eine API in v1.0 verfügbar ist, verwenden Sie die Version Selektor.

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 Standard-Objekte 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 plannerPlanContainer bestimmt die Autorisierungsregeln des Plans und alle darin enthaltenen Aufgaben sowie den Lebenszyklus des Plans. Sie können einen Plan in einem Container mit einem der folgenden Typen erstellen: driveItem, Microsoft 365-Gruppe, Planner Projekt, Liste oder Benutzer.

Der am häufigsten verwendete Containertyp ist eine Gruppe.

Containertyp: Microsoft 365-Gruppen

Pläne sind in der Regel in Gruppen in der Planner-API 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. Wenn dagegen 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 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.

Containertyp: Benutzer

Der Benutzercontainertyp unterstützt persönliche Pläne, bei denen der Benutzer der einzige Benutzer ist, der seine einzelnen Aufgaben nachverfolgt. Dies bietet Benutzern die Flexibilität, ihre persönlichen Pläne zu teilen oder zusammenzuarbeiten. 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 Typ fest user.

{
    "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/me"
    }
}

Benutzer können ihre persönlichen Pläne in gruppenbasierte Pläne aktualisieren, indem sie den Plan vom Benutzercontainer in einen Gruppencontainer verschieben und den Typ des Containers für den Plan von in usergroupä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

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 Reihenfolgenprinzipien werden in Planner Reihenfolgenhinweisen 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.

Planner-Ressourcentyp	Abonnierte Instanzen
Aufgaben	Vom Benutzer erstellt Dem Benutzer zugewiesen Gehören zu einem Plan, den der Benutzer besitzt In einem Plan enthalten, der für den Benutzer über die sharedWith-Sammlung des Plans freigegeben wird.
Pläne	Für den Benutzer über die sharedWith-Sammlung des Plans freigegeben.
Buckets	In einem Plan enthalten, der für den Benutzer über die sharedWith-Sammlung des Plans freigegeben wird.

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 Deltanutzlastobjekte, die die Planner Deltaabfrage derzeit zurückgeben kann, sind von den folgenden Typen:

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.

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 plannerPlan-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:

Der Aufrufer initiiert eine Delta-Synchronisierungsabfrage, wodurch ein nextLink-Element und eine leere Auflistung von Änderungen abgerufen wird.
Der Aufrufer muss den Objektcache für Delta-Abfragen mit Objekten auffüllen, die der Benutzer abonniert hat, wodurch der Cache aktualisiert wird.
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.
Der Aufrufer wendet die Änderungen in der zurückgegebenen Delta-Antwort auf die Objekte im Cache an.
Der Aufrufer folgt dem neuen deltaLink, um den nächsten deltaLink und Änderungen abzurufen, seit das aktuelle deltaLink generiert wurde.
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 lässt Änderungen an älteren Versionen von Ressourcen zu, wenn die beabsichtigte Änderung nicht mit neueren Änderungen in Konflikt tritt, 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 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:

Für open Type-Eigenschaften wurde der falsche Typ angegeben oder kein Typ angegeben, oder es enthielten keine Eigenschaften. Beispielsweise müssen plannerAssignments-Eigenschaften mit komplexen Werten @odata.type-Eigenschaft mit dem Wert microsoft.graph.plannerAssignmentdeklarieren.
Bestellhinweiswerte hatten nicht das richtige Format. Beispielsweise wurde ein Bestellhinweiswert direkt auf den Wert festgelegt, der an den Client zurückgegeben wurde.
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 status Code zurück, wenn ein dienstdefinierter Grenzwert überschritten wird. Wenn dies der Grund ist, gibt die Codeeigenschaft für den Fehlerressourcentyp den Typ des Grenzwerts an, der von der Anforderung überschritten wurde. Nachfolgend finden Sie die möglichen Werte für die Grenzwerttypen.

Wert	Beschreibung
MaximumProjectsOwnedByUser	Die maximale Anzahl von Plänen, die in einem Gruppengrenzwert enthalten sind, wurde überschritten. Die Containereigenschaft der plannerPlan-Ressource bestimmt diesen Grenzwert.
MaximumProjectsSharedWithUser	Die maximale Anzahl von Plänen, die für einen Benutzer freigegeben wurden, wurde überschritten. Die sharedWith-Eigenschaft für die PlannerPlanDetails-Ressource bestimmt diesen Grenzwert.
MaximumTasksCreatedByUser	Die maximale Anzahl von Aufgaben, die von einem Benutzerlimit erstellt wurden, wurde überschritten. Die createdBy-Eigenschaft für die plannerTask-Ressource bestimmt diesen Grenzwert.
MaximumTasksAssignedToUser	Die maximale Anzahl von Aufgaben, die einem Benutzerlimit zugewiesen wurden, wurde überschritten. Die Assignments-Eigenschaft für die plannerTask-Ressource bestimmt diesen Grenzwert.
MaximumTasksInProject	Die maximale Anzahl von Vorgängen in einem Planlimit wurde überschritten. Die planId-Eigenschaft für die plannerTask-Ressource bestimmt diesen Grenzwert.
MaximumActiveTasksInProject	Die maximale Anzahl von Vorgängen, die in einem Planlimit nicht abgeschlossen werden, wurde überschritten. Die Eigenschaften planId und percentComplete für die plannerTask-Ressource bestimmen diesen Grenzwert.
MaximumBucketsInProject	Die maximale Anzahl von Buckets in einem Planlimit wurde überschritten. Die planId-Eigenschaft für die plannerBucket-Ressource bestimmt diesen Grenzwert.
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 Aufgaben-Eigenschaft der plannerTask-Ressource enthält zu viele Werte.
MaximumFavoritePlansForUser	Die favoritePlanReferences-Eigenschaft der plannerUser-Ressource enthält zu viele Werte.
MaximumRecentPlansForUser	Die recentPlanReferences-Eigenschaft der plannerUser-Ressource enthält zu viele Werte.
MaximumContextsOnPlan	Die contexts-Eigenschaft der plannerPlan-Ressource enthält zu viele Werte.

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.