在 Planner 中管理应用支持的任务，以定制任务体验

项目
12/20/2024
适用于:

Microsoft Teams

注意

此功能目前为公共预览版。

概述

应用支持的任务功能可让你的组织更好地控制用户在 Microsoft Teams 中的 Planner 应用中打开任务时看到的内容。你可以为用户提供针对手头任务定制的体验，而不是仅显示一组标准任务域。该体验可能是一组特定于工作流的字段或分步指南，用于引导用户从头到尾完成工作流。为此，请将 Teams 应用与任务集成，然后以编程方式创建这些任务。

例如，组织中的用户使用 Teams 应用来跟踪和完成检查。可以将此检查应用与任务集成，以便为系统中跟踪的每个检查创建Planner任务。

当用户从 Teams 中的 Planner 应用打开其中一个任务时，他们会看到一个简化的屏幕，其中包含一个按钮，用于直接跳转到由检查应用提供支持的检查体验。
完成任务并关闭检查体验后，他们就回到了开始Planner。

用户直接从其分配的任务中获取 Teams 应用提供的定制体验。他们不必导航到其他应用即可完成工作或丢失处理任务时所处的位置的上下文。

除了用户完成任务时的这些好处外，应用支持的任务功能还允许组织将所需的业务流程和工作流反映为任务，以便员工可以从一个位置查看他们负责的所有工作。

Teams Web、桌面和移动设备上的 Planner 应用中支持此体验。可以使用满足以下要求的任何 Teams 应用为用户提供定制的任务体验。

要求

应用支持的任务是一项扩展性功能，它依赖于以编程方式创建和管理任务。使用此功能的要求如下。

每个应用支持的任务都指向目标 Teams 应用中的体验，这要求你提供该体验的参考 URL。建议将此引用 URL 指向用户应处理的特定项或屏幕。必须以特定方式将此引用 URL 添加到任务。若要了解详细信息，请参阅本文的步骤 1：配置参考 URL 部分。
必须使用 Microsoft Graph 中的业务方案 API 创建和更新任务。
需要处理任务的用户必须有权访问 Teams 中的目标应用，这受你在 Teams 管理中心中设置的应用策略的约束。若要了解详细信息，请参阅 Teams 管理中心中的应用管理和治理概述。
目标 Teams 应用负责管理任务生命周期，其中包括以下操作：
- 创建任务。请参阅创建 businessScenarioTask。
- 分配任务。请参阅更新 businessScenarioTask。
- 如果属性发生更改，请更新任务。请参阅更新 businessScenarioTask。
- 完成所有步骤后，将任务标记为“已完成”。请参阅更新 businessScenarioTask。
- 删除任务。请参阅 Delete businessScenarioTask。

此功能允许目标 Teams 应用控制任务生命周期，因为某些工作流可能没有确定性流。因此，Planner应用不知道是否完成了所有必需的步骤。例如，检查过程中的发现可能会导致在检查中包含更多步骤。同样，用户无法更新任务字段或将任务标记为已完成。这些操作可能会导致用户做出与目标 Teams 应用中反映的内容冲突的更改。

创建应用驱动的任务

本部分介绍如何使用创建 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 ，并且必须包含特殊格式的链接， (引用 URL) Teams 应用中的目标体验。这表示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 发送给自己来测试该 URL。此链接应在 Teams 桌面、Web 或移动设备上打开，供有权访问 Teams 中目标应用的任何用户打开。
. 将引用 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，请确保它包含 &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`	在 Stageview 模式链接语法中指向目标体验的 URL。有关如何构造和编码 URL 的详细信息，请参阅本文的步骤 1：配置引用 URL 部分。
`alias`	Teams 应用的名称。当用户打开任务时，他们会看到一条消息，上面写着“以别名>完成<此任务”，以及一个用于跳转到目标体验的“开始任务”按钮。
`previewPriority`	保留为 `!`。
`type`	设置为 `TeamsHostedApp`。这表示Planner任务是应用驱动的任务。

示例

此示例演示如何创建名为“查看安全做法演示文稿”的应用驱动的任务，并将其分配给名为 Adele Vance 的用户 (用户 ID 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 应用中的外观

相关文章

反馈

其他资源