次の方法で共有

Planner でのタスクの繰り返しの構成 (プレビュー)

  • [アーティクル]

この記事では、 Planner タスク で繰り返しを使用して繰り返しタスクの作成を自動化する方法について説明します。 Planner タスクの 繰り返し プロパティを使用すると、ユーザーは、繰り返し完了する必要がある実際のタスクを表す将来のタスクの作成を自動化できます。

ユーザーのシナリオ

次のシナリオがサポートされます。

  • 既存のタスクに繰り返し動作を追加し、定期的な系列を作成します。 または、繰り返しが定義された新しいタスクを作成します。 両方の最終結果は同じです。定期的なタスク、定期的な系列の最初のタスクです。 ユーザーは、繰り返しのスケジュールを指定します。

  • 既存の定期的な系列の定期的なスケジュールを編集します。

  • シリーズを続行します。 タスクが完了すると、定期的なスケジュールに従って新しいタスクが生成され、シリーズが続行されます。 系列内のアクティブなタスクが削除された場合は、ユーザーに対して、系列を続行するか終了するかを確認するメッセージが表示されます。 クライアントが繰り返しについて認識せず、プロンプトが表示されない場合は、シリーズを続行する必要があります。 誤って終了しないでください。

  • 次の方法で系列を終了します。

    • 系列内のアクティブなタスクを削除する (および[ はい ] を選択して系列を終了します)。
    • アクティブなタスクを削除せずに系列を終了する。

  • シリーズを復活させる。 繰り返しが終了した場合は、系列を元に戻す可能性があります。

定期的な会議と定期的なタスクの概念的な違い

このセクションでは、定期的なタスクの実際のシナリオについて説明し、定期的な会議と定期的なタスクの興味深い違いを説明し、定期的なパターンに対する変更の問題領域を調べます。

次の例では、定期的に完了する必要があるレポートを含み、定期的なタスクを使用してレポートの完了を追跡します。

レポートとその関連タスクは、金曜日に 2 週間ごとに期限が設定されます。2021 年 5 月 14 日にシリーズが開始されました。 最初のレポートは、その日付の 5 月 14 日 (金曜日) に期限が設定されています。 34 週間後の 2022 年 1 月 7 日に早送りします。 レポートを行った人は 12 月に休暇を取り、誰もレポートを完了しませんでした。 現在の定期的なタスク (および対応するレポート) は、12 月 10 日に期限です。 レポートとその関連タスクは、4 週間の期限切れになりました。

手記： この時点で、定期的な会議とイベントのコントラストが明らかになります。 自動システムが予定表で次の会議をスケジュールするために、会議を 完了としてマーク する必要はありません。 期限切れのタスクを完了すると、過去に期限が切れた別のタスクが生成される可能性がありますが、 過去に会議を完了するという概念はありません。 会議の次のインスタンスは、今日の日付に基づいて常に将来 の状態になります。 今日の日付は、遅延作業の追跡を失わないように、定期的なタスクの期限を計算するために使用されません。

このタスクでは、繰り返しスケジュールが編集されておらず、12 月 10 日のタスクが完了とマークされている場合、系列の次のタスクは 12 月 24 日の期限でインスタンス化されます。

ただし、今後、このレポートは 2 週間ごとにではなく、3 週間ごとに行う必要があることを決定したとします。 この決定は、期限切れのレポートに対して 3 週間のケイデンスをさかのぼって行う必要がある場合もあります。 この変更により、系列の継続を定義する方法に関して考えられるさまざまなオプションが招待されます。

  • 12 月 10 日の期限を変更する必要がありますか?
  • 次のタスクの期限はいつですか?

定期的なタスクの現在の状態と決定を次に示します。

  • 現在のタスクの期限は 2021 年 12 月 10 日です。
  • 前回完了したタスクの期限は 2021 年 11 月 26 日でした。
  • ケイデンスを 2 週間から 3 週間に変更することを決定します。この変更は、期限切れのレポートにさかのぼって適用されます。

コンテキストを考えると、2 つのオプションが可能であり、両方とも、新しい 3 週間のケイデンスに対応するようにシリーズを変更する方法に関する有効な顧客ストーリーです。

オプション 1: 12 月 10 日のタスクを、前の 11 月 26 日のタスクの 3 週間後に期限に変更します。 現在のタスクの期限は 12 月 17 日に変更され、次のタスクは 1 月 7 日に期限になります。

