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

  • Статья

Важно!

API версии /beta в Microsoft Graph могут быть изменены. Использование этих API в производственных приложениях не поддерживается. Чтобы определить, доступен ли API в версии 1.0, используйте селектор версий.

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

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

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

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

Наиболее распространенным типом контейнера является группа.

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

Планы обычно содержатся в группах в API Планировщик.

Члены группы могут создавать, изменять, разрешать и удалять задачи в плане. Члены группы также могут изменять некоторые свойства на уровне плана, например имя плана или имена меток. Кроме того, при удалении группы все планы в ней автоматически удаляются. И наоборот, если группа восстанавливается, все планы восстанавливаются автоматически.

Чтобы получить планы, принадлежащие группе, выполните HTTP-запрос, описанный ниже.

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

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

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

Тип контейнера: User

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

Чтобы создать план в контейнере пользователя, задайте свойство контейнера для объекта плана с типомuser.

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

Кроме того, можно указать URL-адрес пользователя.

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

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

Планы

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

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

Задачи

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

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

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

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

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

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

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

Принципы упорядочения описаны в Планировщик указаниях порядка.

Отслеживание изменений с помощью запроса изменений

Запрос изменений Планировщика поддерживает запрос объектов, на которые подписан пользователь.

Пользователи подписаны на указанные ниже объекты.

Тип ресурса Планировщика Экземпляры подписки
задачи
  • Созданные пользователем
  • Назначенные пользователю
  • Относящиеся к плану, принадлежащему пользователю
  • Содержащиеся в плане, предоставленном пользователю для совместного использования посредством коллекции sharedWith плана
планы
  • Предоставленные пользователю для совместного использования посредством коллекции sharedWith плана
сегменты
  • Содержащиеся в плане, предоставленном пользователю для совместного использования посредством коллекции sharedWith плана

Заполнение кэша объекта для запросов изменений

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

Объекты разностных полезных данных, которые в настоящее время может возвращать разностный запрос Планировщик, имеют следующие типы:

Чтобы получить исходное состояние объектов для заполнения локального кэша, используйте соответствующе методы GET.

Различие между созданием и изменением объекта

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

Приведенные ниже инструкции можно использовать для определения создания объекта:

  • Свойство createdBy отображается во вновь созданных объектах.
  • За созданным объектом plannerTask следует соответствующий объект plannerTaskDetails .
  • За созданным объектом plannerPlan следует соответствующий объект plannerPlanDetails .

Применение

Ожидается, что у вызывающего объекта есть кэш, содержащий объекты подписки. Сведения о заполнении локального кэша объектов подписки см. в статье Заполнение кэша объектов для запросов изменений.

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

  1. Вызывающий объект запускает запрос синхронизации изменений, получая nextLink и пустую коллекцию изменений.
  2. Вызывающий объект должен заполнить кэш объектов для запросов изменений объектами, на которые подписан пользователь, обновив их кэш.
  3. Вызывающий объект переходит по ссылке nextLink, предоставленной в исходном запросе синхронизации изменений, чтобы получить новую ссылку deltaLink для любых изменений с предыдущего этапа.
  4. Вызывающий объект применяет изменения в возвращенном отклике изменений к объектам в кэше.
  5. Вызывающий объект переходит по новой ссылке deltaLink, чтобы получить следующую ссылку deltaLink и изменения с момента создания текущей ссылки deltaLink.
  6. Вызывающий объект применяет изменения (при наличии) и ожидает некоторое время, прежде чем перезапустить предыдущий и текущий шаг.

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

Планировщик управляет версиями ресурсов с помощью тегов 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 код состояния при превышении ограничения, определенного службой. В этом случае свойство кода типа ресурса error указывает тип лимита, превышенного запросом. Ниже перечислены возможные значения для типов ограничений.

Значение Описание
MaximumProjectsOwnedByUser Превышено максимальное количество планов, содержащихся в пределах группы. Это ограничение определяется свойством контейнера ресурса 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 содержит слишком много значений.
MaximumFavoritePlansForUser Свойство favoritePlanReferences ресурса plannerUser содержит слишком много значений.
MaximumRecentPlansForUser Свойство recentPlanReferences ресурса plannerUser содержит слишком много значений.
MaximumContextsOnPlan Свойство contexts ресурса plannerPlan содержит слишком много значений.

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

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