实用图表：使用 Teams 消息传递

在模块之间进行选择

Microsoft Teams PowerShell 模块的新版本通常会从 PowerShell 库生成数十万次下载。虽然下载次数并不代表使用情况，但可以合理地假设大多数下载该模块的人都使用它来管理 Teams。 Microsoft Graph PowerShell SDK 还包括与 Teams 配合使用的 cmdlet，例如 Get-MgTeam、Get-MgTeamChannel 等，其中许多重复的 cmdlet 可以在 Microsoft团队模块。考虑到重复，管理员应该采取哪条途径来自动化 Teams 操作？

答案并不简单，因为这取决于您想要做什么。以下是一些需要记住的要点：

• 这两个模块都有指向 Microsoft Graph 的链接。 Microsoft Teams 模块中的许多 cmdlet 都基于 Graph API，并且 Microsoft Graph PowerShell SDK 中的所有 cmdlet 均派生自 Graph API。
• Microsoft Teams 模块包括不基于图形 API 的其他 cmdlet。大多数是最初来自 Skype for Business 连接器的策略管理 cmdlet。
• Microsoft Graph PowerShell SDK 包括用于与其他 Microsoft 365 工作负载和 Entra ID 交互的 cmdlet。
• Microsoft Teams 模块旨在自动化管理操作。当由拥有全局管理员或团队管理员角色的帐户使用时，cmdlet 可以管理组织中的所有团队。
• Microsoft Graph PowerShell SDK 包含可与用户内容交互的 cmdlet，例如发布新聊天。与不同的 Teams 数据交互需要不同的权限。在访问数据时，开发人员还需要记住委派权限和应用程序权限之间的区别。

在大多数情况下，使用 Microsoft Teams 模块进行一般自动化会更容易，并在需要与用户数据交互（例如发布或删除聊天）时引入 Microsoft Graph PowerShell SDK，这正是我们在这里想要做的。

本文的其余部分介绍 Teams 消息传递的基础知识，并说明如何使用 Microsoft Graph PowerShell SDK 将消息发布到一对一聊天、群聊和频道对话。从通道中删除消息的过程将在另一篇文章中介绍。

关于权限的说明

您可能知道，用于 Graph API 请求的权限模型是基于最小权限的。在大多数情况下，应用程序权限可允许使用图形请求的应用程序作为后台进程运行，例如计划的 Azure 自动化作业。

没有应用程序权限可用于图形请求，例如将消息发布到聊天或频道对话，因此必须使用委派权限。该应用需要 ChannelMessage.Send 权限才能将消息发布到频道，并需要 Chat.Create 权限才能发布到聊天。获取消息需要更多权限（例如Chat.ReadWrite）。

由于缺乏应用程序权限，登录帐户必须是聊天或团队的成员才能发布消息，并且必须是团队所有者才能删除频道消息。无法使用 Azure 自动化托管标识，因为这些标识不能是团队或聊天的成员。

通常的解决方法是使用作为团队成员的实用程序帐户登录 Teams，并以这种方式发布到频道。过去，我使用存储在 Azure Key Vault 中的凭据使用 Submit-PnPTeamsChannelMessage cmdlet PnP 模块来完成此操作。相同的技术适用于此处介绍的 cmdlet。

聊天负载

Teams 支持一对一和群组聊天。第一个示例在两个租户帐户之间创建新的一对一聊天。 Microsoft 文档包含几个有关如何在聊天中发布消息的好示例。但是，我认为用于构造要发布到 Teams 的 JSON 有效负载的方法过于复杂，并且不适合编程操作。

因此，我采用不同的方法来定义和弹出构成有效负载的数组和哈希表。这与构建参数以将 Planner 任务发布到计划中的方法相同。如果您愿意，可以使用文档示例中采用的方法。它们很有效并且是很好的例子，但我认为我的方法更适合生产脚本。

创建并发布到一对一聊天

首先，我们定义一个包含聊天参与者帐户标识符的数组，以及包含用于创建聊天的有效负载（也称为请求正文）的哈希表。该代码还添加了一个参数来将聊天标识为一对一。您必须使用准确的格式 (onOnOne) 来识别聊天类型。

