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

Настройка повторения задач в Планировщике (предварительная версия)

  • Статья

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

Пользовательские сценарии

Поддерживаются следующие сценарии:

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

  • Измените расписание повторения для существующего повторяющегося ряда.

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

  • Завершите ряд следующими ами:

    • Удаление активной задачи из ряда (и выбор да , чтобы завершить ряд).
    • Прекращение ряда без удаления активной задачи.

  • Возродить серию. Если повторение было завершено, необходимо восстановить ряд.

Концептуальные различия между повторяющимися собраниями и повторяющимися задачами

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

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

Отчет и связанная с ним задача предоставляются каждые 2 недели в пятницу; серия началась 14 мая 2021 года. Первый доклад ожидается в эту дату, пятницу, 14 мая. Перемежем до 7 января 2022 г., через 34 недели. Человек, который делал отчеты, взял некоторое время отгула в декабре, и никто не завершил отчеты. Текущая повторяющаяся задача (и соответствующий отчет) должна состояться 10 декабря. Отчет и связанная с ним задача просрочены на 4 недели.

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

Если расписание повторения не изменено и задача 10 декабря помечена как завершенная, то для следующей задачи для серии создается экземпляр с датой выполнения 24 декабря.

Однако предположим, что принято решение о том, что в будущем этот доклад следует делать каждые 3 недели, а не каждые 2 недели. Решение может даже заключаться в том, что 3-недельная периодичность должна быть ретроактивной для просроченных отчетов. Это изменение предлагает различные возможные варианты определения продолжения ряда:

  • Следует ли изменить дату 10 декабря?
  • Когда должна быть поставлена следующая задача?

Ниже приведено текущее состояние повторяющейся задачи и решение.

  • Текущая задача имеет дату выполнения — 10 декабря 2021 г.
  • Предыдущая задача должна была быть выполнена 26 ноября 2021 г.
  • Принимается решение изменить периодичность с 2 недель на 3 недели; изменение применяется задним числом к просроченной отчетности.

Учитывая контекст, возможны два варианта, и оба являются допустимыми историями клиентов о том, как можно изменить серию в соответствии с новой 3-недельной периодичностью.

Вариант 1. Измените задачу 10 декабря, чтобы она была просрочена через 3 недели после предыдущей задачи 26 ноября. Срок выполнения текущей задачи изменен на 17 декабря, а следующая задача — 7 января.

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

Планировщик поддерживает оба этих варианта. Сегодняшняя дата не учитывает, как обрабатываются эти различные случаи. Этот пример рассматривается далее в примере 1. Изменение шаблона с помощью и без изменений в patternStartDateTime.

Определения

Для обсуждения и описания задач Планировщика с повторением используются следующие термины:

Определение задачи с активным повторением

Если выполняются следующие три условия, plannerTask имеет активное повторение:

  • Свойство percentComplete имеет значение меньше 100.
  • recurrence.nextInSeriesTaskId имеет null значение или undefined.
  • recurrence.schedule содержит допустимый plannerRecurrenceSchedule с значением nextOccurrenceDateTime, не имеющим значения NULL.

Задача с активным повторением (назовите ее задачей A) может активировать механизм повторения службы, которая создает новую задачу (задачу Б) для продолжения повторяющегося ряда. В этом случае задача A имеет значение recurrence.nextInSeriesTaskId , для которого задан идентификатор задачи B. Так как задача A больше не соответствует условию 2, она больше не имеет активного повторения. Задача A никогда не может иметь активное повторение , так как nextInSeriesTaskId является свойством только для чтения, и служба никогда не удаляет его значение.

Определение ряда повторений

Ряд повторений (также известный как повторяющийся ряд) — это последовательный ряд задач. Серия начинается при первом определении повторения для одной задачи и продолжается автоматическое создание новых задач с тем же идентификатором recurrence.seriesId.

  • Задачи, совместно использующие один и тот же параметр recurrence.seriesId , относятся к одному и тому же ряду повторений.
  • Каждая задача в серии имеет отдельный идентификатор recurrence.occurenceId.
  • Первая задача в серии имеет значение occurrenceId1.
  • Если первая задача активируется механизмом повторения (помечается как завершенная или удаленная, а она имеет активное повторение), то вторая задача создается с идентификатором occurenceId .2 Этот процесс продолжается до тех пор, пока ряд повторений не завершится.

Избегание неоднозначного термина повторяющейся задачи

В обычной речи термин повторяющаяся задача иногда относится к уникальной задаче с активным повторением в ряде; и иногда ссылается на сам ряд повторений или все задачи в цикле повторений. Эта неоднозначность распространена в устном английском языке: точно так же еженедельный отчет может ссылаться на один экземпляр отчета или на повторяющуюся ответственность за выполнение отчета каждую неделю. Из-за этой неоднозначности использование термина "повторяющаяся задача " избегается; Вместо этого предпочтителен один из следующих терминов: задача с активным повторением или ряд повторений.

Сведения о типе ресурса

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

plannerRecurrenceSchedule

PlannerRecurrenceSchedule инкапсулирует определение шаблона повторения (pattern), начальную дату для этого шаблона (patternStartDateTime) и созданное системой свойство, указывающее дату следующего вхождения (nextOccurrenceDateTime).

Шаблон является повторениемPattern; Дополнительные сведения см. в примечаниях, относящихся к планировщику, о повторенииPattern.

