Plannerでアプリを利用したタスクを管理して、カスタマイズされたタスクエクスペリエンスを実現する

[アーティクル]
12/18/2024
適用対象:

Microsoft Teams

注意

この機能は現在パブリックプレビュー段階です。

概要

アプリを利用したタスク機能を使用すると、organization Microsoft Teams内のPlanner アプリでタスクを開いたときにユーザーに表示される内容をより詳細に制御できます。タスクフィールドの標準セットのみを表示する代わりに、ユーザーに手元のタスクに合わせたエクスペリエンスを提供できます。このエクスペリエンスは、ワークフロー固有のフィールドのセットや、ユーザーがワークフローを最初から最後まで説明するためのステップバイステップガイダンスである場合があります。これを実現するには、Teams アプリをタスクと統合し、これらのタスクをプログラムで作成します。

たとえば、organizationのユーザーは Teams アプリを使用して、検査を追跡して完了するとします。この検査アプリをタスクと統合して、システムで追跡される検査ごとにPlannerタスクが作成されるようにすることができます。

ユーザーが Teams のPlanner アプリからこれらのタスクのいずれかを開くと、検査アプリを利用して検査エクスペリエンスに直接ジャンプするためのボタンが表示された簡略化された画面が表示されます。
タスクを完了し、検査エクスペリエンスを閉じると、開始したPlannerに戻ります。

ユーザーは、Teams アプリが割り当てられたタスク内から直接提供するカスタマイズされたエクスペリエンスを取得します。作業を完了するために別のアプリに移動する必要や、タスクを操作するときにどこにいたかのコンテキストを失う必要はありません。

ユーザーがタスクを完了した場合のこれらの利点に加えて、アプリを利用したタスク機能を使用すると、組織は必要な基幹業務プロセスとワークフローをタスクとして反映できるため、従業員は自分が責任を負うすべての作業を 1 か所から見ることができます。

このエクスペリエンスは、Teams Web、デスクトップ、モバイル上のPlanner アプリでサポートされています。次の要件を満たす Teams アプリを使用して、ユーザーに合わせたタスクエクスペリエンスを提供できます。

要件

アプリを利用するタスクは、プログラムによるタスクの作成と管理に依存する機能拡張機能です。この機能を使用する要件は次のとおりです。

各アプリを利用するタスクは、移行先の Teams アプリのエクスペリエンスを指し示しています。この場合、そのエクスペリエンスへの参照 URL を指定する必要があります。この参照 URL は、ユーザーが操作する必要がある特定の項目または画面を指すようお勧めします。この参照 URL は、特定の方法でタスクに追加する必要があります。詳細については、この記事の「手順 1: 参照 URL を構成する」セクションを参照してください。
タスクは、Microsoft Graph のビジネスシナリオ API を使用して作成および更新する必要があります。
タスクを操作する必要があるユーザーは、Teams 管理センターで設定したアプリポリシーに従って、Teams の移行先アプリにアクセスできる必要があります。詳細については、「 Teams 管理センターでのアプリ管理とガバナンスの概要」を参照してください。
移行先の Teams アプリは、次のアクションを含むタスクライフサイクルの管理を担当します。
- タスクを作成します。「BusinessScenarioTask の作成」を参照してください。
- タスクを割り当てます。「businessScenarioTask を更新する」を参照してください。
- プロパティが変更された場合は、タスクを更新します。「businessScenarioTask を更新する」を参照してください。
- すべての手順が完了したら、タスクを完了済みとしてマークします。「businessScenarioTask を更新する」を参照してください。
- タスクを削除します。「businessScenarioTask を削除する」を参照してください。

この機能を使用すると、一部のワークフローに決定的なフローがない可能性があるため、移行先の Teams アプリでタスクのライフサイクルを管理できます。その結果、Planner アプリでは、必要なすべての手順が完了したかどうかがわかりません。たとえば、検査中の検索によって、検査にさらに複数のステップが含まれる場合があります。同様に、ユーザーはタスクフィールドを更新したり、タスクを完了済みとしてマークしたりできません。これらのアクションにより、ユーザーが移行先の Teams アプリに反映されているものと競合する変更を加える可能性があります。

アプリを利用したタスクを作成する

このセクションでは、 Create businessScenarioTask API を使用してアプリを利用するタスクを作成する方法について説明します。

次の HTTP POST 要求を使用します。指定したプロパティのプレースホルダーを使用して、要求の外観を次に示します。

要求

POST https://graph.microsoft.com/beta/solutions/businessScenarios/{your-business-scenario-ID}/planner/tasks 

{ 
"title": "{Task title}", 
    "target": { 
        "@odata.type": "#microsoft.graph.businessScenarioGroupTarget", 
        "taskTargetKind": "group", 
        "groupId": "{group ID of the team where you want to create the task}" 
    }, 
    "businessScenarioProperties": { 
        "externalObjectId": "{any unique ID, for example, the ID of the object in your destination app}", 
        "externalBucketId": "{any bucket ID from planConfiguration of your business scenario}" 
    }, 
    "assignments": { 
        "{user ID of user you want to assign the task to}": { 
            "@odata.type": "#microsoft.graph.plannerAssignment", 
            "orderHint": " !" 
        } 
    }, 
    "details": { 
        "references": { 
            "{reference URL}": { 
                "@odata.type": "microsoft.graph.plannerExternalReference", 
                "alias": "{destination app name}", 
                "previewPriority": " !", 
                "type": "TeamsHostedApp" 
            } 
       } 
    } 
}