オプション 2: 現在の 12 月 10 日の期限を保持し、12 月 31 日に期限が設定されている次のタスクの間隔を変更します。

Planner では、これらのオプションの両方がサポートされています。 今日の日付 では、これらの異なるケースの処理方法は考慮されません。 この例については、「 例 1: patternStartDateTime を変更せずにパターンを変更する」で詳しく説明します。

定義

次の用語は、定期的な Planner タスクについて話し合い、説明するために使用されます。

アクティブな繰り返しがあるタスクの定義

次の 3 つの条件が満たされた場合、 plannerTask には アクティブな繰り返しがあります。

  • percentComplete プロパティの値は、 100未満です。
  • recurrence.nextInSeriesTaskId が null または未定義です。
  • recurrence.schedule には、null 以外の nextOccurrenceDateTime を持つ有効な plannerRecurrenceSchedule が含まれています。

アクティブな繰り返しを持つタスク (タスク A と呼びます) は、定期的な系列を続行する新しいタスク (タスク B) を作成するサービスの繰り返しメカニズムをトリガーできます。 その場合、 タスク A の recurrence.nextInSeriesTaskId は タスク B の ID に設定されます。 タスク A は 条件 2 を満たさなくなったため、 アクティブな繰り返しはありません。 nextInSeriesTaskId は読み取り専用プロパティであり、サービスがその値を削除することはありません。

繰り返し系列の定義

繰り返し系列 (繰り返し系列とも呼ばれます) は、連続した一連のタスクです。 系列は、1 つのタスクで繰り返しが最初に定義されたときに開始され、系列は同じ recurrence.seriesId を持つ新しいタスクの自動作成を続行します。

  • 同じ recurrence.seriesId を 共有するタスクは、同じ 繰り返し系列に属します。
  • 系列内の各タスクには、個別の recurrence.occurenceId があります。
  • 系列の最初のタスクには、1の occurrenceId があります。
  • 最初のタスクの繰り返しメカニズムがトリガーされると (アクティブな繰り返しがある間に完了または削除済みとしてマークされます)、2 番目のタスクは2の occurenceId で作成されます。 このプロセスは、 繰り返し系列 が終了するまで続行されます。

あいまいな用語の定期的なタスクの回避

一般的な音声では、 定期的なタスク という用語は、一連の中 でアクティブな繰り返しを持つ 一意のタスクを指す場合があります。また、 繰り返し系列自体、または繰り返し系列 内のすべてのタスクを参照する場合があります。 このあいまいさは、英語で読み上げられることが一般的です。同様に、 週次レポート はレポートの 1 つのインスタンスを参照するか、毎週レポートを実行する定期的な責任を参照する場合があります。 このあいまいさのため、定期的なタスクという用語の使用は回避されます。代わりに、アクティブな繰り返しまたは繰り返し系列を含むタスクのいずれかの用語を使用することをお勧めします。

リソースの種類の詳細

Planner タスクの定期的な操作には、 plannerTaskRecurrence、 plannerRecurrenceSchedule、 recurrencePattern という多くのリソースの種類を使用する必要があります。 以降のセクションでは、後者の 2 つのリソースの種類について詳しく説明します。

plannerRecurrenceSchedule

plannerRecurrenceSchedule は、定期的なパターン定義 (パターン)、そのパターンの開始日 (patternStartDateTime)、および次の発生日 (nextOccurrenceDateTime) を示すシステム生成プロパティをカプセル化します。

パターンは recurrencePattern です。詳細については、「recurrencePattern に関する Planner 固有のメモ」を参照してください。

patternStartDateTime は、DateTimeOffset として系列の開始日時を示します。 pattern プロパティを使用する場合は常に、null 以外の値を patternStartDateTime に割り当てる必要があります。これは現在、繰り返しを定義する唯一の方法です。 クライアントは通常、新しいパターンの開始日を示すために recurrence.schedule.pattern に変更を加えたときに、この値を再割り当てする必要があります。ただし、クライアントに値が含まれていない場合、サービスはスケジュールに基づいて既定値を使用して系列を続行します。 詳細については、次の注意事項と説明を参照してください。

nextOccurrenceDateTime は、読み取り専用のシステム生成フィールドです。 これは、系列内の次の plannerTask の dueDateTime として使用されるサービス計算日付を提供します。 nextOccurrenceDateTime は、patternStartDateTime または指定されたタスクの最初にスケジュールされた日付を追跡するアンカー値と共に、パターンから計算されます。