ШаблонStartDateTime указывает начальную дату и время ряда в качестве значения DateTimeOffset. Значение, отличное от NULL, должно присваиваться patternStartDateTime всякий раз, когда используется свойство pattern ; В настоящее время это единственный способ определения повторения. Клиенты, как правило, должны переназначить это значение, когда они вносят изменения в recurrence.schedule.pattern , чтобы указать дату начала нового шаблона; Однако если клиенты не включают значение, служба продолжает серию, используя значение по умолчанию, основанное на расписании. Дополнительные сведения см. в следующих примечаниях и пояснениях.

NextOccurrenceDateTime — это созданное системой поле только для чтения. Он предоставляет вычисляемую службу дату, которая используется в качестве dueDateTime для следующего plannerTask в серии. NextOccurrenceDateTime вычисляется на основе шаблона вместе с patternStartDateTime или значением привязки, которое отслеживает первоначально запланированную дату заданной задачи.

Заметка: Планировщик в настоящее время не использует тип ресурса recurrenceRange .

Заметки, относящиеся к планировщику, о повторенииPattern

Ниже приведены ограничения, относящиеся к Планировщику, для recurrencePattern:

  • relativeMonthly и relativeYearly шаблоны могут не указывать более одного дня для daysOfWeek.
  • Для weekly шаблонов, если daysOfWeek содержит более одного дня, интервал должен иметь значение 1.

Пояснения по поводу повторенияPattern:

  • При изменении любого свойства в файле recurrencePattern необходимо указать все соответствующие свойства шаблона. Например, шаблон с типом = daily и интервалом = 1 не может быть исправлен только с интервалом = 2400 Bad Request; в противном случае служба возвращает код ответа. Также необходимо указать свойство type = daily , даже если тип не меняется. Это нормальное поведение для типа ресурса recurrencePattern , хотя некоторые другие свойства Планировщика работают иначе.

  • Неиспользуемые свойства автоматически присваиваются значению по умолчанию.

    • Например, свойство month используется только для годовых шаблонов с допустимыми значениями от 1 до 12. dailyОднако шаблоны , weeklyи monthly назначены 0 свойству month, так как 0 является значением по умолчанию для целочисленного значения.
    • Свойства перечисления, включая firstDayOfWeek и index, получают значения по умолчанию, соответствующие первому значению перечисления: sunday и firstсоответственно.

  • Для absoluteMonthly шаблонов, если выбранный dayOfMonth не существует в конкретном месяце, заменяется последний день месяца.

    • Пример: если значение dayOfMonth — и 31 вы повторяете апрель, выбранная дата — 30 апреля.
    • Пример: если аргумент dayOfMonth имеет значение 29, 30или 31 и вы повторяете для февраля, выбранная дата — последний день февраля.

  • Аналогичным образом, для absoluteYearly шаблонов с месяцем = 2 и днемOfMonth = 29 выбранная дата в високосных годах — 28 февраля.

  • Для weekly шаблонов свойство firstDayOfWeek используется для различения того, что рассматривается на этой неделе , и того, что будет рассматриваться на следующей неделе. Это актуально при измененииweekly шаблона. Следующая задача запланирована на следующую неделю, а firstDayOfWeek определяет, когда начнется следующая неделя.

Примеры того, как firstDayOfWeek влияет на изменения еженедельного шаблона

Задана задача с активным повторением со следующими свойствами:

  • Это происходит еженедельно каждую среду: шаблон имеет тип = weekly, интервал = 1, daysOfWeek = [wednesday], и firstDayOfWeek = sunday
  • DueDateTime — среда 2/2
  • СледующийOccurrenceDateTime — среда 2/9

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

Изменение шаблона Результат nextOccurrenceDateTime
Еженедельно каждый вторник Вторник 2/8
Еженедельно каждый четверг Четверг 2/10
Еженедельно каждый четверг и firstDayOfWeek изменяется на четверг Четверг 2/3

Обратите внимание на разницу четверг 2/10 против четверга 2/3. При firstDayOfWeek = Thursday четверг 2/3 не в ту же неделю , что и среда 2/2, так как новая неделя начинается в четверг; если первый ДеньOfWeek не Thursdayявляется , то четверг 2/3 находится в той же неделе , что и среда 2/2, а четверг 2/10 — на следующей неделе.

Примечания о расписании и дате выполнения

DueDateTime может быть изменен клиентами, чтобы иметь другое значение (включая null), не влияя на расписание и nextOccurrenceDateTime. Например, если задача опаздывает, а дата выполнения изменена в соответствии с этой задержкой, следующая задача в серии отображается как первоначально запланированная, если шаблон и (или) шаблонStartDateTime явно не обновлены. Таким образом, откладывание срока выполнения не приводит к пропуску дат в соответствии с заданным расписанием. Это отличается от модели собрания , где сегодняшняя дата играет роль при определении времени следующего собрания. Знание сегодняшней даты важно для вычисления даты следующего собрания или события, но оно не относится к расчету следующей даты выполнения задачи.

Пример 1. Изменение шаблона с помощью и без изменений в patternStartDateTime

Задана задача с активным повторением со следующими свойствами:

  • Шаблон повторения указывает каждые 2 недели в пятницу, например тип = weekly, интервал = 2, daysOfWeek = [friday], и firstDayOfWeek = sunday.
  • Предыдущая задача должна была быть выполнена 26 ноября 2021 г.
  • Текущая задача должна быть поставлена 10 декабря 2021 г.
  • Следующий ПараметрOccurrenceDateTime — 24 декабря 2021 г. (через две недели после текущей даты выполнения).