次のセクションでは、要求を形成する方法について詳しく説明します。

要求でプロパティを定義する方法

特定の種類の添付ファイルは、アプリを使用するタスクを標準タスクと区別します。添付ファイルの種類は TeamsHostedApp である必要があり、Teams アプリの移行先エクスペリエンスへの特別な形式のリンク (参照 URL) が含まれている必要があります。これは、タスクがアプリを使用するタスクであることをPlannerすることを意味します。

API では、これらの添付ファイルが参照として参照されていることに注意してください。

最初に、宛先エクスペリエンスを指す参照 URL を構成します。次に、参照 URL と、要求本文の添付ファイルに必要なその他のプロパティを指定します。

手順 1: 参照 URL を構成する

参照 URL では、特定の形式が使用されます。 URL を構築してエンコードするには、次の手順に従います。

手順 1a: URL を作成する

変換先エクスペリエンスへの参照 URL では、次の形式で Stageview モーダルリンク構文を使用する必要があります。

https://teams.microsoft.com/l/stage/{Teams-app-Id}/0?context={"contentUrl":"URL-to-destination-experience"},"name":"{page-title}","openMode":"modal"}

参照 URL を作成するには、次のパラメーターを指定します。

パラメーター	説明
`Teams-app-Id`	タスクと統合している Teams アプリのアプリ ID。
`URL-to-destination-experience`	ユーザーがタスクを開くときに表示する対象の Teams アプリのターゲットエクスペリエンスを指す URL。セキュリティ上の理由から、URL は Teams アプリに関連付けられている有効なドメインを指す必要があります。これは、指定したアプリ ID によって表されます。
`page-title`	ユーザーが宛先エクスペリエンスの URL を表示したときに画面の上部に表示されるタイトル。

エンコード前の参照 URL の例を次に示します。

https://teams.microsoft.com/l/stage/com.microsoft.teamspace.tab.youtube/0?context={"contentUrl":"https://tabs.teams.microsoft.com/youtubeContentStage?videoId=HBGmSy1iVmY","name":"Security%20talk","openMode":"modal"}

この例では、

