Planner REST APIを使用する

  • [アーティクル]

Microsoft Graph の Planner API を使用してタスクを作成し、それらを Microsoft 365 のグループ内のユーザーに割り当てることができます。

Planner API を使い始める前に、メイン オブジェクト同士や、Microsoft 365 グループとの関係について理解しておくと役に立ちます。

プラン コンテナー

Microsoft Planner では、プランは常に別のリソースに含まれています。 含んでいるリソースは、プランの承認ルールとその中にあるすべてのタスク、およびプランのライフサイクルを決定します。 たとえば、Microsoft 365 グループに含まれるプランの場合、グループ メンバーは、プラン内のタスクの作成、編集、解決、削除、およびプランの名前やラベル名などのプランレベルのプロパティの変更ができます。 さらに、グループが削除されると、グループ内のすべてのプランは自動的に削除され、グループが復元されると、すべてのプランは自動的に復元されます。

最も一般的なコンテナーの種類は、Microsoft 365 グループです。

コンテナーの種類: Microsoft 365 グループ

プランは通常、Planner API の Microsoft 365 グループに含まれています。 グループが所有するプランを取得するには、次に示す HTTP 要求を行います。

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

新しいプランを作成するとき、プラン オブジェクトのcontainer プロパティを設定して、グループをそのコンテナーにします。 プランは、サポート対象のリソースに含まれている必要があります。

注意: プランを作成するユーザーは、プランを含むグループのメンバーである必要があります。 あなたが新しいグループをグループの作成を使用して作成しても、メンバーとしてそのグループに追加されることはありません。 グループを作成したら、グループ投稿メンバーを使用して自分自身をメンバーとして追加します。

プラン

プランはタスクのコンテナーです。 プランのタスクを作成するには、タスクの作成時にタスク オブジェクトの planId プロパティをプランの ID に設定します。 現在、プランなしでタスクを作成することはできません。 プラン内のタスクを取得するには、次のHTTPリクエストを行います。

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

タスク

各タスクは、タスク オブジェクトの assignments プロパティに assignment を追加することにより、ユーザーに割り当てることができます。 タスクを割り当てるユーザーの ID は assignmentsオープン プロパティの名前であり、割り当ての orderHint プロパティを指定する必要があります。

タスクとプランの詳細

Planner のリソースは、基本オブジェクトと詳細オブジェクトに配置されます。 基本オブジェクトは、リスト ビューに適したリソースの共通プロパティへのアクセスを提供し、詳細オブジェクトは、ドリル ダウン ビューに適したリソースの大規模なプロパティへのアクセスを提供します。

視覚化

Planner API は、タスクとプランのデータのほかに、データの共通した視覚化をクライアント全体に提供するためのリソースも提供します。 次の表にリストされているように、タスクにはいくつかの種類の視覚化データがあります。

タスクの表示 タスクを順序付ける情報の情報源
フラット リスト (プラン内のタスク) タスクの orderHint プロパティ
フラット リスト (ユーザーに割り当てられたタスク) タスクの assigneePriority プロパティ
割り当て先の列を含むボード ビュー (タスク ボードに割り当て) assignedToTaskBoardTaskFormat オブジェクト
タスクの進行状況を示す列を含むボード ビュー (進行状況タスク ボード) progressTaskBoardTaskFormatオブジェクト
タスクのカスタム列を含むボード ビュー (バケット タスク ボード) bucketTaskBoardTaskFormat オブジェクト

バケット タスク ボード内のカスタム列は、 bucket オブジェクトと、オブジェクトの orderHint プロパティによる順序によって表されます。

すべての順序は、Planner の順序のヒントに書かれた原則によって制御されます。

Planner のリソースのバージョン管理