Принимается решение изменить периодичность с 2 недель на 3 недели. Таким образом, шаблон изменяется, чтобы иметь интервал = 3 вместе с одинаковыми значениями для еженедельно по пятницам.

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

Описание изменений Результат nextOccurrenceDateTime
Измените шаблонStartDateTime на 10 декабря 2021 г. 31 декабря 2021 г.
Измените шаблонStartDateTime на 17 декабря 2021 г. 7 января 2022 г.
Не изменяйте шаблонStartDateTime 31 декабря 2021 г.

В первом примере параметр patternStartDateTime имеет то же значение, что и dueDateTime, например 10 декабря. Параметр nextOccurrenceDateTime имеет значение 3 недели после patternStartDateTime, то есть 31 декабря. Концептуально это изменение представляет собой изменение частоты, которое действует только для следующей задачи, а не для этой задачи.

Во втором примере параметр patternStartDateTime имеет значение 3 недели после 26 ноября, то есть 17 декабря. Опять же, параметр nextOccurrenceDateTime имеет значение 3 недели после шаблонаStartDateTime, на этот раз 7 января. Концептуально это изменение срока действия с 26 ноября (предыдущая задача), а не с 10 декабря (исходная дата выполнения текущей задачи).

Обычно рекомендуется изменить значение dueDateTime задачи, чтобы он совпадал с новым шаблономStartDateTime; однако это не обязательно. Если dueDateTime не изменяется вместе с шаблономStartDateTime во втором примере, пользователи по-прежнему видят дату выполнения текущей задачи 10 декабря. После ее завершения следующая задача в серии запланирована на 7 января. Так как это может привести к путанице для пользователей, рекомендуется совместно назначить dueDateTime и patternStartDateTime .

Третий пример аналогичен первому, за исключением того, что в нем не указан шаблонStartDateTime. ШаблонStartDateTime, который имеет длинную обратную сторону, например в августе, нельзя использовать. В этом случае значение nextOccurrenceDateTime вычисляется на основе исходной даты выполнения 10 декабря, что приводит к nextOccurrenceDateTime 31 декабря, аналогично первому примеру. Обратите внимание, что исходная дата выполнения не предоставляется, хотя она используется в этом вычислении. Это означает, что dueDateTime можно изменить на другое значение или даже изменить на nullзначение , но значение dueDateTime игнорируется для этого вычисления, используя вместо него исходную дату выполнения. Это еще одна причина, по которой рекомендуется изменить dueDateTime и patternStartDateTime вместе.

Пример 2. Дата выполнения не влияет на следующее вхождение

Задана задача с активным повторением со следующими свойствами:

  • Это происходит еженедельно каждую среду: шаблон имеет тип = weekly, интервал = 1, daysOfWeek = [wednesday], и firstDayOfWeek = sunday.
  • DueDateTime — ср 2/16.
  • СледующийOccurrenceDateTime — СР 2/9.
  • Исходная дата выполнения — среда 2/2. Это значение не является общедоступным, хотя его можно вывести из nextOccurrenceDateTime.

Ниже приводится изучение трех возможных изменений.

Изменение Результат nextOccurrenceDateTime
Без изменений Вторник 2/9
шаблон изменяется на еженедельный каждый четверг; нет изменений в шаблонеStartDateTime Четверг 2/10
patternStartDateTime изменено на 2/9; нет изменений в шаблоне Среда 2/16

Во всех трех примерах dueDateTime не изменяется с измененного значения среды 2/16, а следующая задача в серии создается с dueDateTime , равным nextOccurrenceDateTime в предыдущей таблице.

Примечание.

  • Поведение по умолчанию, когда patternStartDateTime не переназначается явным образом, заключается в том, что расписание продолжается на основе исходной даты выполнения. В этом случае исходная дата выполнения — 2/2, а текущая дата dueDateTime — 16.02.
  • Если шаблонStartDateTime изменен, nextOccurrenceDateTime пересчитывается с использованием этой новой даты начала.
  • Если дата выполнения будет изменена на null 2/16 или на любую другую дату в будущем или прошлом, предыдущие примеры не будут затронуты.

Сценарии разработчика

Создание повторяющейся серии

Recurrence.schedule — это единственное редактируемое клиентом подсредактируемое свойство повторения. Добавив recurrence.schedule (независимо от того, определен ли повторение уже), клиенты могут изменить неповторяющуюся задачу на задачу с активным повторением.

Два других условия, упомянутые в определении активного повторения , влияют на возможность добавления recurrence.schedule :

  • Свойство percentComplete должно быть меньше 100.
  • Свойство recurrence.nextInSeriesTaskId должно быть null или не назначено.

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

Повторение триггера

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

В предыдущем определении для _task с активным повторением, если какое-либо из трех условий не выполняется, механизм повторения не активируется (новая задача не создается и nextInSeriesTaskId не назначается).)

Создание экземпляра новой задачи обычно происходит немедленно, что иногда приводит к задержке при создании новой задачи.