手記： Planner では現在、 recurrenceRange リソースの種類は使用されていません。

recurrencePattern に関する Planner 固有の注意事項

recurrencePattern の Planner 固有の制限を次に示します。

  • relativeMonthly と relativeYearly パターンでは、 daysOfWeek に対して複数の日を指定しない場合があります。
  • weeklyパターンの場合、daysOfWeek に複数の日が含まれている場合は、間隔を1する必要があります。

recurrencePattern に関する説明:

  • recurrencePattern 内のプロパティが変更されるたびに、関連するすべてのパターン プロパティを指定する必要があります。 たとえば、型 = dailyと間隔を持つパターン = 1は interval = 2 のみで修正することはできません。それ以外の場合、サービスは400 Bad Request応答コードを返します。 型 = dailyプロパティは、型が変更されていない場合でも指定する必要があります。 これは 、recurrencePattern リソースの種類に対する通常の動作ですが、他の Planner プロパティの動作は異なります。

  • 未使用のプロパティには、既定値が自動的に割り当てられます。

    • たとえば、 month プロパティは年単位のパターンにのみ使用され、 1 から 12までの有効な値があります。 ただし、daily、weekly、およびmonthlyパターンは、0が整数値の既定値であるため、month プロパティに割り当てられている0。
    • firstDayOfWeek と index を含む列挙プロパティは、最初の列挙値 (それぞれ sunday と first) に対応する既定値を取得します。

  • absoluteMonthlyパターンの場合、選択した dayOfMonth が特定の月に存在しない場合、その月の最終日が置き換えられます。

    • 例: dayOfMonth が 31 され、4 月に繰り返される場合、選択した日付は 4 月 30 日です。
    • 例: dayOfMonth が 29、 30、または 31 で、2 月に繰り返される場合、選択した日付は 2 月の 最終日 です。

  • 同様に、月 = 2と dayOfMonth = 29 のabsoluteYearlyパターンの場合、閏以外の年の選択された日付は 2 月 28 日です。

  • weeklyパターンの場合、firstDayOfWeek プロパティを使用して、今週考慮されるものと来週と見なされるものを区別します。 これは、weekly パターンを変更するときに関連します。 次のタスクは次の週にスケジュールされ、firstDayOfWeek は次の週がいつ始まるかを決定します。

firstDayOfWeek が毎週のパターンへの変更にどのように影響するかの例

次のプロパティ を持つアクティブな繰り返しを含むタスク が与えられます。

  • 毎週水曜日に発生します。パターンには、型 = weekly、間隔 = 1daysOfWeek = [wednesday]、firstDayOfWeek があります = sunday
  • dueDateTime は水曜日の 2/2 です
  • 次のOccurrenceDateTime は水曜日の 2/9 です

パターンに対して 3 つの変更が可能であり、次の表に、結果として得られる nextOccurrenceDateTime を示します。

パターンの変更 結果の nextOccurrenceDateTime
毎週火曜日 火曜日 2/8
毎週木曜日 木曜日 2/10
毎週木曜日と firstDayOfWeek が木曜日に変更されました 木曜日 2/3

木曜日 2/10 と木曜日 2/3 の違いに注意してください。 firstDayOfWeek = Thursday、木曜日 2/3 は水曜日 2/2 と同じ週ではなく、新しい週が木曜日に始まるのに対し、firstDayOfWeek がThursdayされていない場合は、木曜日 2/3 が水曜日 2/2 と同じ週に、木曜日 2/10 は次の週になります。

スケジュールと期限に関する注意事項

dueDateTime は、スケジュールと nextOccurrenceDateTime に影響を与えずに、クライアントが異なる値 (nullを含む) を持つよう編集できます。 たとえば、タスクが遅れて期限が変更され、その遅延に対応するように変更された場合、パターンや patternStartDateTime が明示的に更新されていない限り、系列内の次のタスクは元のスケジュールどおりに表示されます。 したがって、期限を延期しても、定義されたスケジュールに従って 日付がスキップ されることはありません。 これは、今日の日付が次の会議がいつ行われるかを決定する役割を果たす会議モデルとは異なります。 今日の日付を把握することは、次の会議やイベントの日付の計算には関連しますが、次のタスクの期日の計算には関係ありません。

例 1: patternStartDateTime に変更を加えた場合と変更しないパターンを変更する

