在 Planner 中管理由應用程式提供的工作，以獲得量身打造的工作體驗

發行項
12/20/2024
適用於:

Microsoft Teams

注意事項

這項功能目前處於公開預覽中。

概觀

由應用程式提供的工作功能可讓貴組織進一步控制使用者在Teams內 Planner 應用程式中開啟工作時會看到的內容Microsoft。您可以為使用者提供量身打造的工作體驗，而不是只顯示標準一組任務欄位。該體驗可能是工作流程特定的一組字段，或逐步引導使用者從頭到尾的工作流程。若要達成此目標，您可以整合 Teams 應用程式與工作，並以程式設計方式建立這些工作。

例如，假設貴組織中的使用者使用 Teams 應用程式來追蹤並完成註冊。您可以將這個示範應用程式與工作整合，以便為系統中追蹤的每一個檢查建立 Planner 工作。

當使用者從 Teams 中的 Planner 應用程式開啟其中一個工作時，會看到簡化的畫面，其中有一個按鈕可直接跳到由您的檢查應用程式提供的檢查體驗。
當他們完成工作並關閉封存體驗時，會直接回到開始 Planner 位置。

用戶可從 Teams 應用程式指派的工作內取得量身打造的體驗。他們不需要流覽至不同的應用程式，就能完成工作，或遺失工作所在位置的內容。

除了使用者完成工作時的這些優點之外，應用程式提供的工作功能還可讓組織將必要的企業營運程式和工作流程反映為工作，讓員工可以從單一位置查看他們負責的所有工作。

Teams 網頁版、桌面版和行動裝置版的 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 Modal 連結語法：

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 應用程式的應用程式識別碼。
`URL-to-destination-experience`	指向目的地 Teams 應用程式中目標體驗的 URL，可讓用戶在開啟工作時看到。基於安全性考慮，URL 必須指向與 Teams 應用程式相關聯的有效網域，該網域是由您提供的應用程式識別符表示。
`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 應用程式的應用程式識別碼。請記住，大部分的Teams應用程式標識碼都是英數位元，看起來可能不同。
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。

編碼後接 URL 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 聊天中將 URL 傳送給自己，藉此測試 URL。鏈接應該會在 Teams 桌面、網頁或行動裝置上開啟，以供在 Teams 中存取目的地應用程式的任何使用者使用。
將參照網址中 的所有. 字元取代為 %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，請確定它包含 &source=teamstab 讓單一登錄 (SSO) 適用於 Power Apps 的參數，並 &skipMobileRedirect=1 略過提示使用者開啟獨立 Power App 播放程式的畫面。

步驟 2：定義附件

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

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

屬性	描述
`reference-URL`	目的地體驗的 URL，在 Stageview Modal 連結語法中。如需如何建構及編碼 URL 的詳細數據，請參閱本文的步驟 1：設定參照 URL 一節。
`alias`	Teams 應用程式的名稱。當用戶開啟工作時，他們會看到一則訊息，指出「以 <別>名完成這項工作，以及跳至目的地體驗的 [開始] 工作按鈕。
`previewPriority`	請保留為 `!`。
`type`	設定為 `TeamsHostedApp`。這表示要 Planner 該工作是由應用程式提供的工作。

範例

此範例示範如何建立名為「檢閱安全性做法簡報」的由應用程式提供的工作，並將它指派給名為 Adele Vance (用戶標識碼 44ee44ee-ff55-aa66-bb77-88cc88cc88cc) 的使用者。此要求使用本文步驟 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 應用程式中的外觀

相關文章

意見反應

其他資源