Utilisation de l’API REST Planificateur

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 utile de comprendre comment les principaux objets sont liés les uns aux autres et aux groupes Microsoft 365.

Planification de conteneurs

Dans le Planificateur Microsoft, les plans sont toujours contenus dans une autre ressource. La ressource conteneur, plannerPlanContainer, détermine les règles d’autorisation du plan et de toutes les tâches qu’il contient, ainsi que le cycle de vie du plan. Vous pouvez créer un plan dans un conteneur de l’un des types suivants : driveItem, groupe Microsoft 365, plannerTask, projet Planner, roster, teamsChannel ou utilisateur.

Le type de conteneur le plus courant est un groupe.

Type de conteneur : groupes Microsoft 365

Les plans sont généralement contenus dans des groupes dans l’API Planificateur.

Les membres du groupe peuvent créer, modifier, résoudre et supprimer des tâches dans le plan. Les membres du groupe peuvent également modifier certaines propriétés au niveau du plan, telles que le nom du plan ou les noms des étiquettes. En outre, lorsque le groupe est supprimé, tous les plans du groupe sont automatiquement supprimés. À l’inverse, si un groupe est restauré, tous les plans sont automatiquement restaurés.

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 membre du groupe qui contient le plan. Lorsque vous créez un groupe à l’aide de Créer un groupe, vous n’êtes pas ajouté au groupe 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.

Type de conteneur : tâche du planificateur

Le plannerTask type de conteneur prend en charge les plans devant être contenus par une tâche du Planificateur. Les plans contenus par une tâche du Planificateur sont supprimés lorsque la tâche est supprimée.

Pour créer un plan dans le conteneur d’une tâche du Planificateur, définissez la propriété de conteneur sur un objet de plan avec le type défini sur plannerTask, et définissez l’ID sur l’ID de la tâche du Planificateur.

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

Vous pouvez également spécifier l’URL d’une tâche du Planificateur.

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

Type de conteneur : Canal Teams

Le teamsChannel type de conteneur prend en charge les plans créés dans des canaux partagés dans Teams, où le canal est le conteneur du plan. Les plans épinglés dans des canaux partagés sont supprimés lorsque le canal est supprimé.

Pour créer un plan dans le conteneur d’un canal Teams, définissez la propriété de conteneur sur un objet de plan avec le type , teamsChannelet l’id doit être au format « {team-id}/channels/{channel-id} ».

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

Vous pouvez également spécifier l’URL d’un canal partagé dans Teams.

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

Type de conteneur : Utilisateur

Le type de conteneur utilisateur prend en charge les plans personnels, où l’utilisateur est le seul utilisateur à suivre ses tâches individuelles. Cela offre aux utilisateurs la possibilité de partager ou de collaborer sur leurs plans personnels. Les plans créés pour un seul utilisateur sont automatiquement supprimés lorsque l’utilisateur est supprimé.

Pour créer un plan dans le conteneur d’un utilisateur, définissez la propriété conteneur sur un objet de plan dont le type est .user

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

Vous pouvez également spécifier l’URL d’un utilisateur.

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

Les utilisateurs peuvent mettre à niveau leurs plans personnels en plans de groupe en déplaçant le plan du conteneur utilisateur vers un conteneur de groupe, en modifiant le type de conteneur pour le plan de user à group.

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. Actuellement, il est impossible de créer des tâches 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

Objectifs

Les objectifs expriment les résultats de haut niveau qu’un ensemble de tâches d’un plan est destiné à accomplir. Un plan peut avoir plusieurs objectifs, et une tâche peut être associée à plusieurs objectifs.

Pour récupérer les objectifs dans un plan, effectuez la requête HTTP suivante.

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

Utilisez la propriété goalIds en lecture seule d’un objet plannerTask pour identifier les objectifs associés à la tâche.

Tâches

Vous pouvez attribuer chaque tâche à un utilisateur en ajoutant une affectation dans la propriété affectations de l’objet tâche. L’ID de l’utilisateur pour affecter la tâche est le nom de la propriété ouverte sur les devoirs, et la propriété orderHint sur le devoir doit être spécifiée.