次のプロパティ を持つアクティブな繰り返しを含むタスク が与えられます。

  • 定期的なパターンでは、金曜日の 2 週間ごとにを指定します( 例: type = weekly、 interval = 2daysOfWeek = [friday]、 firstDayOfWeek = sunday。
  • 前回完了したタスクの期限は 2021 年 11 月 26 日でした。
  • 現在のタスクの期限は 2021 年 12 月 10 日です。
  • 次のOccurrenceDateTime は、2021 年 12 月 24 日 (現在の期日から 2 週間後) です。

ケイデンスを 2 週間から 3 週間に変更することを決定します。 したがって、パターンは 間隔 = 3 毎週金曜日に同じ値を持つよう変更されます。

3 つの異なる可能性が検討され、それぞれがシリーズの次のタスクに対して異なる期日を生み出します。

説明の変更 結果の nextOccurrenceDateTime
パターンStartDateTime を 2021 年 12 月 10 日に変更する 2021 年 12 月 31 日
パターンStartDateTime を 2021 年 12 月 17 日に変更する 2022 年 1 月 7 日
patternStartDateTime を変更しない 2021 年 12 月 31 日

最初の例では、 patternStartDateTime は dueDateTime と同じ値 (たとえば、12 月 10 日) に設定されています。 次のOccurrenceDateTime は、patternStartDateTime の 3 週間後 (12 月 31 日) に設定されます。 概念的には、これは、このタスクではなく、次のタスクに対してのみ有効なケイデンス変更を表します。

2 番目の例では、 patternStartDateTime は 11 月 26 日から 12 月 17 日の 3 週間後に設定されています。 ここでも、 次のOccurrenceDateTime は 、patternStartDateTime の後の 3 週間 (今回は 1 月 7 日) に設定されます。 概念的には、これは、12 月 10 日 (現在のタスクの元の期日) ではなく、11 月 26 日 (前のタスク) から有効なケイデンス変更を表します。

通常、タスクの dueDateTime は、新しい patternStartDateTime と一致するように変更することをお勧めします。ただし、これは必要ありません。 2 番目の例の patternStartDateTime と共に dueDateTime が変更されていない場合、ユーザーには現在のタスクの 12 月 10 日の期限が引き続き表示されます。 完了すると、シリーズの次のタスクは 1 月 7 日にスケジュールされます。 これはユーザーにとって混乱する可能性があるため、 dueDateTime と patternStartDateTime を一緒に割り当てることをお勧めします。

3 番目の例は、 patternStartDateTime を指定しない点を除き、最初の例と似ています。 8 月のように長い時間がかかった patternStartDateTime は使用できません。 この場合、 nextOccurrenceDateTime は 12 月 10 日の 元の期日 に基づいて計算され、最初の例と同様に、12 月 31 日の nextOccurrenceDateTime になります。 元の期日は公開されませんが、この計算では使用されます。 つまり、 dueDateTime は別の値に変更することも、 nullするように変更することもできますが、この計算では dueDateTime 値は無視されます。代わりに 元の期日を使用します。 これは、 dueDateTime と patternStartDateTime を一緒に変更することをお勧めするもう 1 つの理由です。

例 2: 期限が次の発生に影響しない

次のプロパティ を持つアクティブな繰り返しを含むタスク が与えられます。

  • 毎週水曜日に発生します。 パターン には 、型 = weekly、 間隔 = 1daysOfWeek = [wednesday]、 firstDayOfWeek = sundayがあります。
  • dueDateTime は 2/16 (月) です。
  • nextOccurrenceDateTime は Wed 2/9 です。
  • 元の期限は水曜日の 2/2 です。 この値はパブリックに公開されませんが、 nextOccurrenceDateTime から推論できます。

次に示す 3 つの変更の検討を行います。

変更 結果の nextOccurrenceDateTime
変更なし 火曜日 2/9
パターンは毎週木曜日に変更されました。patternStartDateTime への変更なし 木曜日 2/10
patternStartDateTime が 2/9 に変更されました。パターンに変更はありません 水曜日 2/16

3 つすべての例では、dueDateTime は水曜日 2/16 の変更された値から変更されません。また、系列の次のタスクは、前のテーブルの次のOccurrenceDateTime と等しい dueDateTime で作成されます。

注:

  • patternStartDateTime が明示的に再割り当てされていない場合の既定の動作は、元の期日に基づいてスケジュールが継続することです。 この場合、元の 期日 は 2/2、現在の dueDateTime は 2/16 です。
  • patternStartDateTime が変更された場合、その新しい開始日を使用して nextOccurrenceDateTime が再計算されます。
  • 期限が 2/16 ではなく null に変更された場合、または将来または過去の他の日付に変更された場合、前の例は影響を受けません。

開発者シナリオ

定期的なアイテムを作成する

recurrence.schedule は、繰り返しの唯一のクライアント編集可能なサブプロパティです。 recurrence.schedule を追加することで (繰り返しが既に定義されているかどうかに関係なく)、クライアントは非定期的なタスクをアクティブな定期的なタスクに変更できます。

アクティブな繰り返しの定義に記載されている他の 2 つの条件は、recurrence.schedule を追加できるかどうかに影響します。

  • percentComplete プロパティは、100未満にする必要があります。
  • recurrence.nextInSeriesTaskId プロパティは、nullするか、割り当て解除する必要があります。

その他の 繰り返し サブプロパティは読み取り専用です。 まだ割り当てていない場合、 recurrence.schedule が追加されると、サービスによって自動的に生成されます。

トリガーの繰り返し

アクティブな繰り返しがある タスクで繰り返しメカニズムをトリガーできる 2 つの方法を次に示します。

アクティブな繰り返しがある_taskの前の定義で、3 つの条件のいずれかが満たされていない場合、繰り返しメカニズムはトリガーされません (新しいタスクは作成されておらず、 nextInSeriesTaskId は割り当てられません)。

通常、新しいタスクのインスタンス化は直ちに行われます。これにより、新しいタスクの作成に遅延が発生することがあります。

新しいタスクには、 タイトル、 説明、 チェックリスト項目 (不完全に設定)、 割り当て、 優先度、 カテゴリの各プロパティが、現在完了したタスクからコピーされます。 新しいタスクの percentComplete は、 0に設定されます。 新しいタスクの dueDateTime は、定期的なスケジュールに従って設定されます。 次の繰り返しのサブプロパティがコピーされます。 seriesId、recurrenceStartDateTime、schedule。schedule.nextOccurrenceDateTime は、新しいタスクに対して新しく計算されます。 その他の繰り返しプロパティには、新しいタスクに適切な値が与えられます。

シリーズの次のタスクを見る

タスク C に繰り返しが定義されていて、ユーザーがタスク C の完了 (percentComplete = 100) をマークした場合、タスク D が作成され、定期的な一連の作業が続行されます。 タスク C には、タスク D の ID が設定された recurrence.nextInSeriesTaskId プロパティがあります。

一方、 タスク C が削除され、削除によって繰り返しがトリガーされる場合、クライアントは他の方法で タスク D の ID を検出する必要があります。 たとえば、同じバケット内のタスクに対してクエリを実行したり、差分同期フィードを使用したりします。

定期的な系列を編集する

アクティブな繰り返しがあるタスクでは、定期的なスケジュールを編集できます。 recurrence.schedule は、編集できる繰り返しの唯一のサブプロパティであることに注意してください。

たとえば、アクティブな繰り返しと 毎週水曜日のスケジュールを持つタスクでは、そのスケジュールを 毎月 15 日に月単位に変更できます。

定期的な系列を終了する

定期的な系列を終了するには、 recurrence.schedule プロパティを null に設定します。 これは、 nextInSeriesTaskId が null または割り当てられていない場合にのみ実行できます。

終了後の繰り返しの復活

recurrence.schedule を削除した後、系列を復活させるタスクに新しい recurrence.schedule を追加できます。

「 定期的な系列を作成する」の前の手順に従います。 同じ制限が適用されます。 元の recurrence.seriesId およびその他の 繰り返 しのサブプロパティは変更されず、元の系列を実質的に復帰または継続します。

定期的な一連の中でアクティブな繰り返しを持つタスクを特定する

recurrence.seriesId を指定すると、その seriesId を持つ最大 1 つのタスクでアクティブな繰り返しを実行できます。

完了したタスクは、ほとんどのビューから非表示になります。 完了とマークされているタスクをユーザーが表示することは珍しい場合があります。 削除されたタスクは表示できません。 つまり、ほとんどの場合、アクティブな繰り返しを持つタスクは 1 つの繰り返し系列に存在します。 アクティブな繰り返しを持つタスクが、スケジュールを削除して非アクティブ化されている場合、その系列にアクティブな繰り返しがあるタスクは存在しません。

まれな例外的なシナリオ

次のシナリオはまれですが、可能です。 クライアントには例外のように見えるかもしれませんが、実際には、サービスは常にルールの整合性を維持します。特定の繰り返しシリーズでアクティブな繰り返しを持つ最大 1 つのタスク。 あいまいさを解消するためのガイダンスが提供されます。

原因

次に、情報が同期していないように見える 2 つの原因を示します。

  • Planner のクライアント向けの高速ストレージにはまだ情報が届いていません。 Planner の権限のある情報ソースにはデータがありますが、クライアントにデータを返す要求最適化ストレージにデータがまだレプリケートされていません。

  • 繰り返しメカニズムで一時的なエラーが発生しました。 つまり、シリーズを継続する新しいタスクはまだ作成されていません。通常、数秒または数分で作成されます。

同じ繰り返し系列にアクティブな繰り返しがある 2 つのタスク

クライアントが同じ繰り返し系列でアクティブな繰り返しを持つ 2 つのタスクを観察した場合、 occurrenceId が 小さいタスクは、繰り返しメカニズムが既にトリガーされていると見なすことができます。 Planner のバックエンド ストレージには nextInSeriesTaskId が設定されていますが、その情報はまだクライアント向けの高速ストレージに到達していません。 occurrenceId が大きいタスクは、アクティブな繰り返しを持つ一意のタスクです。

アクティブな繰り返しがあるタスクの occurrenceId は、同じ繰り返し系列内の別のタスクよりも小さいです

前の "アクティブな定期的な 2 つのタスク" と同様に、この 2 番目の状況は、 occurrenceId が 大きいタスクの繰り返しが非アクティブ化されている場合に観察される可能性があります (recurrence.schedule = null)。 occurrenceId が大きいタスクが存在するということは、occurrenceId が大きいタスクにもアクティブな繰り返しがない場合でも、その系列の occurrenceId が小さいタスクにアクティブな繰り返しがないことを意味します。

一連のアクティブな繰り返しを含む 0 個のタスク

これは本当にあいまいな状況です。次のいずれかが考えられます。

  • 繰り返しメカニズムは、一時的な障害によって遅延しました。再試行されます。
  • 繰り返しメカニズムは成功しましたが、新しいタスクはまだクライアント向けの高速ストアに追加されていません。
  • 新しいタスクが作成されましたが、別のクライアントによって削除されました。

最初の 2 つの状態は一時的な状態であり、通常は数秒または数分でサービスによって修復されます。 3 つ目は一般に永続的です。 このシナリオを まれまたは例外的と表現することは、おそらく不正確です。しかし、最初の2つのケースの可能性のために観察された状態にあいまいさがあるという事実に注意を払うために以前に説明しました。

定期的なシリーズのすべてのタスクを検索する

Planner を使用する開発者は、プラン内のすべてのタスクを取得するための既存の API に精通しています。 Planner には、 定期的なシリーズのすべてのタスクを取得するための API がまだありません。ただし、プラン内のすべてのタスクを取得することで、通常、 定期的な一連のすべてのタスクを取得できます。

各 plannerTask の recurrence.seriesId プロパティは、1 つ以上のタスクが属する特定の定期的な系列とは異なる識別子です。 割り当てられた場合、この値は変更できません。 recurrence.occurrenceId は、系列内のタスクの順序を示す整数値です。 系列の最初のタスク (繰り返しが最初に追加されたタスク) には、1の occurrenceId が指定されます。

注:

  • 系列の一部のタスクが削除された場合、インデックスにギャップが含まれている可能性があります。
  • ユーザーが定期的な系列を別のプランに移動した場合は、他のプランを調べる必要があります。ただし、ユーザーは通常、1 つのプラン内の定期的なシリーズに主に関心があります。 タスクはグループの境界を越えて移動することはできません。グループ内のすべてのプランが照会された場合は、元のプランから移動された可能性のあるすべてのタスクを見つけることができます。

REST 操作の例

次の要求と応答は、順序付けられた一連の操作を表します。 適切な識別子 (タスク、計画、定期的な系列など) を置き換えることで、Planner タスクの繰り返しを実装するクライアントのテスト ケースとして使用される場合があります。多くのエラー ケースは、特定の状態に対する不適切な変更を示すために散在しています。

期限と繰り返しを既存の plannerTask に追加する

次の要求と応答の例は、タスクへの繰り返し方法を示しています。 ID 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 は 11 月 13 日で、パターンは 1 日おきに定義されます。これにより、patternStartDateTime の 2 日後の nextOccurrenceDateTime が 11 月 15 日になります。
  • seriesId と occurrenceId は自動的に生成されます。 seriesId は、Planner 識別子形式でエンコードされた新しい GUID です。 これはシリーズの最初のタスクであるため、1の occurrenceId を取得します。
  • recurrenceStartDateTime には、patternStartDateTime と同じ値が割り当てられます。 これは、系列の最初のタスク (occurrenceId = 1) に当てはまります。 ただし、シリーズの今後のタスクでは、patternStartDateTime が変更されても、recurrenceStartDateTime の値は変更されません。パターンの変更とは対照的に、繰り返しの開始を追跡します。
  • これは系列の最初のタスク (occurrenceId = 1) であるため、前のInSeriesTaskId は常にnullされます。
  • 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 番目のタスク)

