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

發行項
11/15/2024
適用於:

Microsoft Teams

注意事項

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

概觀

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

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

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

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

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

Teams 網頁版、桌面版和行動裝置版的 Planner 應用程式支援此體驗。您可以更新任何 Teams 應用程式，以建立由應用程式提供的工作，並為您的使用者提供量身打造的工作體驗。

需求

以應用程式提供的工作是一項擴充功能功能，它仰賴以程序設計的方式建立和管理工作。使用此功能的需求如下所示。

每個由應用程式提供的工作都必須有參照URL，指出目的地Teams應用程式中的體驗。我們建議您將此參照 URL 指向用戶應該使用的特定項目或畫面。此參照 URL 必須以特定方式新增至工作。 To learn more, see the Configure the reference URL section of this article.
您必須使用 Microsoft Graph 中的商務案例 API 來建立和更新工作。
需要處理工作的用戶必須有權存取 Teams 中的目的地應用程式，這受到您在 Teams 系統管理中心設定的應用程式原則所規範。若要深入瞭解，請參閱 Teams 系統管理中心的應用程式管理和控管概觀。
目的地 Teams 應用程式負責管理任務生命週期，其中包含下列動作：
- 建立工作。請參閱建立 businessScenarioTask。
- 指派工作。請參閱更新 businessScenarioTask。
- 如果屬性變更，請更新工作。請參閱更新 businessScenarioTask。
- 完成所有步驟時，將工作標示為已完成。請參閱更新 businessScenarioTask。
- 刪除工作。請參閱刪除 businessScenarioTask。
  
  這項功能可讓目的地 Teams 應用程式控制任務的生命週期，因為某些工作流程可能沒有決定性流程。因此，Planner 應用程式不知道是否已完成所有必要的步驟。例如，在檢查期間尋找，可能會導致在檢查中包含多個步驟。同樣地，用戶無法更新工作欄位或將工作標示為已完成。這些動作可能會導致用戶進行與目的地 Teams 應用程式中所反映內容相衝突的變更。

建立由應用程式提供的工作

本節說明如何使用 Create businessScenarioTask API 來建立由應用程式提供的工作。

請使用下列 HTTP POST 要求，您的商務案例識別碼在哪裡 {your-business-scenario-ID} 。

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

下列顯示要求，其中包含您在要求內文中指定之屬性的佔位元。

請求

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 team}" 
    }, 
    "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" 
            } 
       } 
    } 
}

定義附件

應用程式支援的工作與標準工作的區別在於特定附件的目前狀態。附件包含連結 (參照 Teams 應用程式中目的地體驗的 URL) ，可讓 Planner 將任務辨識為由應用程式供電的工作。

請記住，API 會將這些附件作為參照。

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

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

屬性	描述
`reference-URL`	目的地體驗的 URL，在 Stageview Modal 連結語法中。 For details on how to format and encode the URL, see the Configure the reference URL section of this article.
`alias`	Teams 應用程式的名稱。當用戶開啟工作時，他們會看到一則訊息，指出「以 <別>名完成這項工作，以及跳至目的地體驗的 [開始] 工作按鈕。
`previewPriority`	請保留為 `!`。
`type`	設定為 `TeamsHostedApp`。

設定參照 URL

設定 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。 URL 網域必須是應用程式識別碼的有效網域。
`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 給自己並確認它開啟。

編碼參照 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 播放程式的畫面。

範例

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

共用方式為

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

概觀

需求

建立由應用程式提供的工作

定義附件

設定參照 URL

設定 URL 格式

編碼參照 URL

範例

Planner 應用程式中的外觀

意見反應

其他資源

共用方式為

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

概觀

需求

建立由應用程式提供的工作

定義附件

設定參照 URL

設定 URL 格式

編碼參照 URL

範例

Planner 應用程式中的外觀

相關文章

意見反應

其他資源