[array]$MemberstoAdd = "eff4cd58-1bb8-4899-94de-795f656b4a18", "cad05ccf-a359-4ac7-89e0-1e33bf37579e"
$OneOnOneChatBody = @{}
$OneOnOneChatBody.Add("chattype", "oneOnOne")

有效负载的其余部分定义聊天参与者。该数据在由两个哈希表组成的数组中传递。每个哈希表都保存有关聊天参与者的信息，其中之一必须是登录用户。如您所见，代码可以添加访客帐户作为聊天参与者。

$Members = @()
ForEach ($Member in $MemberstoAdd) {
    $User = Get-MgUser -UserId $Member -Property id, displayName, userType, userprincipalName
    $MemberId = ("https://graph.microsoft.com/v1.0/users('{0}')" -f $Member)
    $MemberDetails = @{}
    [array]$MemberRole = "owner"
    If ($User.userType -eq "Guest") {
        [array]$MemberRole = "guest"
    }
    $MemberDetails.Add("roles", $MemberRole.trim())
    $MemberDetails.Add("@odata.type", "#microsoft.graph.aadUserConversationMember")
    $MemberDetails.Add("[email protected]", $MemberId.trim())
    $Members += $MemberDetails
}
$OneOnOneChatBody.Add("members", $Members)

完整的有效负载如下所示：

$OneOnOneChatBody

Name                           Value
----                           -----
chattype                       oneOnOne
members                        {System.Collections.Hashtable, System.Collections.Hashtable}

我们现在可以运行 New-MgChat cmdlet 来创建聊天。如果两个参与者已存在聊天，Teams 将返回该聊天的聊天标识符。如果没有，Teams 会创建一个新聊天并返回该标识符，其值类似于 19:[email protected]。

$NewChat = New-MgChat -BodyParameter $OneOnOneChatBody
If ($NewChat) {
    Write-Host ("New chat {0} created" -f $NewChat.id)
} Else {
    Write-Host "Failed to create chat"
}

了解聊天标识符后，我们就可以运行 New-MgChatMessage cmdlet 将消息发布到聊天中。此代码创建一些 HTML 内容并将其发布到聊天中。

$Content = "<b><i>Using the Microsoft AuditLog Query Graph API (Preview)</b></i><p>"
$Content = $Content + "The unified audit log is the source of a lot of information about a Microsoft 365 tenant. The Search-UnifiedAuditLog cmdlet is available to search the audit log and now we have the AuditLog Graph API. This article explains how to use the new API to query and retrieve audit records from the log."
$Content = $Content + "<p>For more information, see <a href='https://practical365.com/audit-log-query-api/'>https://practical365.com/audit-log-query-api/</a>"

$ChatMessageBody = @{}
$ChatMessageBody.Add("contentType", "html")
$ChatMessageBody.Add("content", $Content) 
$ChatMessage = New-MgChatMessage -ChatId $NewChat.Id -Body $ChatMessageBody

图 1 显示了发布到聊天的消息。

创建并发布到群聊

群聊有 2 到 250 名参与者。它还可以有一个主题（标题）。为了演示如何将大量参与者添加到新的群聊中，此代码找到一个使用 af 过滤器作为特定显示名称的团队，并将其成员名册提取到用户帐户标识符数组中。它还为有效负载创建哈希表以创建新的聊天并填充聊天类型和主题：

$Members = @()
$Team = Get-MgTeam -Filter "displayName eq 'Information Quality and Accuracy'"
If ($Team) {
   [array]$TeamMembers = (Get-MgGroupMember -GroupId $Team.Id).Id 
}
# Create a new group chat
$GroupChatBody = @{}
$GroupChatBody.Add("chattype", "group")
$GroupChatBody.Add("topic", "Major Updates - Urgent News")

下一步创建一组哈希表来定义要添加到群聊的每个成员。就像一对一聊天一样，群聊的参与者之一必须是登录用户。由于它是预览功能，因此代码排除了从多租户组织同步的团队成员的帐户。最后，New-MgChat cmdlet 创建新的聊天。