Teams-app-Id は、Teams (com.microsoft.teamspace.tab.youtube) の YouTube アプリのアプリ ID です。ほとんどの Teams アプリ ID は英数字であり、外観が異なる可能性があることに注意してください。
URL-to-destination-experience は、移行先の Teams アプリ (https://tabs.teams.microsoft.com/youtubeContentStage?videoId=HBGmSy1iVmY) 内のエクスペリエンスを指します。
page-title は、URL を読み込むときに画面タイトル (Security talk) の名前です。

Teams の YouTube アプリを利用できる場合は、この URL を自分に送信して開くことを確認できます。

手順 1b: URL をエンコードする

参照 URL は、添付ファイルで使用する前にエンコードする必要があります。パーセントエンコードにより、リンクがプログラムで使用できる互換性のある形式になります。

参照 URL をエンコードするには、次の手順に従います。前に説明した参照 URL の例を使用して、URL をエンコードする方法を示します。

0?context=後の URL の部分をエンコードする割合。 https://または= (等しい記号)、またはその間の文字はエンコードしないでください。

https://teams.microsoft.com/l/stage/com.microsoft.teamspace.tab.youtube/0?context=%7B%22contentUrl%22%3A%22https%3A%2F%2Ftabs.teams.microsoft.com%2FyoutubeContentStage%3FvideoId%3DHBGmSy1iVmY%22%2C%22name%22%3A%22Security%2520talk%22%2C%22openMode%22%3A%22modal%22%7D

先端

これは、Teams チャットでリンクを簡単に検証できる最後の手順です。この手順を完了したら、Teams チャットで自分に送信することで URL をテストできます。リンクは、Teams の移行先アプリにアクセスできるユーザーの Teams デスクトップ、Web、またはモバイルで開く必要があります。
参照 URL 内のすべての. 文字を %2Eに置き換えます。これは、参照 URL 内のすべての文字で、最初から最後まで行う必要があります。この手順をスキップすると、参照 URL が機能しない可能性があります。

次の URL は、プログラムで使用する準備ができています。

https://teams%2Emicrosoft%2Ecom/l/stage/com%2Emicrosoft%2Eteamspace%2Etab%2Eyoutube/0?context=%7B%22contentUrl%22%3A%22https%3A%2F%2Ftabs%2Eteams%2Emicrosoft%2Ecom%2FyoutubeContentStage%3FvideoId%3DHBGmSy1iVmY%22%2C%22name%22%3A%22Security%2520talk%22%2C%22openMode%22%3A%22modal%22%7D

注意

URL が Power App を指している場合は、Power Apps でシングルサインオン (SSO) を機能させる &source=teamstab パラメーターと、 &skipMobileRedirect=1 パラメーターが含まれていることを確認して、ユーザーにスタンドアロン Power App プレーヤーを開くよう求める画面をスキップします。

手順 2: 添付ファイルを定義する

添付ファイルを定義するには、要求本文の "references" で次のプロパティを指定します。

        "references": { 
            "{reference-URL}": { 
            "@odata.type": "microsoft.graph.plannerExternalReference", 
            "alias": "{destination app name}", 
            "previewPriority": " !", 
            "type": "TeamsHostedApp" 
         } 
       }

プロパティ	説明
`reference-URL`	Stageview モーダルリンク構文の宛先エクスペリエンスへの URL。 URL を構築およびエンコードする方法の詳細については、この記事の「手順 1: 参照 URL を構成する」セクションを参照してください。
`alias`	Teams アプリの名前。ユーザーがタスクを開くと、" <alias> でこのタスクを完了しタスクの開始ボタンをクリックして移動先のエクスペリエンスにジャンプするメッセージが表示されます。
`previewPriority`	`!`のままにします。
`type`	[ `TeamsHostedApp`] に設定します。これは、タスクがアプリを使用するタスクであることをPlanner意味します。

例

この例では、"セキュリティプラクティスのプレゼンテーションを確認する" という名前のアプリを使用したタスクを作成し、それを Adele Vance (ユーザー ID 44ee44ee-ff55-aa66-bb77-88cc88cc) という名前のユーザーに割り当てる方法を示します。この要求では、「手順 1: この記事の参照 URL を構成する」セクションの参照 URL の例を使用します。

要求

POST https://graph.microsoft.com/beta/solutions/businessScenarios/ccd5aa8aebd048bd839a4fa5b7420631/planner/tasks

{
"title": "Review security practices presentation",
    "target": {
        "@odata.type": "#microsoft.graph.businessScenarioGroupTarget",
        "taskTargetKind": "group",
        "groupId": "769bbf41-70b7-4ea6-a044-a7037358883e"
    },
    "businessScenarioProperties": {
        "externalObjectId": "SP-202418",
        "externalBucketId": "Security practices"
    },
    "assignments": {
        "44ee44ee-ff55-aa66-bb77-88cc88cc88cc": {
            "@odata.type": "#microsoft.graph.plannerAssignment",
            "orderHint": " !"
        }
    },
    "details": {
        "references": {
            "https://teams%2Emicrosoft%2Ecom/l/stage/com%2Emicrosoft%2Eteamspace%2Etab%2Eyoutube/0?context=%7B%22contentUrl%22%3A%22https%3A%2F%2Ftabs%2Eteams%2Emicrosoft%2Ecom%2FyoutubeContentStage%3FvideoId%3DHBGmSy1iVmY%22%2C%22name%22%3A%22Security%2520talk%22%2C%22openMode%22%3A%22modal%22%7D": {
                "@odata.type": "microsoft.graph.plannerExternalReference",
                "alias": "Security practices presentation",
                "previewPriority": " !",
                "type": "TeamsHostedApp"
             }
        }
    }
}

注意

この参照 URL の例は、多くの組織の環境で使用できるアプリを使用して、アプリを使用したタスクエクスペリエンスを簡単にテストする方法として選択されました。この参照 URL の例では、ユーザーはタスクを完了できないことに注意してください。これは、YouTube アプリがアプリを利用するタスクと統合されておらず、ビデオの再生後にタスクが完了したことを示す API 呼び出しを行わないためです。

Planner アプリの外観

Teams のPlanner アプリでタスクを開くと、ユーザーに表示される内容を次に示します。 [タスクの開始] ボタンを選択すると、ユーザーは Teams アプリの移行先エクスペリエンスに移動します。この例では、宛先エクスペリエンスは Teams の YouTube アプリのセキュリティプラクティスビデオです。

ユーザーエクスペリエンスの詳細については、「Teams のPlanner アプリでアプリを使用したタスクを操作する」を参照してください。

次の方法で共有

Plannerでアプリを利用したタスクを管理して、カスタマイズされたタスクエクスペリエンスを実現する

概要

要件

アプリを利用したタスクを作成する

要求でプロパティを定義する方法

手順 1: 参照 URL を構成する

手順 1a: URL を作成する

手順 1b: URL をエンコードする

手順 2: 添付ファイルを定義する

例

Planner アプリの外観

フィードバック

その他のリソース

次の方法で共有

Plannerでアプリを利用したタスクを管理して、カスタマイズされたタスク エクスペリエンスを実現する

概要

要件

アプリを利用したタスクを作成する

要求でプロパティを定義する方法

手順 1: 参照 URL を構成する

手順 1a: URL を作成する

手順 1b: URL をエンコードする

手順 2: 添付ファイルを定義する

例

Planner アプリの外観

関連記事

フィードバック

その他のリソース

Plannerでアプリを利用したタスクを管理して、カスタマイズされたタスクエクスペリエンスを実現する