Plannerはすべてのリソースを etagsを使ってバージョン管理します。 これらの etags は各リソースの @odata.etag プロパティと一緒に返されます。 PATCHとDELETE リクエストは、クライアントが知っている最後のetagをIf-Matchヘッダで指定することを要求します。 目的の変更が同じリソース上の Planner サービスによって受け入れられた新しい変更と競合しない場合、Planner は古いバージョンのリソースに変更を加えることができます。 クライアントは、etag順序文字列の比較でどの値が大きいかを計算することによって、同じリソースのどのetagがより新しいかを識別できます 。 各リソースには固有の etagがあります。 異なるリソースの Etag 値は比較できません (包含関係のあるものを含む)。 クライアント アプリは、バージョン管理に関連する エラー コード409 を処理し、 412 アイテムの最新バージョンを読み取り、競合する変更を解決することで処理する必要があります。

一般的な Planner のエラー条件

Microsoft Graph に適用される一般的なエラーのほかに、Planner API に固有のエラー条件もあります。

400 要求が正しくありません

いくつかの一般的なシナリオでは、POST and PATCH リクエストは400ステータスコードを返す可能性があります。 以下は、よくある原因の一部です。

  • Open Type プロパティが正しい型でないか、型が指定されていないか、またはプロパティが含まれていません。 たとえば、複雑な値が指定された plannerAssignments プロパティは、値 microsoft.graph.plannerAssignment を指定した @odata.type プロパティで宣言する必要があります。
  • ORDER ヒントの値が正しい書式になっていません。 たとえば、ORDER ヒントの値は、クライアントに返される値に直接設定されています。
  • データが論理的に矛盾しています。 たとえば、タスクの開始日がタスクの期日よりも後になる場合などです。

403 Forbidden

Planner API では、一般的なエラーのほかに、サービスで定義された制限を超えた場合にも 403 ステータス コードを返します。 この場合、エラー リソース タイプの code プロパティは、要求が超過した制限タイプを示します。 制限の詳細については、「Planner制限」を参照してください。 以下は、制限タイプに有効な値です。

値 説明
MaximumProjectsOwnedByUser グループに含まれるプランの最大数の制限を超過しています。 この制限は、plannerPlan リソースの container プロパティに基づいて、グループに含まれるプランに適用されます。
MaximumProjectsSharedWithUser ユーザーに共有されるプランの最大数の制限を超過しています。 この制限は、plannerPlanDetails リソースの sharedWith プロパティに基づいています。
MaximumTasksCreatedByUser ユーザーが作成するタスクの最大数の制限を超過しています。 この制限は、plannerTask リソースの createdBy プロパティに基づいています。
MaximumTasksAssignedToUser ユーザーに割り当てられるタスクの最大数の制限を超過しています。 この制限は、plannerTask リソースの assignments プロパティに基づいています。
MaximumTasksInProject プランにおけるタスクの最大数の制限を超過しています。 この制限は、plannerTask リソースの planId プロパティに基づいています。
MaximumActiveTasksInProject プランで完了されないタスクの最大数の制限を超過しています。 この制限は、plannerTask リソースの planId および percentComplete プロパティに基づいています。
MaximumBucketsInProject プランにおけるバケットの最大数の制限を超過しています。 この制限は、plannerBucket リソースの planId プロパティに基づいています。
MaximumUsersSharedWithProject plannerPlanDetails リソースの sharedWith プロパティに含まれる値が多すぎます。
MaximumReferencesOnTask plannerTaskDetails リソースの references プロパティに含まれる値が多すぎます。
MaximumChecklistItemsOnTask plannerTaskDetails リソースの checklist プロパティに含まれる値が多すぎます。
MaximumAssigneesInTasks plannerTask リソースの assignments プロパティに含まれる値が多すぎます。
MaximumPlannerPlans グループには、ユーザーが所有するプランの最大数が既に含まれています。現在は 200 です。 制限の詳細については、「Planner制限」を参照してください。

412 前提条件が失敗しました

Planner API のすべての POST、PATCH および DELETE 要求には、要求対象となるリソースの直近の etag 値で If-Match ヘッダーを指定する必要があります。 さらに、要求に指定された etag 値がサービス内のリソースのバージョンと一致しなくなった場合は、412 ステータス コードが返されます。 この場合、クライアントはリソースを再度読み込んで、新しい etag を取得する必要があります。