向 Microsoft Teams 中的用户发送活动源通知

项目
11/14/2023

Microsoft Teams 活动源使用户能够通过通知更改来对需要注意的项目进行会审。可以使用 Microsoft Graph 中的活动源通知 API 将此功能扩展到应用。这允许你的应用提供更丰富的体验，并通过帮助用户及时了解他们所使用的工具和工作流的更改，从而更好地吸引用户。

活动源通知的用例

新闻：帮助用户随时了解最新信息，例如新作业或新帖子。
协作：在评论中共享文件或 @ 提及用户时，用户可以在通知横幅中看到文本预览。
提醒：通知，用于通知事件或任务。例如，你今天有一个训练截止日期，应用会向你发送提醒通知，以帮助你记住任务或事件。
警报：需要紧急或立即关注的通知。例如，培训的截止日期已过，或者管理员发送了修复优先级最高的 bug 的请求。

活动源通知的优点

活动源通知是一种本机 Teams 集成，可让用户无缝地进入选项卡应用，从而将活动中的其他用户参与度引入应用。
活动源通知在 Teams 桌面和移动客户端中附带 OS 通知，以便从系统弹出窗口和声音中获取用户的注意力。
通知内容高度可自定义，允许用户预览通知事件的摘要。
你可以将应用深层链接到通知，以便在用户选择通知时，它会增加用户应用参与度。
可以向各种收件人发送活动源通知。例如，向一组用户发送个人通知或发送批通知。
应用清单 (以前称为 Teams 应用清单) 本地化支持活动源通知中的模板化文本。

了解活动源通知的基础知识

在 Teams 中，活动源通知由多个信息位一起显示，如下图所示：

组件包括：

计数器	说明
1	虚拟形象：显示发起活动的人员。
2	活动类型或应用图标：活动类型或应用图标描述活动类型。对于应用通知，行图标将替换为应用图标。
3	标题：执行组件 + 原因：执行组件：启动活动的用户或应用的名称。原因：描述活动。
4	时间戳：显示活动发生时间。
5	文本预览：显示通知开头的截断行。
6	位置：显示活动在 Teams 中发生的位置。

以下示例演示这些组件一起提供有关通知的详细信息。

活动源通知卡的类型

以下变体显示了可以显示的活动源通知卡的类型。应用徽标替换应用生成的通知的用户头像：

桌面设备
移动设备

计数器	说明
1	Teams 自定义
2	Windows
3	Mac

计数器	说明
1	Android
2	iOS

使用活动源通知 API 的要求

活动源 API 可与 Teams 应用配合使用。以下是发送活动源通知的要求：

应用清单必须向节添加 webApplicationInfo Microsoft Entra 应用 ID。有关详细信息，请参阅应用清单架构。
可以发送活动通知，无论是否在应用清单中添加活动类型。
- 默认情况下，可以使用活动通知 API，而无需在应用清单中添加 activities 节。活动 systemDefault 类型是保留的，这样就可以在活动源通知的行中 Actor+Reason 提供自由格式的文本。有关详细信息，请参阅发送可自定义的活动源通知。
  
  注意
  
  活动 systemDefault 类型仅在公共开发人员预览版中可用。
- 如果要在传统模式下发送模板化通知， activityTypes 则必须在活动部分中添加属性。有关详细信息，请参阅应用清单架构。
必须为收件人安装 Teams 应用，无论是个人安装，还是在他们所属的团队或聊天中。

权限

使用委托权限或应用程序权限发送活动源通知。使用应用程序权限时，建议使用特定于资源的许可 (RSC) ， TeamsActivity.Send.User 因为用户同意发送活动通知的权限。确保在应用清单文件中添加 RSC 权限。

应用清单更新

本部分介绍需要添加到应用清单的更新。确保使用应用清单版本 1.7 或更高版本。

"$schema": "https://developer.microsoft.com/json-schemas/teams/v1.7/MicrosoftTeams.schema.json",
"manifestVersion": "1.7",

webApplicationInfo 更新

"webApplicationInfo":
{
    "id": "a3111f15-658e-457c-9689-fd20fe907330",
    "resource": "https://contosoapp.com"
}

参数	类型	说明
`id`	string	Microsoft Entra 应用 ID (客户端 ID) 。
`resource`	string	与 Microsoft Entra 应用关联的资源。在 Azure 门户中也称为回复或重定向 URL Microsoft。

注意

如果同一范围内的多个 Teams 应用 (团队、聊天或用户) 使用相同的Microsoft Entra 应用，则可能会出现错误。请确保使用唯一Microsoft Entra 应用。