Новая задача имеет следующие свойства, скопированные из уже завершенной задачи: заголовок, описание, элементы контрольного списка (для неполных), назначения, приоритет и категории. Параметр percentComplete новой задачи имеет значение 0. DueDateTime новой задачи устанавливается в соответствии с расписанием повторения. Копируются следующие вложенные свойства повторения: seriesId, recurrenceStartDateTime и schedule; schedule.nextOccurrenceDateTime вычисляется для новой задачи. Другим свойствам повторения присваиваются соответствующие значения для новой задачи.

Обнаружение следующей задачи в серии

Если задача C имеет определенное повторение и пользователь помечает задачу C завершенной (percentComplete = 100), то для продолжения ряда повторений создается задача D . Задача C имеет свое свойство recurrence.nextInSeriesTaskId , заполненное идентификатором задачи D.

С другой стороны, если задача C удаляется, а удаление вызывает повторение, клиент должен обнаружить идентификатор задачи D другими способами. Например, запрашивая задачи в том же контейнере или потребляя разностный канал синхронизации.

Изменение повторяющегося ряда

Для задачи с активным повторением может быть изменено расписание повторения. Обратите внимание, что recurrence.schedule является единственным вложенным свойством повторения, которое можно изменить.

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

Завершение повторяющегося ряда

Чтобы завершить повторяющийся ряд, присвойте свойству recurrence.schedule значение null. Это можно сделать только в том случае, если параметр nextInSeriesTaskId или null не назначен.

Возобновление повторения после завершения

После удаления recurrence.schedule можно добавить новое значение recurrence.schedule в задачу, которая восстанавливает серию.

Выполните предыдущие действия в разделе Создание повторяющегося ряда. Применяются те же ограничения. Исходный идентификатор recurrence.seriesId и другие вложенные свойства повторения не изменяются, фактически восстанавливая или продолжая исходный ряд.

Определение задачи с активным повторением в ряде повторений

С учетом параметра recurrence.seriesIdактивная повторение может иметь не более одной задачи с этим seriesId.

Завершенные задачи скрыты от большинства представлений. Пользователь редко просматривает задачу, которая помечена как завершенная. Удаленные задачи не могут быть просмотрированы. Это означает, что в большинстве случаев в ряде повторений существует только одна задача с активным повторением. Если задача с активным повторением деактивирована с помощью расписания, то задачи с активным повторением в этом ряду не существуют.

Редкие исключительные сценарии

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

Причины

Ниже показаны две возможные причины, по-видимому, не синхронизированные сведения.

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

  • Механизм повторения столкнулся с временным сбоем. Это означает, что новая задача для продолжения ряда еще не создана. Обычно он создается в течение нескольких секунд или минут.

Две задачи с активным повторением в одной серии повторений

Если клиент наблюдает две задачи с активным повторением в одном и том же ряду повторений, можно предположить, что для задачи с меньшим значением occurrenceId уже активирован механизм повторения. Серверное хранилище Планировщика имеет следующий наборInSeriesTaskId , но эта информация еще не достигла быстрого клиентского хранилища. Задача с большим значением occurrenceId — это уникальная задача с активным повторением.

Задача с активным повторением имеет меньшее значение occurrenceId, чем другая в том же ряде повторений.

Как и в случае с предыдущими "двумя задачами с активным повторением", эта вторая ситуация может наблюдаться, если задача с большим параметром occurrenceId отключена (recurrence.schedule = null). Существование задачи с большим значением occurrenceId подразумевает, что все задачи с меньшим значением occurrenceId в этом ряду не имеют активного повторения, даже если задача с большим значением occurrenceId не имеет активного повторения .

Ноль задач с активным повторением в ряде

Это действительно неоднозначная ситуация, так как может быть одно из следующих вариантов:

  • Механизм повторения был отложен из-за временного сбоя; она будет повторна.
  • Механизм повторения завершился успешно, но новая задача еще не добавлена в быстрое клиентское хранилище.
  • Новая задача была создана, но затем она была удалена другим клиентом.

Первые два состояния — это временные состояния, которые гарантированно будут исправлены службой, как правило, в течение нескольких секунд или минут. Третий, как правило, является постоянным. Вероятно, неточно описать этот сценарий как редкий или исключительный; однако было описано ранее, чтобы привлечь внимание к тому факту, что наблюдается неоднозначность в наблюдаемом состоянии из-за возможности первых двух случаев.

Поиск всех задач в повторяющейся серии

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

Свойство recurrence.seriesId для каждого plannerTask — это идентификатор, который отличается от определенного повторяющегося ряда , к которому принадлежит одна или несколько задач. При назначении это значение никогда не может измениться. Recurrence.occurrenceId — это целочисленное значение, указывающее порядок задач в ряду. Первой задаче в ряду (задаче, в которой впервые добавлено повторение) присваивается значение occurrenceId .1

Примечание.

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

Примеры операций REST

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

Добавление даты выполнения и повторения в существующий планировщикTask

В следующем примере запроса и ответа показано, как повторяться с задачей. Задача с идентификатором Q7SNdWp5ekeJTpRRSCcZ3pUAD6kV уже существует и имеет повторение = null. Чтобы добавить повторение, необходимо назначить необходимые свойства recurrence.schedule. Неиспользуемые свойства recurrencePattern (month, dayOfMonth, firstDayOFWeek и index) не следует включать.

Запрос

PATCH https://graph.microsoft.com/beta/planner/tasks/Q7SNdWp5ekeJTpRRSCcZ3pUAD6kV

