Planner REST APIを使用する

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

Planner API を使い始める前に、メイン オブジェクトの相互関係および Microsoft 365 グループとの関係を理解しておくと便利です。

プラン コンテナー

Microsoft Planner では、プランは常に別のリソースに含まれています。 このリソースを含む plannerPlanContainer は、プランとその中のすべてのタスク、およびプランのライフサイクルの承認ルールを決定します。 driveItem、Microsoft 365 グループ、plannerTask、Planner project、roster、teamsChannel、または user のいずれかの種類のコンテナーにプランを作成できます。

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

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

プランは通常、Planner API のグループに含まれています。

グループ メンバーは、プラン内のタスクを作成、編集、解決、削除できます。 グループ メンバーは、プランの名前やラベル名など、一部のプラン レベルのプロパティを変更することもできます。 さらに、グループが削除されると、グループ内のすべてのプランが自動的に削除されます。 逆に、グループが復元された場合は、すべてのプランが自動的に復元されます。

グループが所有するプランを取得するには、次に示す HTTP 要求を行います。

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

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

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

コンテナーの種類: Planner タスク

plannerTask コンテナーの種類は、Planner タスクに含まれるプランをサポートします。 Planner タスクに含まれるプランは、タスクが削除されると削除されます。

Planner タスクのコンテナーで新しいプランを作成するには、タイプを plannerTask に設定したプラン オブジェクトにコンテナー プロパティを設定し、id を Planner タスクの ID に設定します。

{
    "container": {
        "id": "{task-id}",
        "type": "plannerTask"
    }
}

または、Planner タスクの URL を指定することもできます。

{
    "container": {
        "url": "https://graph.microsoft.com/beta/planner/tasks/{task-id}"
    }
}

コンテナーの種類: Teams チャネル

teamsChannel コンテナーの種類は、Teams の共有チャネルで作成されたプランをサポートします。チャネルはプランのコンテナーです。 共有チャネルにピン留めされているプランは、チャネルが削除されると削除されます。

Teams チャネルのコンテナーで新しいプランを作成するには、プランオブジェクトにコンテナー プロパティを設定し、タイプを teamsChannel として設定し、ID を「{team-id}/channels/{channel-id}」として書式設定する必要があります。

{
    "container": {
        "id": "{team-id}/channels/{channel-id}",
        "type": "teamsChannel"
    }
}

または、Teams で共有チャネルの URL を指定することもできます。

{
    "container": {
        "url": "https://graph.microsoft.com/beta/teams/{team-id}/channels/{channel-id}"
    }
}

コンテナーの種類: ユーザー

ユーザー コンテナーの種類は、個々のタスクを追跡する唯一のユーザーである個人用プランをサポートします。 これにより、ユーザーは個人用プランを共有または共同作業する柔軟性が提供されます。 1 人のユーザー用に作成されたプランは、そのユーザーが削除されると自動的に削除されます。

ユーザーのコンテナーに新しいプランを作成するには、タイプが user のプラン オブジェクトにコンテナー プロパティを設定します。

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

または、ユーザーの URL を指定することもできます。

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

ユーザーは、 プランをユーザー コンテナーからグループ コンテナーに移動し、プランのコンテナーの種類を user から group に変更することで、個人プランをグループ ベースのプランにアップグレードできます。

プラン

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

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

目標

目標は 、計画内の一連のタスクが達成することを意図している高レベルの成果を表します。 1 つのプランには複数の目標を設定でき、1 つのタスクは複数の目標に関連付けることができます。

プラン内の目標を取得するには、次の HTTP 要求を行います。

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

タスクに関連付けられている目標を特定するには、plannerTask オブジェクトで読み取り専用の goalIds プロパティを使用します。

タスク

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

タスクとプランの詳細

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

視覚化

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

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

順序付けの原則については、 Planner の順序のヒントで説明されています。

デルタクエリを使用して変更を追跡する

Plannerのデルタクエリは、ユーザがサブスクライブしているオブジェクトのクエリをサポートします。

ユーザーは以下のオブジェクトをサブスクライブしています。

デルタクエリ用にオブジェクトキャッシュを生成する

PlannerデルタクエリAPIを使用したい場合は、デルタ応答フィードからの変更を適用するために、ユーザーが観察したいオブジェクトのローカル・キャッシュを維持してください。

現在、Planner デルタ クエリが返すことができるデルタ ペイロード オブジェクトは次のとおりです。

• plannerTask
• plannerTaskDetails
• plannerPlan
• plannerPlanDetails
• plannerBucket
• plannerAssignedToTaskBoardTaskFormat
• plannerBucketTaskBoardTaskFormat
• plannerAssignedToTaskBoardTaskFormat

リソース上の対応するGETメソッドを使用して、ローカルキャッシュに移入するオブジェクトの初期状態を取得します。

計画の履歴を確認する

Planner では、プラン内のタスクに加えられた変更履歴を取得する API がサポートされています。

オブジェクトの作成とオブジェクトの変更の違い

特定のシナリオでは、呼び出し側は、Plannerのデルタクエリフィード内でオブジェクトの作成とオブジェクトの変更を区別したい場合があります。

これらのガイドラインは、オブジェクト作成を推測するために使用できます。

• createdBy プロパティは、新しく作成されたオブジェクトに表示されます。
• 新しく作成された plannerTask オブジェクトの後に、対応する plannerTaskDetails オブジェクトが続きます。
• 新しく作成された plannerPlan オブジェクトの後に、対応する plannerPlanDetails オブジェクトが続きます。

使用方法

呼び出し元は、サブスクライブしているオブジェクトが含まれるキャッシュを持っている必要があります。 サブスクライブされたオブジェクトのローカルキャッシュを埋める方法の詳細については、デルタクエリ用にオブジェクトキャッシュを生成するを参照してください。

Plannerのデルタクエリコールフローは次のとおりです。

1. 呼び出し側がデルタ同期照会を開始し、nextLinkと空の変更コレクションを取得します。
2. 呼び出し側はユーザーがサブスクライブしているオブジェクトを使用して、差分キャッシュのオブジェクトキャッシュにデータを入力し そのキャッシュを更新する必要があります。
3. 呼び出し側は、最初のデルタ同期照会で提供されたnextLinkの内容に従って前のステップ以降に行われたdeltaLink新しい変更を取得します 。
4. 呼び出し側は、返されたデルタレスポンスの変更をキャッシュ内のオブジェクトに適用します。
5. 呼び出し側は新しい deltaLink をたどって現在の deltaLink 生成後の次の deltaLink と変更を取得します。
6. 呼び出し側は変更があればそれを適用して、前のステップとこのステップを再実行する前に少し待ちます。

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ステータスコードを返す可能性があります。 以下は、よくある原因の一部です。

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

403 Forbidden

一般的なエラーに加えて、Planner API は、サービス定義の制限を超えたときに 403 状態コードも返します。 その場合、エラー リソースの種類の コード プロパティは、要求が超えた制限の種類を示します。 以下は、制限タイプに有効な値です。

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

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