Использование REST API Планировщика

Статья
03/06/2024

API Планировщика в Microsoft Graph можно использовать для создания задач и назначения их пользователям в группе Microsoft 365.

Перед началом работы с API Планировщика изучите, как основные объекты связаны друг с другом и группами Microsoft 365.

Контейнеры плана

В Планировщике (Майкрософт) планы всегда содержатся в другом ресурсе. Содержащий их ресурс определяет правила авторизации плана и все задачи в нем, а также жизненный цикл плана. Например, для планов, содержащихся в группах Microsoft 365, участники группы смогут создавать, изменять, разрешать и удалять задачи в плане, а также изменять некоторые свойства на уровне плана, такие как имя плана и названия меток. Кроме того, при удалении группы автоматически удаляются все планы из нее, а если группа восстанавливается, все планы будут автоматически восстановлены.

Самый распространенный тип контейнера — группа Microsoft 365.

Тип контейнера: группы Microsoft 365

Планы обычно содержатся в группах Microsoft 365 в API Планировщика. Чтобы получить планы, принадлежащие группе, выполните HTTP-запрос, описанный ниже.

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

При создании плана настройте свойство container объекта плана, чтобы сделать группу его контейнером. Планы должны содержаться в поддерживаемом ресурсе.

Примечание. Пользователь, создающий план, должен быть участником группы, в которой будет содержаться план. При создании группы с помощью средства создания группы вы не становитесь ее участником. После создания группы добавьте себя в качестве участника с помощью операции добавления участников группы.

Планы

Планы представляют собой контейнеры задач. Чтобы создать задачу в плане, при ее создании укажите идентификатор плана в качестве свойства planId объекта задачи. В настоящее время невозможно создавать задачи без планов. Чтобы получить задачи в плане, выполните HTTP-запрос, описанный ниже.

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

Задачи

Каждую задачу можно назначить пользователю, добавив назначение в свойство assignments объекта задачи. Идентификатор пользователя, назначаемого задаче, — это имя открытого свойства в назначениях, а свойство orderHint в назначении должно быть указано.

Данные задач и плана

Ресурсы планировщика упорядочены по базовым объектам и объектам сведений. Базовые объекты предоставляют доступ к общим свойствам ресурсов, подходящим для представлений списка, а объекты подробных сведений предоставляют доступ к большим свойствам ресурсов, подходящим для представлений детализации.

Визуализация

Помимо данных задач и плана, API Планировщика предоставляет ресурсы для создания общей визуализации данных по клиентам. Для задач доступны несколько типов визуализации данных, как представлено в таблице ниже.

Способ представления задач	Источник информации для упорядочивания задач
Простой список (задачи в плане)	Свойство orderHint задач
Простой список (задачи, назначенные пользователю)	Свойство assigneePriority задач
Доска со столбцами для исполнителей (доска задач "Кому назначено")	Объект assignedToTaskBoardTaskFormat
Доска со столбцами для хода выполнения задачи (доска задач "Ход выполнения")	Объект progressTaskBoardTaskFormat
Доска с настраиваемыми столбцами задач (доска задач "Сегменты"):	Объект bucketTaskBoardTaskFormat

Настраиваемые столбцы на доске задач "Сегменты" представлены объектами bucket, а их порядок — свойством orderHint объекта.

Принципы упорядочивания описаны в статье Использование указаний по упорядочиванию в Планировщике.

Версии ресурсов в Планировщике

Планировщик управляет версиями ресурсов с помощью тегов etag. Эти теги etag возвращаются со свойством @odata.etag для каждого ресурса. Для запросов PATCH и DELETE требуется последний тег etag, известный клиенту, чтобы указать его в заголовке If-Match. Планировщик позволяет изменять старые версии ресурсов, если планируемое изменение не конфликтует с более новыми изменениями, принятыми службой Планировщика в том же ресурсе. Клиенты могут определить, какой тег etag ресурса новее, вычислив большее значение тега etag при сравнении порядкового номера строки. У каждого ресурса есть уникальный тег etag. Невозможно сравнить значения тегов etag для разных ресурсов, в том числе с отношениями вложения. Клиентские приложения должны обрабатывать коды409 ошибок, связанных с управлением версиями, считывая 412 последнюю версию элемента и устраняя конфликтующие изменения.

Основные ошибки Планировщика

В дополнение к общим ошибкам Microsoft Graph, некоторые ошибки относятся только к API Планировщика.

400 (неправильный запрос)

В некоторых типовых сценариях на запросы POST и PATCH может быть получен код состояния 400. Ниже приведено несколько распространенных причин.

Свойства Open Type не относятся к правильным типам, тип не указан или не содержит никаких свойств. Например, свойства plannerAssignment со сложными значениями должны объявлять свойство @odata.type со значением microsoft.graph.plannerAssignment.
Значения указаний порядка имеют неправильный формат. Например, значение подсказки заказа задается непосредственно для значения, возвращаемого клиенту.
Данные логически несогласованны. Например, дата начала задачи позже даты выполнения задачи.

403 (доступ запрещен)

Помимо общих ошибок, API Планировщика возвращает код состояния 403, если превышено ограничение, определенное в службе. Тип ограничения, превышенного в запросе, будет указан в свойстве code типа ресурса с ошибкой. Дополнительные сведения об ограничениях см. в разделе Ограничения Планировщика . Ниже перечислены возможные значения для типов ограничений.

Значение	Описание
MaximumProjectsOwnedByUser	Превышено максимальное количество планов, содержащихся в группе. Это ограничение применяется к планам, содержащимся в группе, на основе свойства container ресурса plannerPlan.
MaximumProjectsSharedWithUser	Превышено максимальное количество планов, совместно используемых с ограничением пользователей. Это ограничение основано на свойстве sharedWith ресурса plannerPlanDetails .
MaximumTasksCreatedByUser	Превышено максимальное число задач, созданных в результате ограничения пользователей. Это ограничение основано на свойстве createdBy ресурса plannerTask .
MaximumTasksAssignedToUser	Превышено максимальное число задач, назначенных пользователю. Это ограничение основано на свойстве assignments ресурса plannerTask .
MaximumTasksInProject	Превышено максимальное число задач в пределах плана. Это ограничение основано на свойстве planId ресурса plannerTask .
MaximumActiveTasksInProject	Превышено максимальное число задач, не выполненных в рамках плана. Это ограничение основано на свойствах planId и percentComplete ресурса plannerTask .
MaximumBucketsInProject	Превышено максимальное количество контейнеров в рамках плана. Это ограничение основано на свойстве planId ресурса plannerBucket .
MaximumUsersSharedWithProject	Свойство sharedWith ресурса plannerPlanDetails содержит слишком много значений.
MaximumReferencesOnTask	Свойство references ресурса plannerTaskDetails содержит слишком много значений.
MaximumChecklistItemsOnTask	Свойство checklist ресурса plannerTaskDetails содержит слишком много значений.
MaximumAssigneesInTasks	Свойство assignments ресурса plannerTask содержит слишком много значений.
MaximumPlannerPlans	Группа уже содержит максимальное количество планов, принадлежащих пользователю, которое в настоящее время составляет 200. Дополнительные сведения об ограничениях см. в разделе Ограничения Планировщика.

412 (необходимое условие не выполнено)

Во всех запросах POST, PATCH и DELETE API Планировщика заголовок If-Match необходимо указывать с последним известным значением тега etag ресурса. Код состояния 412 также может быть возвращен, если значение тега etag, указанное в запросе, больше не соответствует версии ресурса в службе. В этом случае клиентам следует прочитать ресурс еще раз и получить новый тег etag.

Поделиться через