Использование REST API Планировщика
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.