Utilisation de l’API REST Planificateur

Article
03/26/2023

L’API Planificateur de Microsoft Graph vous permet de créer des tâches et de les affecter aux utilisateurs d’un groupe dans Microsoft 365.

Avant de commencer à utiliser l’API Planificateur, il est important de comprendre le lien entre les principaux objets de l’API Planificateur, ainsi que dans les groupes Microsoft 365.

Planification de conteneurs

Dans le Planificateur Microsoft, les plans sont toujours contenus par une autre ressource. La ressource contenant détermine les règles d’autorisation du plan et de toutes ses tâches, ainsi que le cycle de vie du plan. Par exemple, dans le cas de plans contenus par un groupe Microsoft 365, les membres du groupe peuvent créer, modifier, résoudre et supprimer des tâches dans le plan, ainsi que modifier des propriétés au niveau du plan, telles que le nom du plan ou les noms d’étiquette. En outre, lorsque le groupe est supprimé, tous les plans du groupe sont automatiquement supprimés et, si un groupe est restauré, tous les plans seront automatiquement restaurés.

Le type de conteneur le plus classique est un groupe Microsoft 365.

Type de conteneur : groupes Microsoft 365

Les plans sont généralement contenus dans des groupes Microsoft 365 de l’API Planificateur. Pour obtenir les plans appartenant à un groupe, effectuez la requête HTTP suivante.

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

Lorsque vous créez un plan, définissez la propriété conteneur sur un objet de plan pour qu’un groupe en soit son conteneur. Les plans doivent être contenus par une ressource prise en charge.

Remarque : l’utilisateur qui crée le plan doit être un membre du groupe qui contiendra le plan. Lorsque vous créez un nouveau groupe à l’aide de l’API Création d’un groupe, vous n’y êtes pas automatiquement ajouté en tant que membre. Une fois le groupe créé, ajoutez-vous vous-même en tant que membre à l’aide de la rubrique membres du groupe publication.

Plans

Les plans contiennent des tâches. Pour créer une tâche dans un plan, définissez la propriété planId de l’objet de tâche à l’ID du plan lors de la création de la tâche. Tâches actuellement ne peut pas être créées sans plans. Pour récupérer les tâches dans un plan, faire la demande via HTTP ci-dessous.

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

Tâches

Chaque tâche peut être affectée à un utilisateur en ajoutant une affectation dans la propriété affectations sur l’objet de tâche. L’ID de l’utilisateur à affecter à la tâche est le nom de la propriété open sur les affectations, et la propriété orderHint sur l’affectation doit être spécifiée.

Détails de la tâche et du plan

Planificateur ressources sont organisées en objets de base et en objets de détail. Les objets de base permettent d’accéder aux propriétés courantes des ressources, adaptées aux affichages de liste, tandis que les objets de détail donnent accès à de grandes propriétés des ressources adaptées aux vues d’exploration.

Visualisation

En dehors des tâches et des données de plan, l’API Planificateur fournit également des ressources pour permettre une visualisation des données sur plusieurs clients. Plusieurs types de données de visualisation sont disponibles pour les tâches, tel qu’illustré dans les tableaux ci-dessous.

Les tâches sont affichées sous la forme	Les tâches sont classées avec les informations de
Liste simple (tâches d’un plan)	Propriété orderHint des tâches
Liste simple (tâches affectées à un utilisateur)	Propriété assigneePriority des tâches
Affichage du tableau avec colonnes pour les cessionnaires (affectés au tableau des tâches)	Objet assignedToTaskBoardTaskFormat
Affichage du tableau avec colonnes pour l’avancement de la tâche jusqu’à l’achèvement (tableau des tâches - Avancement)	Objet progressTaskBoardTaskFormat
Affichage du tableau avec colonnes personnalisées des tâches (tableau des tâches - Compartiment) :	Objet bucketTaskBoardTaskFormat

Les colonnes personnalisées dans le tableau des tâches du compartiment sont représentées par les objets decompartiment et sont classées par propriété orderHint de l’objet.

Tout le classement est contrôlé par les principes décrits dans les Conseils de classement Planner.

Contrôle de version des ressources Planner