{
    "recurrence": {
        "schedule": {
            "pattern": {
                "type": "daily",
                "interval": 2
            },
            "patternStartDateTime": "2021-11-13T10:30:00Z"
        }
    },
    "dueDateTime": "2021-11-13T10:30:00Z"
}

Отклик

HTTP/1.1 204 NO CONTENT

Получение предыдущей задачи

В следующем примере запроса и ответа показано, как получить задачу с новым повторением.

Запрос

GET https://graph.microsoft.com/beta/planner/tasks/Q7SNdWp5ekeJTpRRSCcZ3pUAD6kV

Отклик

Ниже приведены заметки об ответе:

  • Неиспользуемым свойствам recurrencePattern (month, dayOfMonth, firstDayOFWeek и index) служба присваивает значения по умолчанию.
  • NextOccurrenceDateTime вычисляется по расписанию. В этом случае patternStartDateTime — 13 ноября, и шаблон определяет каждый другой день; это дает значение nextOccurrenceDateTime через два дня после шаблонаStartDateTime, то есть 15 ноября.
  • SeriesId и occurrenceId создаются автоматически. SeriesId — это новый GUID, закодированный в формате идентификатора Планировщика. Так как это первая задача в ряде, она получает значение occurrenceId .1
  • Параметру recurrenceStartDateTime присваивается то же значение, что и patternStartDateTime. Это верно для первой задачи в ряду (occurrenceId = 1). Однако для будущих задач в ряду значение recurrenceStartDateTime не меняется, даже если изменится шаблонStartDateTime . он отслеживает начало повторения, в отличие от изменений шаблона.
  • Параметр previousInSeriesTaskId всегда nullимеет значение , так как это первая задача в серии (occurrenceId = 1).
  • NextInSeriesTaskId назначается, если и когда создается следующая задача для продолжения ряда.
HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#planner/tasks/$entity",
    "@odata.etag": "W/\"JzEtVGFzayAgQEBAQEBAQEBAQEBAQEBASCc=\"",
    "planId": "4CaQUsrKXkyMDBhpF9cu-JUAAZ1V",
    "bucketId": "mVAeurfATUOEkpxi-60a9pUAJDxm",
    "title": "Water the plants",
    "orderHint": "8586352620867692777",
    "assigneePriority": "",
    "percentComplete": 0,
    "priority": 5,
    "startDate": null,
    "createdDateTime": "2019-08-20T23:46:38.708303Z",
    "hasDescription": false,
    "previewType": "automatic",
    "completedDateTime": null,
    "completedBy": null,
    "referenceCount": 0,
    "checklistItemCount": 0,
    "activeChecklistItemCount": 0,
    "conversationThreadId": null,
    "id": "Q7SNdWp5ekeJTpRRSCcZ3pUAD6kV",
    "createdBy": {
        "user": {
            "displayName": null,
            "id": "edcfc4b0-be77-4866-948a-b93267e151f8"
        }
    },
    "appliedCategories": {},
    "assignments": {},
    "recurrence": {
        "seriesId": "w5tLb5HceUmpuiYlhdXyHg",
        "occurrenceId": 1,
        "previousInSeriesTaskId": null,
        "nextInSeriesTaskId": null,
        "recurrenceStartDateTime": "2021-11-13T10:30:00Z",
        "schedule": {
            "patternStartDateTime": "2021-11-13T10:30:00Z",
            "nextOccurrenceDateTime": "2021-11-15T10:30:00Z",
            "pattern": {
                "type": "daily",
                "interval": 2,
                "firstDayOfWeek": "sunday",
                "dayOfMonth": 0,
                "daysOfWeek": [],
                "index": "first",
                "month": 0
            }
        }
    },
    "dueDateTime": "2021-11-13T10:30:00Z",
    "creationSource": null
}

Пометка задачи завершена, активируя повторение (1-я задача в серии)

В следующем примере запроса и ответа показано, как задать значение percentComplete100 (также называется завершение задачи или пометка задачи завершена).

Запрос

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

PATCH https://graph.microsoft.com/beta/planner/tasks/Q7SNdWp5ekeJTpRRSCcZ3pUAD6kV

{
    "percentComplete": 100
}

Отклик

HTTP/1.1 204 NO CONTENT

Получение завершенной задачи и обнаружение идентификатора следующей (второй) задачи в серии

В следующем примере запроса и ответа показано, как получить задачу после ее завершения.

Запрос

GET https://graph.microsoft.com/beta/planner/tasks/Q7SNdWp5ekeJTpRRSCcZ3pUAD6kV

Отклик

Ниже показан пример запроса. Так как назначен параметр nextInSeriesTaskId , для этой задачи больше не может быть настроено активное повторение .

HTTP/1.1 200 OK
Content-type: application/json

{
    "_comment": "other fields omitted for brevity",
    "percentComplete": 100,
    "recurrence": {
        "seriesId": "w5tLb5HceUmpuiYlhdXyHg",
        "occurrenceId": 1,
        "previousInSeriesTaskId": null,
        "nextInSeriesTaskId": "GxOo0ms1iEu3eBI1-6lk85UAI5FI",
        "recurrenceStartDateTime": "2021-11-13T10:30:00Z",
        "schedule": {
            "patternStartDateTime": "2021-11-13T10:30:00Z",
            "nextOccurrenceDateTime": "2021-11-15T10:30:00Z",
            "pattern": {
                "type": "daily",
                "interval": 2,
                "firstDayOfWeek": "sunday",
                "dayOfMonth": 0,
                "daysOfWeek": [],
                "index": "first",
                "month": 0
            }
        }
    },
    "dueDateTime": "2021-11-13T10:30:00Z",
}

