在 Planner 中管理應用程式驅動的任務，打造量身打造的任務體驗

概觀

這個由應用程式驅動的任務功能，讓組織能更精確地控制用戶在 Microsoft Teams 中 Planner 應用程式開啟任務時看到的內容。 你不只顯示標準的任務欄位，而是能提供針對當前任務量身打造的體驗。 這種體驗可能是針對工作流程的欄位，或是逐步引導使用者從頭到尾完成工作流程。 為了達成這個目標，你會將 Teams 應用程式與任務整合，並以程式化方式建立這些任務。

舉例來說，你們組織中的用戶使用 Teams 應用程式來追蹤並完成檢查。 你可以將這個檢查應用程式與任務整合，讓系統中追蹤的每個檢查都能建立一個規劃工具任務。

• 當使用者在 Teams 的 Planner 應用程式開啟這些任務時，會看到一個簡化的畫面，並有一個按鈕可以直接跳到由你的檢查應用程式驅動的檢查體驗。
• 當他們完成任務並結束檢查體驗時，會回到起點的 Planner。

使用者能直接從分配任務中獲得 Teams 應用程式所提供的量身打造體驗。 他們不必切換到其他應用程式來完成工作，也不會忘記自己在執行任務時的狀況。

除了用戶完成任務時的這些好處外，應用程式驅動的任務功能讓組織能將所需的業務流程與工作流程反映為任務，讓員工能從單一地點看到所有他們負責的工作。

此體驗在 Teams 網頁版、桌面版及行動裝置的 Planner 應用程式中皆有支援。 您可以使用任何符合以下需求的 Teams 應用程式，為使用者提供量身訂做的任務體驗。

需求

應用程式驅動任務是一種依賴程式化創建與管理任務的擴充性功能。 使用此功能的條件如下。

• 每個由應用程式驅動的任務都會指向目的地 Teams 應用程式中的一個體驗，而該體驗需要你提供該體驗的參考網址。 我們建議您將此參考網址指向使用者應該處理的特定項目或畫面。 這個參考網址必須以特定方式加入任務中。 欲了解更多，請參閱本文的第一 步：設定參考網址 章節。

• 任務必須透過 Microsoft Graph 中的 商業情境 API 建立並更新。

• 需要處理任務的使用者必須能在 Teams 中存取目標應用程式，這取決於你在 Teams 管理中心設定的應用程式政策。 欲了解更多，請參閱 Teams 管理中心的應用程式管理與治理概述。

• 目的地 Teams 應用程式負責管理任務生命週期，包含以下動作：

  • 創造任務。 請參見 建立商業情境任務。
  • 指派任務。 請參見 Update businessScenarioTask。
  • 如果屬性改變，則更新任務。 請參見 Update businessScenarioTask。
  • 當所有步驟完成後，將任務標記為完成。 請參見 Update 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 應用程式中的目的地體驗。 這對 Planner 來說意味著該任務是由應用程式驅動的。

請記得 API 會將這些附件視為 參考。

首先，你設定參考網址指向目的地體驗。 接著，在請求主體中指定參考 URL 及附件所需的其他必要屬性。

步驟 1：設定參考網址

參考網址使用特定格式。 請依照以下步驟構建並編碼 URL。

步驟 1a：建立網址

目的地體驗的參考網址必須使用以下格式的 Stageview Modal 連結語法 ：

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

要構造參考網址，請指定以下參數。

以下是編碼前的參考網址範例：

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 是載入網址時 (Security talk) 的螢幕標題名稱。

如果你在 Teams 裡有 YouTube 應用程式，可以把這個網址傳給自己確認它是否開啟。

步驟 1b：編碼網址

你需要先編碼參考網址，才能在附件中使用。 百分比編碼確保連結格式相容，方便程式化使用。

請依照以下步驟編碼參考網址。 我們使用先前描述的範例參考 URL，示範如何編碼該 URL。

1. 百分比編碼網址後面 0?context=的部分。 不要編碼 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 聊天中傳給自己來測試該網址。 對於任何能在 Teams 中存取目標應用程式的用戶，該連結應該會在 Teams 桌面、網頁或行動裝置上開啟。

2. 將參考網址 中的所有. 字元替換為 %2E。 你必須從頭到尾對參考網址中的所有字元進行此操作。 如果你跳過這個步驟，參考網址可能無法使用。

   以下網址已準備好供程式化使用。

   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

   備註

   如果你的網址指向 Power App，請確保它包含 &source=teamstab 讓單一登入 (SSO) 在 Power Apps 上運作的參數，以及 &skipMobileRedirect=1 跳過提示使用者開啟獨立 Power App 播放器畫面的參數。

步驟二：定義附件

要定義附件，請在請求文中指定以下屬性 "references" 。

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

範例

這個範例展示了如何建立一個名為「檢視安全實務簡報」的應用程式驅動任務，並將其指派給一位名叫 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"
             }
        }
    }
}

這在 Planner 應用程式中的樣子

以下是使用者在 Teams 的 Planner 應用程式中開啟任務時看到的內容。 選擇 開始任務 按鈕會帶使用者進入 Teams 應用程式中的目的地體驗。 在這個例子中，目的地體驗是在 Teams 的 YouTube 應用程式中播放的安全實務影片。

想了解更多使用者體驗，請參閱 Teams 中 Planner 應用程式中「處理應用程式驅動任務」。

相關文章

• 使用 Microsoft Graph 中的商業情境 API 來整合 Planner
• 在 Microsoft Teams 中管理您組織的 Planner 應用程式