Planner REST APIを使用する

  • [アーティクル]

重要

Microsoft Graph の /beta バージョンの API は変更される可能性があります。 実稼働アプリケーションでこれらの API を使用することは、サポートされていません。 v1.0 で API を使用できるかどうかを確認するには、Version セレクターを使用します。

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

Planner API の使用を開始する前に、メイン オブジェクトが相互および Microsoft 365 グループにどのように関連しているかを理解しておくと役立ちます。

プラン コンテナー

Microsoft Plannerでは、プランは常に別のリソースに含まれます。 含まれているリソース plannerPlanContainer は、プランの承認規則とその中のすべてのタスク、およびプランのライフサイクルを決定します。 プランは、driveItem、Microsoft 365 グループ、Planner プロジェクト、名簿、またはユーザーのいずれかの種類のコンテナーに作成できます。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

プラン

プランはタスクのコンテナーです。 プランのタスクを作成するには、タスクの作成時にタスク オブジェクトの 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 リソースの種類 サブスクライブしているインスタンス
タスク
  • ユーザーによって作成
  • ユーザーに割り当て済
  • ユーザーが所有しているプランに属しています。
  • プランの sharedWith コレクションを通してユーザーと共有されているプランに含まれています
プラン
  • プランの sharedWith コレクションを通してユーザーと共有されています
バケット
  • プランの sharedWith コレクションを通してユーザーと共有されているプランに含まれています

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

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

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

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

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

特定のシナリオでは、呼び出し側は、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ステータスコードを返す可能性があります。 以下は、よくある原因の一部です。

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

403 Forbidden

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

値 説明
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 プロパティに含まれる値が多すぎます。
MaximumFavoritePlansForUser plannerUser リソースの favoritePlanReferences プロパティに含まれる値が多すぎます。
MaximumRecentPlansForUser plannerUser リソースの recentPlanReferences プロパティに含まれる値が多すぎます。
MaximumContextsOnPlan plannerPlanリソースの contexts プロパティに含まれる値が多すぎます。

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

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