Получение новой задачи в серии (2-е вхождение)

В следующем примере запроса и ответа показано, как получить новую задачу в серии, идентификатор которой был обнаружен из nextInSeriesTaskId в предыдущем ответе.

Запрос

Пример запроса (GxOo0ms1iEu3eBI1-6lk85UAI5FI) содержит следующие отличия по сравнению с предыдущим примером (Q7SNdWp5ekeJTpRRSCcZ3pUAD6kV):

  • dueDateTime было присвоено значение из предыдущей задачи nextOccurrenceDateTime .
  • nextOccurrenceDateTime вычисляется по расписанию: следующее вхождение после предыдущего dueDateTime.
  • occurrenceId — это 2 , а не 1
  • percentComplete имеет значение 0.
GET https://graph.microsoft.com/beta/planner/tasks/GxOo0ms1iEu3eBI1-6lk85UAI5FI

Отклик

HTTP/1.1 200 OK
Content-type: application/json

{
    "_comment": "other fields omitted for brevity",
    "planId": "4CaQUsrKXkyMDBhpF9cu-JUAAZ1V",
    "bucketId": "mVAeurfATUOEkpxi-60a9pUAJDxm",
    "title": "Water the plants",
    "percentComplete": 0,
    "id": "GxOo0ms1iEu3eBI1-6lk85UAI5FI",
    "appliedCategories": {},
    "assignments": {},
    "recurrence": {
        "seriesId": "w5tLb5HceUmpuiYlhdXyHg",
        "occurrenceId": 2,
        "previousInSeriesTaskId": "Q7SNdWp5ekeJTpRRSCcZ3pUAD6kV",
        "nextInSeriesTaskId": null,
        "recurrenceStartDateTime": "2021-11-13T10:30:00Z",
        "schedule": {
            "patternStartDateTime": "2021-11-13T10:30:00Z",
            "nextOccurrenceDateTime": "2021-11-17T10:30:00Z",
            "pattern": {
                "type": "daily",
                "interval": 2,
                "firstDayOfWeek": "sunday",
                "dayOfMonth": 0,
                "daysOfWeek": [],
                "index": "first",
                "month": 0
            }
        }
    },
    "dueDateTime": "2021-11-15T10:30:00Z"
}

Измените повторение задачи на один день в неделю и задайте для даты выполнения значение NULL.

В следующем примере запроса и ответа показано, как назначить nulldueDateTime и другой шаблонзадаче с активным повторением.

Запрос

PATCH https://graph.microsoft.com/beta/planner/tasks/GxOo0ms1iEu3eBI1-6lk85UAI5FI

{
    "recurrence": {
        "schedule": {
            "pattern": {
                "type": "weekly",
                "interval": 1,
                "daysOfWeek": [ "tuesday" ],
                "firstDayOfWeek": "sunday"
            }
        }
    },
    "dueDateTime": null
}

Отклик

HTTP/1.1 204 NO CONTENT

Снова получите задачу, чтобы увидеть результат редактирования

В следующем примере запроса и ответа показано, как получить задачу после предыдущих изменений. Вы можете ожидать, что будет отображаться указанная ранее ранее модель recurrence.schedule: еженедельно по вторникам вместе с dueDateTime = null.

Запрос

GET https://graph.microsoft.com/beta/planner/tasks/GxOo0ms1iEu3eBI1-6lk85UAI5FI

Отклик

В следующем примере задача может иметь активное повторение вместе с датой null выполнения. NextOccurrenceDateTime вычисляется повторно и теперь находится 23 ноября, вторник, от daysOfWeek. Это следующее вхождение вычисляется на основе исходного dueDateTime задачи от 15 ноября в понедельник.

HTTP/1.1 200 OK
Content-type: application/json

{
    "_comment": "other fields omitted for brevity",
    "planId": "4CaQUsrKXkyMDBhpF9cu-JUAAZ1V",
    "bucketId": "mVAeurfATUOEkpxi-60a9pUAJDxm",
    "title": "Water the plants",
    "percentComplete": 0,
    "id": "GxOo0ms1iEu3eBI1-6lk85UAI5FI",
    "appliedCategories": {},
    "assignments": {},
    "recurrence": {
        "seriesId": "w5tLb5HceUmpuiYlhdXyHg",
        "occurrenceId": 2,
        "previousInSeriesTaskId": "Q7SNdWp5ekeJTpRRSCcZ3pUAD6kV",
        "nextInSeriesTaskId": null,
        "recurrenceStartDateTime": "2021-11-13T10:30:00Z",
        "schedule": {
            "patternStartDateTime": "2021-11-13T10:30:00Z",
            "nextOccurrenceDateTime": "2021-11-23T10:30:00Z",
            "pattern": {
                "type": "weekly",
                "interval": 1,
                "firstDayOfWeek": "sunday",
                "dayOfMonth": 0,
                "daysOfWeek": [ "tuesday" ],
                "index": "first",
                "month": 0
            }
        }
    },
    "dueDateTime": null
}

Удаление расписания повторения

В следующем примере запроса и ответа показано, как назначить nullфайл recurrence.schedule, тем самым завершив повторение для этой задачи.

Запрос

PATCH https://graph.microsoft.com/beta/planner/tasks/GxOo0ms1iEu3eBI1-6lk85UAI5FI