次の要求と応答の例は、 percentComplete を 100 に設定する方法を示しています ( タスクの完了またはタスク の 完了マークとも呼ばれます)。

要求

次の例は、繰り返しの有無にかかわらず、タスクに対して同一の要求を示しています。

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

{
    "percentComplete": 100
}

応答

HTTP/1.1 204 NO CONTENT

完了したタスクを取得し、シリーズの次の (2 番目の) タスクの ID を検出する

次の要求と応答の例は、完了とマークされた後にタスクを取得する方法を示しています。

要求

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 から検出された、系列の新しいタスク ID を取得する方法を示しています。

要求

要求の例 (GxOo0ms1iEu3eBI1-6lk85UAI5FI) には、前の例 (Q7SNdWp5ekeJTpRRSCcZ3pUAD6kV) と比較した場合の次の違いが含まれています。

  • dueDateTime には、タスクの前の nextOccurrenceDateTime の値が割り当てられます。
  • nextOccurrenceDateTime は 、スケジュールに従って計算されています。前の dueDateTime の後に次に出現します。
  • occurrenceId はではなく21
  • 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"
}

タスクの繰り返しを週 1 日に編集し、期限を 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.pattern が、火曜日に毎週、 dueDateTime = null と共に表示されます。

要求

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

応答