Planner contrôle les versions de toutes les ressources à l’aide d’en-têtes etags. Ces etags sont retournés avec la propriété @odata.etag sur chaque ressource. Les requêtes PATCH et DELETE nécessitent que le dernier etag connu par le client soit spécifié avec un en-tête If-Match. Planner autorise l’apport de modifications à des versions anciennes de ressources si cette modification n’entre pas en conflit avec les dernières modifications acceptées par le service Planificateur de la même ressource. Les clients peuvent identifier l’etag le plus récent pour la même ressource en calculant la valeur etag la plus grande par comparaison de chaînes ordinale. Chaque ressource comporte un etag distinct. Il n’est pas possible de comparer des valeurs eTag pour différentes ressources, y compris celles avec des relations d’imbrication. Les applications clientes sont censées gérer les codes 409d’erreur liés au contrôle de version et 412 en lisant la dernière version de l’élément et en résolvant les modifications en conflit.

Conditions d’erreur courantes de Planner

En plus des erreurs générales qui s’appliquent à Microsoft Graph, certaines conditions d’erreur sont propres à l’API du planificateur.

400 Demande incorrecte

Dans certains scénarios courants, les requêtes POST et PATCH peuvent renvoyer un code d’état 400. Voici quelques-unes des causes courantes :

Les propriétés Open Type ne sont pas de types corrects, ou le type n’est pas spécifié, ou elles ne contiennent aucune propriété. Par exemple, les propriétés plannerAssignments avec des valeurs complexes doivent déclarer @odata.type avec la valeur microsoft.graph.plannerAssignment.
Les valeurs d’indicateur d’ordre n’ont pas le format correct. Par exemple, une valeur d’indicateur de commande est définie directement sur la valeur retournée au client.
Les données sont logiquement incohérentes. Par exemple, la date de début de la tâche est postérieure à la date d’échéance de la tâche.

403 Interdit

En plus des erreurs générales, l’API Planificateur renvoie également le code 403 d’état lorsqu’une limite définie par le service est dépassée. Si tel est le cas, la propriété code du type de ressource d’erreur indique le type de la limite dépassée par la requête. Pour plus d’informations sur les limites, consultez Planificateur limites . Les valeurs possibles pour les types de limite incluent ce qui suit.

Valeur	Description
MaximumProjectsOwnedByUser	Le nombre maximal de plans contenus dans une limite de groupe a été dépassé. Cette limite s’applique aux plans contenus par un groupe en fonction de la propriété conteneur de la ressource plannerPlan.
MaximumProjectsSharedWithUser	Le nombre maximal de plans partagés avec une limite d’utilisateurs a été dépassé. Cette limite est basée sur la propriété sharedWith de la ressource plannerPlanDetails .
MaximumTasksCreatedByUser	Le nombre maximal de tâches créées par une limite d’utilisateur a été dépassé. Cette limite est basée sur la propriété createdBy sur la ressource plannerTask .
MaximumTasksAssignedToUser	Le nombre maximal de tâches affectées à une limite d’utilisateurs a été dépassé. Cette limite est basée sur la propriété assignments sur la ressource plannerTask .
MaximumTasksInProject	Le nombre maximal de tâches dans une limite de plan a été dépassé. Cette limite est basée sur la propriété planId de la ressource plannerTask .
MaximumActiveTasksInProject	Le nombre maximal de tâches qui ne sont pas terminées dans une limite de plan a été dépassé. Cette limite est basée sur les propriétés planId et percentComplete de la ressource plannerTask .
MaximumBucketsInProject	Le nombre maximal de compartiments dans une limite de plan a été dépassé. Cette limite est basée sur la propriété planId sur la ressource plannerBucket .
MaximumUsersSharedWithProject	La propriété sharedWith de la ressource plannerPlanDetails contient trop de valeurs.
MaximumReferencesOnTask	La propriété références de la ressource plannerTaskDetails contient trop de valeurs.
MaximumChecklistItemsOnTask	La propriété liste de contrôle de la ressource plannerTaskDetails contient trop de valeurs.
MaximumAssigneesInTasks	La propriété affectations de la ressource plannerTask contient trop de valeurs.
MaximumPlannerPlans	Le groupe contient déjà le nombre maximal de plans détenus par un utilisateur, qui est actuellement de 200. Pour plus d’informations sur les limites, consultez limites Planificateur.

412 Échec de la condition préalable

Toutes les requêtes POST, PATCH et DELETE dans l’API Planificateur requièrent la spécification de l’en-tête If-Match avec la dernière valeur etag connue de la ressource faisant l’objet de la requête. Le code d’état 412 peut également être renvoyé si la valeur etag spécifiée dans la requête ne correspond plus à une version de la ressource dans le service. Dans ce cas, les clients doivent lire à nouveau la ressource et obtenir un nouvel etag.