{
    "recurrence": {
        "schedule": null
    }
}

Отклик

HTTP/1.1 204 NO CONTENT

Получение задачи с удаленным расписанием повторения

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

Запрос

GET https://graph.microsoft.com/beta/planner/tasks/GxOo0ms1iEu3eBI1-6lk85UAI5FI

Отклик

Ниже приведен пример ответа с сохраненными сведениями о ряде повторений (recurrence.schedule = null). Если указано новое расписание, эта задача по-прежнему относится к тому же ряду.

HTTP/1.1 200 OK
Content-type: application/json

{
    "_comment": "other fields omitted for brevity",
    "recurrence": {
        "seriesId": "w5tLb5HceUmpuiYlhdXyHg",
        "occurrenceId": 2,
        "previousInSeriesTaskId": "Q7SNdWp5ekeJTpRRSCcZ3pUAD6kV",
        "nextInSeriesTaskId": null,
        "schedule": null,
        "recurrenceStartDateTime": "2021-11-13T10:30:00Z"
    },
    "dueDateTime": null
}

Случай ошибки: попытка добавить новое расписание повторения без указания шаблонаStartDateTime

В следующем примере запроса и ответа показан недопустимый запрос, попытка добавить новый recurrence.schedule без указания шаблонаStartDateTime.

Запрос

PATCH https://graph.microsoft.com/beta/planner/tasks/GxOo0ms1iEu3eBI1-6lk85UAI5FI

{
    "recurrence": {
        "schedule": {
            "pattern": {
                "type": "daily",
                "interval": 5
            }
        }
    }
}

Отклик

Ниже приведен пример ответа, который показывает ошибку, описывающую проблему. Объект ответа содержит ошибку, так как в сообщении об ошибке должно быть указано, Recurrence.Schedule.PatternStartDateTime а не Recurrence.Schedule.Range. В настоящее время это известная проблема.

HTTP/1.1 400 BAD REQUEST
Content-type: application/json

{
    "error": {
        "code": "",
        "message": "Schema validation has failed. Validation for field 'Recurrence.Schedule.Range', on entity 'Task' has failed: A non-null value must be specified for this field.",
        "innerError": {
            "request-id": "922f7646-513a-4f63-a231-9cf2d7b647cb",
            "date": "2021-06-22T21:37:35"
        }
    }
}

Восстановление повторения задачи путем добавления нового расписания

В следующем примере запроса и ответа показано, как назначить новое значение recurrence.schedule задаче, которая в настоящее время содержит recurrence.schedule = null.

Заметка:DueDateTime не назначается.

Запрос

PATCH https://graph.microsoft.com/beta/planner/tasks/GxOo0ms1iEu3eBI1-6lk85UAI5FI

{
    "recurrence": {
        "schedule": {
            "pattern": {
                "type": "absoluteMonthly",
                "interval": 2,
                "dayOfMonth": 25
            },
            "patternStartDateTime": "2021-11-25T10:30:00Z"
        }
    }
}

Отклик

HTTP/1.1 204 NO CONTENT

Получение задачи с новым расписанием повторения

В следующем примере запроса и ответа показано, как получить задачу с новым расписанием повторения. Свойства повторения (кроме расписания) остаются неизменными, и задача имеет активное повторение, даже если свойство dueDateTime остается null.

Запрос

GET https://graph.microsoft.com/beta/planner/tasks/GxOo0ms1iEu3eBI1-6lk85UAI5FI

Отклик

HTTP/1.1 200 OK
Content-type: application/json

{
    "_comment": "other fields omitted for brevity",
    "planId": "4CaQUsrKXkyMDBhpF9cu-JUAAZ1V",
    "bucketId": "mVAeurfATUOEkpxi-60a9pUAJDxm",
    "title": "Water the plants",
    "percentComplete": 0,
    "id": "GxOo0ms1iEu3eBI1-6lk85UAI5FI",
    "appliedCategories": {},
    "assignments": {},
    "recurrence": {
        "seriesId": "w5tLb5HceUmpuiYlhdXyHg",
        "occurrenceId": 2,
        "previousInSeriesTaskId": "Q7SNdWp5ekeJTpRRSCcZ3pUAD6kV",
        "nextInSeriesTaskId": null,
        "recurrenceStartDateTime": "2021-11-13T10:30:00Z",
        "schedule": {
            "patternStartDateTime": "2021-11-25T10:30:00Z",
            "nextOccurrenceDateTime": "2022-01-25T10:30:00Z",
            "pattern": {
                "type": "absoluteMonthly",
                "interval": 2,
                "firstDayOfWeek": "sunday",
                "dayOfMonth": 25,
                "daysOfWeek": [],
                "index": "first",
                "month": 0
            }
        }
    },
    "dueDateTime": null
}

Случай ошибки: попытка изменить свойство только для чтения

В следующем примере запроса и ответа показан недопустимый запрос, попытка присвоить значение свойству recurrence.seriesId , которое доступно только для чтения.

Запрос

PATCH https://graph.microsoft.com/beta/planner/tasks/GxOo0ms1iEu3eBI1-6lk85UAI5FI

{
    "recurrence": {
        "seriesId": "abc"
    }
}

Отклик

В следующем объекте ответа отображается ошибка, описывающая проблему.

HTTP/1.1 400 BAD REQUEST
Content-type: application/json

