Weboldal keresés

Gyakorlati grafikon: Teams Messaging használata

Választás a modulok között

A Microsoft Teams PowerShell-modul új verziója általában több százezer letöltést generál a PowerShell-galériából. Bár a letöltések száma nem jelzi a használatot, ésszerű feltételezni, hogy a legtöbb, aki letölti a modult, a Teams kezelésére használja. A Microsoft Graph PowerShell SDK olyan parancsmagokat is tartalmaz a Teams-szel való együttműködéshez, mint a Get-MgTeam, Get-MgTeamChannel és így tovább, amelyek közül sok ismétlődő parancsmag található a Microsoft Csapatok modul. Tekintettel a duplikációra, melyik útvonalat kell választaniuk a rendszergazdáknak a Teams-műveletek automatizálásához?

A válasz nem egyértelmű, mert attól függ, hogy mit próbál tenni. Íme néhány pont, amelyet emlékezni kell:

  • Mindkét modulnak van linkje a Microsoft Graphhoz. A Microsoft Teams modulban található parancsmagok közül sok Graph API-kon alapul, és a Microsoft Graph PowerShell SDK összes parancsmagja Graph API-kból származik.
  • A Microsoft Teams modul egyéb olyan parancsmagokat is tartalmaz, amelyek nem a Graph API-kon alapulnak. A legtöbb házirend-kezelési parancsmag, amely eredetileg a Skype Vállalati verzió-összekötőből származott.
  • A Microsoft Graph PowerShell SDK parancsmagokat tartalmaz a többi Microsoft 365 munkaterheléssel és az Entra ID-vel való interakcióhoz.
  • A Microsoft Teams modult a felügyeleti műveletek automatizálására tervezték. Ha globális rendszergazdai vagy Teams-rendszergazdai szerepkörrel rendelkező fiók használja, a parancsmagok kezelhetik a szervezet összes csapatát.
  • A Microsoft Graph PowerShell SDK olyan parancsmagokat tartalmaz, amelyek interakcióba léphetnek a felhasználói tartalommal, például új csevegéseket tehetnek közzé. A különböző Teams-adatokkal való interakcióhoz különböző engedélyekre van szükség. A fejlesztőknek emlékezniük kell a delegált engedélyek és az alkalmazásengedélyek közötti különbségre is, amikor az adatokhoz való hozzáférésről van szó.

A legtöbb esetben egyszerűbb használni a Microsoft Teams modult az általános automatizáláshoz, és bevezetni a Microsoft Graph PowerShell SDK-t, amikor szükség van a felhasználói adatokkal való interakcióra, például csevegések közzétételére vagy eltávolítására, amit itt szeretnénk megtenni.

A cikk hátralévő része a Teams-üzenetkezelés alapjait tárgyalja, és elmagyarázza, hogyan lehet üzeneteket küldeni egy-egy személyes, valamint csoportos csevegésekre és csatornabeszélgetésekre a Microsoft Graph PowerShell SDK használatával. Az üzenetek csatornákról való eltávolításának folyamatát egy másik cikk tárgyalja.

Megjegyzés az engedélyekről

Amint azt valószínűleg Ön is tudja, a Graph API-kérésekhez használt engedélymodell a legkevesebb jogosultsági alap. A legtöbb esetben az alkalmazásengedélyek állnak rendelkezésre ahhoz, hogy a Graph-kérelmeket használó alkalmazások háttérfolyamatként, például ütemezett Azure Automation-feladatként futhassanak.

Nem állnak rendelkezésre alkalmazásengedélyek a Graph kérésekhez, például üzenetek közzétételéhez csevegésekben vagy csatornabeszélgetésekben, ezért delegált engedélyeket kell használni. Az alkalmazásnak ChannelMessage.Send engedélyre van szüksége ahhoz, hogy üzeneteket tegyen közzé a csatornákon, és Chat.Create engedélyre van szüksége a csevegésben való közzétételhez. Az üzenetek lekéréséhez további engedélyekre van szükség (például Chat.ReadWrite).

