Microsoft Planner のタスクを Microsoft Graph を使って操作してみた

yhana

2023.10.04

Microsoft Planner のタスク操作を API により実行したい状況があったため、習熟も兼ねて Microsoft Graph を使ってタスクの作成と更新を試してみました。

Microsoft Graph で Planner のタスクを操作

本ブログでは、作成済みのプランにおいてタスクの作成とタスクの更新を試してみます。

タスクの作成にはプラン ID が必要となります。プラン ID はブラウザでプランを選択しているときの URL から確認できます。下記 URL 例におけるplanId=NRwiKEZbCUa7QABNLe5cbcgAHITI部分です。

https://tasks.office.com/classmethod.onmicrosoft.com/ja/Home/Planner/#/plantaskboard?groupId=8b92d200-adfc-44d2-ad75-d7a4eexample&planId=NRwiKEZbCUa7QABNLe5cbcgAHITI


タスクの作成

タスクの作成を試してみます。

タスクの作成は「Create plannerTask」を利用します。

Create plannerTask - Microsoft Graph v1.0 | Microsoft Learn


視覚的に分かりやすいため、Microsoft Graph Explorer でタスク作成を試してみます。単純にタスク名と優先度だけを指定して作成しています。

Request Body

{
    "planId": "NRwiKEZbCUa7QABNLe5cbcgAHITI",
    "title": "Test Task",
    "priority": 5
}

Response

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#planner/tasks/$entity",
    "@odata.etag": "W/\"JzEXAMPLECc=\"",
    "planId": "NRwiKEZbCUa7QABNLe5cbcgAHITI",
    "bucketId": null,
    "title": "Test Task",
    "orderHint": "8585052627314145714",
    "assigneePriority": "",
    "percentComplete": 0,
    "startDateTime": null,
    "createdDateTime": "2023-10-03T14:42:34.0630093Z",
    "dueDateTime": null,
    "hasDescription": false,
    "previewType": "automatic",
    "completedDateTime": null,
    "completedBy": null,
    "referenceCount": 0,
    "checklistItemCount": 0,
    "activeChecklistItemCount": 0,
    "conversationThreadId": null,
    "priority": 5,
    "id": "DsX7GL3O4ECiKcYRiRxemsgAPzWZ",
    "createdBy": {
        "user": {
            "displayName": null,
            "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
        },
        "application": {
            "displayName": null,
            "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
        }
    },
    "appliedCategories": {},
    "assignments": {}
}


実行時にもし権限不足のエラーとなった場合は「Modifypermissions」タブから必要な権限を許可する必要があります。今回の場合ではTasks.ReadWriteの許可が必要です。

ブラウザで Planner を確認してみたところ、作成したタスクである「Test Task」が追加されていました。

なお、curl コマンドで実行する例は次の通りです。

curl -X POST \
  -H 'Content-type: application/json' \
  -H 'Authorization: Bearer XXXEXAMPLE' \
  -d '{"planId": "NRwiKEZbCUa7QABNLe5cbcgAHITI", "title": "Test Task", "priority": 5}' \
  https://graph.microsoft.com/v1.0/planner/tasks


タスクの更新

次にタスクの更新を試してみます。

タスクの更新には「Update plannerTask」を利用します。

Update plannerTask - Microsoft Graph v1.0 | Microsoft Learn


Microsoft Learn に記載の通り、Request headers として If-Match が必要となります。

Last known ETag value for the plannerTask to be updated. Required.


ETag の値はタスク作成時の Response の@odata.etagから確認できます。また、Update plannerTask の URL として指定するために必要なタスク ID も Response のidから確認できます。

URL にタスク ID を反映し、ヘッダーとして If-Match を追加した画面です。

Request Body に更新内容として進行状況が「完了済み」であることを示すpercentComplete: 100を指定して、クエリを実行した結果画面です。

Request Body

{
    "percentComplete": 100
}

Response

{}


ブラウザで Planner を確認してみたところ、タスクが完了済みに更新されていました。

なお、curl コマンドで実行する例は次の通りです。

curl -X PATCH \
  -H 'Content-type: application/json' \
  -H 'If-Match: "JzEXAMPLECc="' \
  -H 'Authorization: Bearer XXXEXAMPLE' \
  -d '{"percentComplete": 100}' \
  https://graph.microsoft.com/v1.0/planner/tasks/DsX7GL3O4ECiKcYRiRxemsgAPzWZ


以上で、Microsoft Graph を利用したタスクの作成、更新は終わりです。

さいごに

Microsoft Planner のタスクを API を操作してみたかったため試してみました。Microsoft Graph Explorer で確認できるのは便利でした。

以上、このブログがどなたかのご参考になれば幸いです。

*