{
    "error": {
        "code": "",
        "message": "Invalid recurrence sub-property assignment(s): \"seriesId\".",
        "innerError": {
            "request-id": "922f7646-513a-4f63-a231-9cf2d7b647cb",
            "date": "2021-06-22T21:37:35"
        }
    }
}

Пометьте задачу завершенной, вызвав повторение (2-я задача в серии, с значением NULL dueDateTime)

В следующем примере запроса и ответа показано, как задать значение percentComplete100 (также называется завершение задачи или пометка задачи завершена).

Запрос

Следующий запрос идентичен для задачи с повторением или без нее.

PATCH https://graph.microsoft.com/beta/planner/tasks/GxOo0ms1iEu3eBI1-6lk85UAI5FI

{
    "percentComplete": 100
}

Отклик

HTTP/1.1 204 NO CONTENT

Получение завершенной задачи и обнаружение идентификатора следующей (третьей) задачи в серии

В следующем примере запроса и ответа показано, как получить задачу после ее завершения.

Запрос

GET https://graph.microsoft.com/beta/planner/tasks/GxOo0ms1iEu3eBI1-6lk85UAI5FI

Отклик

HTTP/1.1 200 OK
Content-type: application/json

{
    "_comment": "other fields omitted for brevity",
    "planId": "4CaQUsrKXkyMDBhpF9cu-JUAAZ1V",
    "bucketId": "mVAeurfATUOEkpxi-60a9pUAJDxm",
    "title": "Water the plants",
    "percentComplete": 100,
    "id": "GxOo0ms1iEu3eBI1-6lk85UAI5FI",
    "appliedCategories": {},
    "assignments": {},
    "recurrence": {
        "seriesId": "w5tLb5HceUmpuiYlhdXyHg",
        "occurrenceId": 2,
        "previousInSeriesTaskId": "Q7SNdWp5ekeJTpRRSCcZ3pUAD6kV",
        "nextInSeriesTaskId": "-6zr7XfE6E2JvxCSmE7Wdf8AClON",
        "recurrenceStartDateTime": "2021-11-13T10:30:00Z",
        "schedule": {
            "patternStartDateTime": "2021-11-25T10:30:00Z",
            "nextOccurrenceDateTime": "2022-01-25T10:30:00Z",
            "pattern": {
                "type": "absoluteMonthly",
                "interval": 2,
                "firstDayOfWeek": "sunday",
                "dayOfMonth": 25,
                "daysOfWeek": [],
                "index": "first",
                "month": 0
            }
        }
    },
    "dueDateTime": null
}

Ошибка: попытка удалить расписание повторения, если nextInSeriesTaskId уже назначен

В следующем примере запроса и ответа показан недопустимый запрос, попытка присвоить значение свойству recurrence.schedule после назначения свойства nextInSeriesTaskId .

Запрос

PATCH https://graph.microsoft.com/beta/planner/tasks/Q7SNdWp5ekeJTpRRSCcZ3pUAD6kV

{
    "recurrence": {
        "schedule": null
    }
}

Отклик

В следующем объекте ответа отображается ошибка, описывающая проблему.

HTTP/1.1 400 BAD REQUEST
Content-type: application/json

{
    "error": {
        "code": "",
        "message": "Schema validation has failed. Validation for field 'Recurrence', on entity 'Task' has failed: Cannot add/edit/delete recurrence when the next instance should already be created.",
        "innerError": {
            "request-id": "922f7646-513a-4f63-a231-9cf2d7b647cb",
            "date": "2021-06-22T21:37:35"
        }
    }
}

Получение новой задачи в серии (3-е вхождение)

В следующем примере запроса и ответа показано, как получить новую задачу в серии, идентификатор которой вы обнаружили из nextInSeriesTaskId в предыдущем ответе. DueDateTime было присвоено значению, представленному в предыдущем nextOccurrenceDateTime задачи, даже если предыдущее dueDateTime задачи было null.

Запрос

GET https://graph.microsoft.com/beta/planner/tasks/-6zr7XfE6E2JvxCSmE7Wdf8AClON

Отклик

HTTP/1.1 200 OK
Content-type: application/json

{
    "_comment": "other fields omitted for brevity",
    "planId": "4CaQUsrKXkyMDBhpF9cu-JUAAZ1V",
    "bucketId": "mVAeurfATUOEkpxi-60a9pUAJDxm",
    "title": "Water the plants",
    "percentComplete": 0,
    "id": "-6zr7XfE6E2JvxCSmE7Wdf8AClON",
    "appliedCategories": {},
    "assignments": {},
    "recurrence": {
        "seriesId": "w5tLb5HceUmpuiYlhdXyHg",
        "occurrenceId": 3,
        "previousInSeriesTaskId": "GxOo0ms1iEu3eBI1-6lk85UAI5FI",
        "nextInSeriesTaskId": null,
        "recurrenceStartDateTime": "2021-11-13T10:30:00Z",
        "schedule": {
            "patternStartDateTime": "2021-11-25T10:30:00Z",
            "nextOccurrenceDateTime": "2022-03-25T10:30:00Z",
            "pattern": {
                "type": "absoluteMonthly",
                "interval": 2,
                "firstDayOfWeek": "sunday",
                "dayOfMonth": 25,
                "daysOfWeek": [],
                "index": "first",
                "month": 0
            }
        }
    },
    "dueDateTime": "2022-01-25T10:30:00Z"
}