活动更新

"activities":
{
  "activityTypes": [
    {
      "type": "taskCreated",
      "description": "Task Created Activity",
      "templateText": "{actor} created task {taskId} for you"
    },
    {
      "type": "approvalRequired",
      "description": "Deployment requires your approval",
      "templateText": "{actor} created a new deployment {deploymentId}"
    }
  ]
}

参数	类型	说明
类型	string	活动的类型。这在特定应用清单中必须是唯一的。
说明	string	人类可读的简短说明。这在 Teams 客户端上可见。
templateText	string	活动通知的模板文本。可以通过在中 `{}`封装参数来添加参数。

注意

actor是始终采用调用方名称的特殊参数。在委托调用中， actor 是用户的名称。在仅限应用程序的调用中，它采用 Teams 应用的名称。
保留 systemDefault 的活动类型不得包含在 activities 应用清单的部分中。活动 systemDefault 类型允许你在活动源通知的行中 Actor+Reason 提供自由格式的文本。

授权更新

"authorization": 
{ 
  "permissions": { 
    "resourceSpecific": [ 
      {
        "type": "Application", 
         "name": "TeamsActivity.Send.User" 
      }, 
      { 
        "type": "Application",
        "name": "TeamsActivity.Send.Group"
      }, 
      { 
        "type": "Application", 
        "name": "TeamsActivity.Send.Chat" 
      } 
    ] 
  }
}

参数	类型	说明
类型	string	RSC 权限的类型。
name	string	RSC 权限的名称。有关详细信息，请参阅支持的 RSC 权限。

安装 Teams 应用

Teams 应用必须安装在团队、聊天或个人范围内的用户中，用户才能接收活动源通知。有关详细信息，请参阅 Teams 应用分发方法。出于开发目的，我们更喜欢自定义应用上传。开发后，可以根据是要分发到一个租户还是所有租户来选择正确的分发方法。

还可以使用 Teams 应用安装 API 来管理 Teams 应用安装。

向用户发送活动源通知

由于 Teams 应用可以为用户安装、在团队中或在聊天中安装，因此它还可以在以下三个上下文中发送通知：

此外，一次最多可以向 100 个用户批量发送通知：

批量向多个用户发送通知

若要查找有关每个方案支持的主题的详细信息，请参阅特定 API。所有方案都支持基于文本的自定义主题。

可以在以下方案中使用活动源通知：

通知个人需要注意的自定义内容。
在 Tab 应用或 URL 中显示丰富内容。
支持复杂的用户交互。
从发起通知的用户发送委托的通知。
将模板放入应用清单中。
Teams 处理通知的本地化。

注意

活动图标基于发出请求的上下文。如果使用委派的权限发出请求，则用户的照片显示为头像，而 Teams 应用图标显示为活动图标。在仅限应用程序的上下文中，Teams 应用图标用作头像，并省略活动图标。

自定义通知

Teams 用户可以自定义他们在源或横幅中看到的通知。还可以自定义通过活动源 API 生成的通知。用户可以选择如何通过 Teams 中的设置来通知他们。 Teams 应用显示在供用户选择的列表中，如以下屏幕截图所示：

用户可以选择应用旁边的 “编辑” 并自定义通知。应用清单显示字段 description 。

示例

有关如何发送活动源通知的示例，请参阅发送活动源通知示例。

用于发送活动源通知的保留活动类型

活动 systemDefault 类型是保留的，在添加活动时不能在应用清单中使用。
我们建议使用模板化通知，因为它们依赖于应用清单中的活动模板来定期发送和大量通知。
systemDefault即使应用清单中列出了其他活动类型，保留活动类型也可用。

活动类型的优点和限制 systemDefault 如下：

优点	限制
可以测试新方案并试用活动源通知 API，而无需将活动类型添加到应用清单。使用 Teams 应用商店应用时 `systemDefault` ，活动类型简化了流程并节省时间，因为它无需对应用清单中的活动类型进行持续调整。活动 `systemDefault` 类型已准备就绪，可立即使用。	不能利用应用清单提供的内置本地化功能。不能依赖使用活动类型发送可自定义通知 `systemDefault` 。用户可以使用 Teams 客户端设置中的切换开关关闭应用的所有通知，这可能会阻碍应用与其用户之间的通信。

代码示例

示例名称	Description	.NET	Node.js
发送活动源通知	示例应用演示如何使用 Microsoft 图形 API 发送活动源通知。	View	View

分步指南

按照分步指南在 Teams 中发送活动源通知。

通过