Az alkalmazásengedélyek hiánya miatt a bejelentkezett fióknak egy csevegés vagy egy csapat tagjának kell lennie az üzenetek közzétételéhez, a csapattulajdonosnak pedig a csatornaüzenetek eltávolításához. Az Azure Automation felügyelt identitásai nem használhatók, mert ezek az identitások nem lehetnek egy csapat vagy csevegés tagjai.

A szokásos megoldás az, hogy bejelentkezik a Teamsbe egy olyan segédprogram-fiókkal, amely egy csapattag, és így tesz közzé bejegyzéseket a csatornákon. Korábban ezt a Submit-PnPTeamsChannelMessage parancsmag PnP-moduljával tettem meg az Azure Key Vaultban tárolt hitelesítő adatok használatával. Ugyanez a technika működik az itt tárgyalt cmdletekkel is.

Chat Payloads

A Teams támogatja az egyéni és csoportos csevegéseket. Az első példa új, személyes csevegést hoz létre két bérlői fiók között. A Microsoft dokumentációja számos jó példát tartalmaz arra, hogyan lehet üzeneteket küldeni a csevegésekre. Úgy gondolom azonban, hogy a Teamsben való közzétételhez használt JSON-adattartalom összeállítására használt módszer túlságosan bonyolult, és nem alkalmas programozott manipulációra.

Ezért más megközelítést alkalmazok a hasznos terhet alkotó tömbök és hash táblák meghatározásához és felbukkanásához. Ez ugyanaz a megközelítés, mint a paraméterek összeállítása a Planner-feladatok tervben történő közzétételéhez. Ha szeretné, használja a dokumentációs példákban alkalmazott megközelítést. Működnek és jó példák, de úgy gondolom, hogy az én módszerem jobb az éles szkriptekhez.

Személyes csevegés létrehozása és közzététele

Először definiálunk egy tömböt, amely tartalmazza a csevegés résztvevőinek fiókazonosítóit, és a hash táblát, amely a csevegés létrehozásához használt hasznos terhet (más néven kérés törzsét) tartalmazza. A kód egy paramétert is hozzáad a csevegés egy az egyhez történő azonosításához. A csevegés típusának azonosításához a pontos formátumot (onOnOne) kell használnia.

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

A hasznos teher többi része határozza meg a chat résztvevőit. Ezeket az adatokat két hash táblából álló tömbben továbbítják. Minden hash-tábla egy-egy csevegési résztvevővel kapcsolatos információkat tartalmaz, amelyek közül az egyiknek a bejelentkezett felhasználónak kell lennie. Amint láthatja, a kód lehetővé teszi vendégfiók hozzáadását csevegési résztvevőként.

$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("user@odata.bind", $MemberId.trim())
    $Members += $MemberDetails
}
$OneOnOneChatBody.Add("members", $Members)

A teljes rakomány így néz ki:

$OneOnOneChatBody

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

Most már futtathatjuk a New-MgChat parancsmagot csevegés létrehozásához. Ha már létezik csevegés a két résztvevő számára, a Teams visszaadja az adott csevegés azonosítóját. Ha nem, a Teams új csevegést hoz létre, és visszaadja azt az azonosítót, amelynek értéke például 19:949d2f6c2b1f4f50b42714ddb2be4a36@thread.v2.

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

A csevegési azonosító ismerete lehetővé teszi a New-MgChatMessage parancsmag futtatását, amellyel üzenetet küldhetünk a csevegésbe. Ez a kód HTML-tartalmat hoz létre, és közzéteszi a csevegésben.

$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

Az 1. ábra a chatben elküldött üzenetet mutatja.

Csoportos csevegés létrehozása és közzététele

A csoportos csevegésnek 2 és 250 résztvevője van. Témája (címe) is lehet. A nagyszámú résztvevő új csoportos csevegésbe való felvételének demonstrálására ez a kód megkeres egy csapatot, amely egy adott megjelenített névhez af szűrőt használ, és a tagsági névsorát felhasználói fiókazonosítók tömbjévé bontja ki. Ezenkívül létrehozza a hash táblát a hasznos adathoz az új csevegés létrehozásához, és feltölti a csevegés típusát és témáját:

$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")

