Partager via

Utilisation de l’API REST Planificateur

  • Article

Importante

Les API sous la version /beta dans Microsoft Graph sont susceptibles d’être modifiées. L’utilisation de ces API dans des applications de production n’est pas prise en charge. Pour déterminer si une API est disponible dans v1.0, utilisez le sélecteur Version .

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 objets principaux 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 contenant, plannerPlanContainer, détermine les règles d’autorisation du plan et 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, projet Planner, liste 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 d’étiquette. 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 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.

Type de conteneur : Utilisateur

Le type de conteneur utilisateur prend en charge les plans personnels, où l’utilisateur est le seul utilisateur qui effectue le suivi de 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 avec le typeuser.

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

Les utilisateurs peuvent mettre à niveau leurs plans personnels en plans basés sur des groupes en déplaçant le plan du conteneur d’utilisateurs vers un conteneur de groupe, en remplaçant le type du conteneur pour le plan par usergroup.

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. Les tâches ne peuvent actuellement 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

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 courantes des ressources, adaptées aux affichages de liste, tandis que les objets de détail permettent d’accéder à 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.

Les principes de classement sont décrits dans Indicateurs 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.

Type de ressource Planner Instances abonnés
tâches
  • Créées par l’utilisateur
  • Affectées à l’utilisateur
  • Appartenant à un plan qui appartient à l’utilisateur
  • Contenues dans un plan partagé avec l’utilisateur via la collection sharedWith du plan
plans
  • Partagés avec l’utilisateur via la collection sharedWith du plan
compartiments
  • Contenues dans un plan partagé avec l’utilisateur via la collection sharedWith du plan

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 :

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

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 apparaît 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 à des versions antérieures des ressources, si la modification prévue n’est 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 pour différentes ressources, y compris les ressources avec des relations de confinement, 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 Open Type n’avaient pas le type spécifié 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 @odata.type avec la valeur microsoft.graph.plannerAssignment.
  • Le format des valeurs d’indicateur d’ordre n’était pas correct. Par exemple, une valeur d’indicateur de commande a été 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 retourne également le 403 code d’état lorsqu’une limite définie par le service est dépassée. Si c’est le cas, la propriété de code sur le type de ressource d’erreur indique le type de la limite dépassée par la requête. 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é. La propriété conteneur de la ressource plannerPlan détermine cette limite.
MaximumProjectsSharedWithUser Le nombre maximal de plans partagés avec une limite d’utilisateurs a été dépassé. La propriété sharedWith sur la ressource plannerPlanDetails détermine cette limite.
MaximumTasksCreatedByUser Le nombre maximal de tâches créées par une limite d’utilisateur a été dépassé. La propriété createdBy sur la ressource plannerTask détermine cette limite.
MaximumTasksAssignedToUser Le nombre maximal de tâches affectées à une limite d’utilisateurs a été dépassé. La propriété assignments sur la ressource plannerTask détermine cette limite.
MaximumTasksInProject Le nombre maximal de tâches dans une limite de plan a été dépassé. La propriété planId sur la ressource plannerTask détermine cette limite.
MaximumActiveTasksInProject Le nombre maximal de tâches qui ne sont pas terminées dans une limite de plan a été dépassé. Les propriétés planId et percentComplete de la ressource plannerTask déterminent cette limite.
MaximumBucketsInProject Le nombre maximal de compartiments dans une limite de plan a été dépassé. La propriété planId de la ressource plannerBucket détermine cette limite.
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.
MaximumFavoritePlansForUser La propriété favoritePlanReferences sur la ressource plannerUser contient trop de valeurs.
MaximumRecentPlansForUser La propriété recentPlanReferences sur la ressource plannerUser contient trop de valeurs.
MaximumContextsOnPlan La propriété contextuelle de la ressource sur le plannerPlan contient trop de valeurs.

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.