Détails de la tâche et du plan

Les ressources du Planificateur 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 communes des ressources, adaptées aux vues de liste, tandis que les objets de détail donnent accès à de grandes propriétés des ressources adaptées aux vues descendantes.

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 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.

Les principes d’ordre sont décrits dans les conseils d’ordre du Planificateur.

Suivi des modifications à l’aide d’une requête delta

Une requête delta de Planner prend en charge les objets requêtes auxquels l’utilisateur est abonné.

Les utilisateurs sont abonnés aux objets suivants.

Remplir le cache de l’objet pour les requêtes delta

Si vous voulez utiliser la requête delta Planner API, tenez à jour un cache d’objets local auxquels l’utilisateur s’intéresse afin d’appliquer les modifications depuis le flux de réponse delta.

Les objets de charge utile delta que la requête delta du Planificateur peut actuellement retourner sont des types suivants :

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

Utilisez les méthodes GET correspondantes sur la ressource pour obtenir l'état initial des objets à remplir dans le cache local.

Examen de l’historique du plan

Le Planificateur prend en charge une API pour obtenir l’historique des modifications apportées aux tâches au sein d’un plan.

Différencier entre la création et la modification d’un objet

Dans certains scénarios, l’appelant souhaite faire la distinction entre la création et ;a modification d’un objet au sein du flux de requêtes delta du Planificateur.

Ces instructions permettent de déduire ;a création d’un objet :

• La propriété createdBy s’affiche sur les objets nouvellement créés.
• Un objet plannerTask nouvellement créé est suivi de son objet plannerTaskDetails correspondant.
• Un objet plannerPlan nouvellement créé est suivi de son objet plannerPlanDetails correspondant.

Utilisation

L’appelant dot avoir un cache contenant des objets abonnés. Pour plus d’informations sur la façon remplir le cache local d’objets abonnés, voir remplir le cache d’objets pour les requêtes delta.

Le flux d'appel de requête delta du planificateur est le suivant :

1. L’appelant établit une requête de synchronisation delta, obtenant un nextLink et un ensemble de modifications vide.
2. L’appelant doit remplir le cache d’objets pour les requêtes delta avec les objets auxquels l’utilisateur est abonné, et met à jour son cache.
3. L’appelant suit le nextLink fourni dans la requête de synchronisation initiale delta pour obtenir un nouveau deltaLink à toutes les modifications depuis l’étape précédente.
4. L’appelant applique les modifications dans la réponse renvoyée delta aux objets dans son cache.
5. L’appelant suit la nouvelle classe deltaLink pour obtenir la classe suivante deltaLink et les modifications depuis que la classe deltaLink a été générée.
6. L’appelant applique les modifications (le cas échéant) et attend un court moment avant de réexécuter l’étape précédente et cette étape.

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. Le Planificateur autorise les modifications apportées aux anciennes versions des ressources, si la modification prévue n’entre pas en conflit avec les modifications plus récentes acceptées par le service Planificateur sur 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. Les valeurs Etag de différentes ressources, y compris les ressources avec des relations d’inclusion, ne peuvent pas être comparées. 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 de type ouvert avaient un type spécifié incorrect ou aucun type spécifié, ou ne contenaient aucune propriété. Par exemple, les propriétés plannerAssignments avec des valeurs complexes doivent déclarer la propriété @odata.type avec la valeur microsoft.graph.plannerAssignment.
• Le format des valeurs d’indicateur d’ordre n’était pas correct. Par exemple, la valeur d’un indicateur d’ordre a été définie directement sur la valeur renvoyé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

Outre les erreurs générales, l’API Planificateur renvoie également le code de status en cas de dépassement d’une limite définie par le 403 service. Si c’est le cas, la propriété code sur le type de ressource d’erreur indique le type de limite dépassé par la requête. Les valeurs possibles pour les types de limite incluent ce qui suit.

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.