ForEach ($Member in $TeamMembers) {
   $User = Get-MgUser -UserId $Member -Property id, displayName, userType, userprincipalName
   # Exclude MTO accounts
   If (($User.userprincipalName -notlike "*#EXT#*" -and $User.userType -eq "Member") -or $User.userType -eq "Guest") {
        Write-Host ("Processing member {0}" -f $User.DisplayName)
        $MemberId = ("https://graph.microsoft.com/v1.0/users('{0}')" -f $Member)
        $MemberDetails = @{}
        [array]$MemberRole = "owner"
        If ($User.userType -eq "Guest") {
            [array]$MemberRole = "guest"
        }
        $MemberDetails.Add("roles", $MemberRole.trim())
        $MemberDetails.Add("@odata.type", "#microsoft.graph.aadUserConversationMember")
        $MemberDetails.Add("[email protected]", $MemberId.trim())
        $Members += $MemberDetails
  }
}
# Add the membership information to the parameter body
$GroupChatBody.Add("members", $Members)
$NewGroupChat = New-MgChat -BodyParameter $GroupChatBody

图 2 显示了由上述代码创建的群聊的成员资格。

用于向一对一聊天发布消息的相同 New-MgChatMessage 命令也将向群聊发布消息。

多个群聊

虽然 Teams 会重复使用存在的一对一聊天，但可以创建多个具有相同主题的群聊。与可自定义的聊天照片一样，Teams 客户端使用该主题进行显示，以帮助用户在聊天列表中查找聊天。聊天标识符是如何引用特定聊天的。这意味着代码在发布消息时必须小心它所针对的聊天。例如，如果您运行 Get-MgChat cmdlet 来检索群聊的详细信息，您可能会看到如下内容：

$GroupChats = Get-MgChat -filter "ChatType eq 'group'"
$GroupChats | Format-Table Topic, Id

Topic                             Id
-----                             --
Major Updates - Urgent News       19:[email protected]
Major Updates - Urgent News       19:[email protected]
Major Updates - Urgent News       19:[email protected]
Warnings                          19:[email protected]

要区分具有相同主题的聊天，您必须检查其他详细信息，例如聊天成员 (Get-MgChatMembers) 或上次更新的时间戳。

向频道发布基本注释和回复

Teams 将组成频道对话（线程）的消息组织为基本注释和回复。此代码查找我们之前使用的团队的常规频道的标识符，并使用 New-MgTeamChannelMessage cmdlet 将消息作为新的基本注释（对话）发布。

与所有频道对话一样，基调也有一个主题，告诉用户对话涵盖的主题。该代码还标记消息（可选步骤）。如果消息发布成功，代码将使用 Get-MgTeamChannelMessage cmdlet 获取注释的详细信息，并报告发布消息的人员和发布日期的详细信息。

[array]$TeamChannel = Get-MgTeamChannel -TeamId $Team.Id -Filter "displayName eq 'General'"
$ChatMessageBody = @{}
$ChatMessageBody.Add("contentType", "html")
$ChatMessageBody.Add("content", $Content)
$ChannelMessage = New-MgTeamChannelMessage -TeamId $Team.Id -ChannelId $TeamChannel.Id -Body $ChatMessageBody -Subject "Really Important News" -Importance "urgent"
$MessageContents = Get-MgTeamChannelMessage -TeamId $Team.Id -ChannelId $TeamChannel.Id -ChatMessageId $ChannelMessage.Id
If ($MessageContents) {
    Write-Host ("Channel message posted by {0} at {1}" -f $MessageContents.from.user.displayName, $MessageContents.createdDateTime)
}

要向对话添加回复，请运行 New-MgTeamChannelMessageReply cmdlet 并传递基本注释的标识符。

$ReplyMessageBody = @{}
$ReplyMessageBody.Add("contentType", "html")
$ReplyMessageBody.Add("content", "This is a reply...")
$ReplyMessage = New-MgTeamChannelMessageReply -TeamId $Team.Id -ChannelId $TeamChannel.Id -ChatMessageId $ChannelMessage.Id -Body $ReplyMessageBody
If ($ReplyMessage) {
    Write-Host ("Reply posted by {0} at {1}" -f $ReplyMessage.from.user.displayName, $ReplyMessage.createdDateTime) 
}

图 3 显示了向 General 频道发布基本注释和回复的结果。

涵盖更多团队消息传递选项

希望这些示例能让您深入了解 Microsoft Graph PowerShell SDK 中的 Teams 消息 cmdlet 的工作原理。还存在其他可能性，例如在消息中包含附件或提及。 Microsoft 文档将帮助您探索必要的参数，或者我可能会在以后的文章中介绍它们。