A következő lépésben létrehoz egy hash-táblázatot, amely meghatározza a csoportos csevegéshez hozzáadandó tagokat. Csakúgy, mint a személyes csevegésnél, a csoportos csevegés egyik résztvevőjének a bejelentkezett felhasználónak kell lennie. Mivel ez egy előnézeti funkció, a kód kizárja a több bérlős szervezetből szinkronizált csapattagok fiókjait. Végül a New-MgChat parancsmag létrehozza az új csevegést.

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("user@odata.bind", $MemberId.trim())
        $Members += $MemberDetails
  }
}
# Add the membership information to the parameter body
$GroupChatBody.Add("members", $Members)
$NewGroupChat = New-MgChat -BodyParameter $GroupChatBody

A 2. ábra a fenti kóddal létrehozott csoportos csevegés tagságát mutatja.

Ugyanaz a New-MgChatMessage parancs, amelyet a személyes csevegésben való üzenetküldéshez használ, üzenetet küld a csoportos csevegésben is.

Több csoportos csevegés

Míg a Teams újrafelhasznál egy személyes csevegést, ha létezik ilyen, lehetőség van több csoportos csevegés létrehozására is azonos témájú. A testreszabható csevegőfotóhoz hasonlóan a Teams kliensei is megjelenítik a témát, hogy segítsenek a felhasználóknak megtalálni a csevegéseket a csevegési listában. A csevegési azonosító az adott csevegésekre való hivatkozás módja. Ez azt jelenti, hogy a kódnak ügyelnie kell arra, hogy melyik csevegést célozza meg üzenetek közzétételekor. Ha például a Get-MgChat parancsmagot futtatja a csoportos csevegés részleteinek lekéréséhez, a következőt láthatja:

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

Topic                             Id
-----                             --
Major Updates - Urgent News       19:1741422a23464620a6e71f363db2d51a@thread.v2
Major Updates - Urgent News       19:949d2f6c2b1f4f50b52714ddb2be4a36@thread.v2
Major Updates - Urgent News       19:5f6deae375f84b3396a9648722ba62b8@thread.v2
Warnings                          19:b2db6ce5bfb348709dccd9b8f959dfae@thread.v2

Az azonos témájú csevegések megkülönböztetéséhez ellenőriznie kell az egyéb részleteket, például a csevegési tagokat (Get-MgChatMembers) vagy az utolsó frissítés időbélyegét.

Alapjegyzetek és válaszok közzététele egy csatornán

A Teams alapjegyzetekké és válaszokká rendezi a csatornabeszélgetéseket (szálakat) alkotó üzeneteket. Ez a kód megtalálja a korábban használt csapat általános csatornájának azonosítóját, és a New-MgTeamChannelMessage parancsmag segítségével új alapjegyzetként (beszélgetésként) tesz közzé egy üzenetet.

Mint minden csatornabeszélgetésnek, az alapjegyzetnek is van egy tárgya, amely elmondja a felhasználóknak, hogy a beszélgetés milyen témát fed le. A kód az üzenetet is jelöli (opcionális lépés). Ha az üzenet közzététele sikeres, a kód lekéri a feljegyzés részleteit a Get-MgTeamChannelMessage parancsmaggal, és jelentést készít arról, hogy ki tette közzé az üzenetet és a feladás dátumát.

[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)
}

Ha választ szeretne adni a beszélgetéshez, futtassa a New-MgTeamChannelMessageReply parancsmagot, és adja át az alapjegyzet azonosítóját.

$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) 
}

A 3. ábra az alapjegyzet és az Általános csatornára adott válasz feladásának eredményét mutatja.

További fedezendő Teams üzenetküldési lehetőségek

Remélhetőleg ezek a példák némi betekintést nyújtanak a Teams üzenetküldő parancsmagjainak működésébe a Microsoft Graph PowerShell SDK-ban. Más lehetőségek is léteznek, például csatolmányok vagy említések az üzenetekben. A Microsoft dokumentációja segít a szükséges paraméterek feltárásában, vagy talán egy későbbi cikkben kitérek rájuk.

Kapcsolódó cikkek