次の例では、タスクにアクティブな繰り返しと null の期限を設定できます。 次のOccurrenceDateTime が再計算され、現在は daysOfWeek から火曜日の 11 月 23 日になります。 この次の発生は、月曜日の 11 月 15 日のタスクの元の dueDateTime に基づいて計算されます。

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
}

定期的なスケジュールを削除する

次の要求と応答の例では、 nullrecurrence.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
}

エラー ケース: patternStartDateTime を指定せずに新しい繰り返しスケジュールの追加を試みます

次の要求と応答の例は、不適切な要求を示しています。patternStartDateTime を指定せずに新しい recurrence.schedule を追加しようとしています。

要求

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

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

応答

次に、問題を説明するエラーを示す応答の例を示します。 エラー メッセージには、Recurrence.Schedule.RangeではなくRecurrence.Schedule.PatternStartDateTimeが含まれる必要があるため、応答オブジェクトにバグが含まれています。 これは現在、既知の問題です。

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 = null があるタスクに新しい recurrence.schedule を割り当てる方法を示しています。

手記：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 でマークする)

次の要求と応答の例は、 percentComplete を 100 に設定する方法を示しています ( タスクの完了またはタスク の 完了マークとも呼ばれます)。

要求

次の要求は、繰り返しの有無にかかわらず、タスクと同じです。

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

{
    "percentComplete": 100
}

応答

HTTP/1.1 204 NO CONTENT

完了したタスクを取得し、シリーズの次の (3 番目の) タスクの ID を検出する

次の要求と応答の例は、完了とマークされた後にタスクを取得する方法を示しています。

要求

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 が既に割り当てられているときに、繰り返しスケジュールの削除を試みます

次の要求と応答の例は、nextInSeriesTaskId プロパティが割り当てられた後に、recurrence.schedule プロパティに値を割り当てようとした、不適切な要求を示しています。

要求

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 から検出した系列の新しいタスク ID を取得する方法を示しています。 dueDateTime は、タスクの前の dueDateTime がnullされていた場合でも、タスクの前の nextOccurrenceDateTime に表示される値に割り当てられます。

要求

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"
}