Weboldal keresés

Küldjön Exchange Online e-mailt a Microsoft Graph PowerShell SDK segítségével

A Graph PowerShell SDK felfedezése

A közelmúltban azt vizsgáltam, hogyan használhatom a Microsoft Graph-ot a PowerShell-lel néhány gyakori Microsoft 365 adminisztrációs feladat automatizálására, például az Exchange Online levelek küldésére a szkriptek eredményének jelentésére. A közelmúltban felmerülő tényezők között, amelyek miatt fontolóra vettem a Graph API-k használatát a PowerShell-lel, a következők:

  • A Microsoft úgy döntött, hogy 2022-ben új licencelési platformra vált, ami azt jelenti, hogy egyes Azure AD-parancsmagok 2022. június 30-a után nem fognak működni. (A Microsoft ezt követően 2023 márciusáig meghosszabbította egyes bérlők határidejét).
  • A jól megalapozott kampány, amely 2023. január 1-jétől megszünteti az alapszintű hitelesítés támogatását az Exchange Online csatlakozási protokolljaiból). Bár a Microsoft egyelőre mentesítette az SMTP AUTH protokollt, bölcs dolog felkészülni a PowerShell Send-Message parancsmagjának alternatíváinak mérlegelésére, például a Graph SendMail API-ra.

Az első probléma megoldásához a Microsoft Graph SDK for PowerShell-t használtam, a másodikhoz pedig a natív Graph API-hívásokat. Ebben a cikkben a Send-MailMessage parancsmag egy másik alternatíváját mutatom be az SDK New-MgUserMessage és Send-MgUserMessage parancsmagjainak használatával. üdvözlő üzenet létrehozása és küldése az új alkalmazottaknak.

Üdvözlő e-mail

A szervezetek általában üdvözlő e-mailt küldenek az új alkalmazottaknak a felvételi folyamatuk részeként. Az e-mail általában hasznos tippeket tartalmaz a szervezetben való munkavégzéssel kapcsolatban, és olyan dolgokat, amelyeket az új alkalmazottaknak tudniuk kell, mint például a kávézó megtalálása. A folyamat automatizálásához a szkript a következőket teszi:

  • Csatlakozik az Exchange Online-hoz, hogy megkeresse az elmúlt 7 napban hozzáadott alkalmazottak postafiókját.
  • Csatlakozik a Microsoft Graphhoz az e-mail létrehozásához és elküldéséhez. A Graphhoz fűződő minden kapcsolathoz hasonlóan az adatokhoz való hozzáféréshez engedélyekre van szüksége. Ebben az esetben szükségünk van a Mail.Send és Mail.ReadWrite engedélyekre. A szkript interaktívan fut, ezért tisztában kell lennünk a Graphhoz való csatlakozáshoz használt egyszerű szolgáltatási jogosultságokkal.
  • A készletben található minden egyes postafiókhoz használja a New-MgUserMessage parancsmagot, és hozzon létre egy HTML-üzenetet a bejelentkezett felhasználó postafiókjában.
  • Küldje el az üzenetet a Send-MgUserMessage parancsmag használatával.

A szkript alapvető (letöltheti a GitHubról), de elegendő a megbízó bizonyításához. Melléklet hozzáadásával (esetleg új alkalmazotti útmutatóval) vagy a címzettek körének megváltoztatásával díszítheti. Ezekre a pontokra később térünk ki.

Kód a csatlakozáshoz

A Graphhoz való csatlakozás kódja egyszerű:

Connect-MgGraph -TenantId a562313f-14fc-43a2-9a7a-d2e27f4f3478 -Scope "Mail.Send, Mail.ReadWrite"
$Details = Get-MgContext
$Scopes = $Details | Select -ExpandProperty Scopes
$Scopes = $Scopes -Join ", "
$ProfileName = (Get-MgProfile).Name
$TenantName = (Get-MgOrganization).DisplayName

A Connect-MgGraph parancsmag a bérlői azonosító használatával csatlakozik egy bérlőhöz (győződjön meg arról, hogy a megfelelő értéket használja a bérlő számára), és kéri a két szükséges engedélyt. Ha a Graph SDK által használt egyszerű szolgáltatás még nem rendelkezik beleegyezéssel ezekhez az engedélyekhez, a Graph beleegyezést kér. A többi parancs lekéri a bejelentkezett környezet és a szervezet nevének részleteit.

Célpostafiókok keresése

A célpostafiókok megkeresésére szolgáló kód az elmúlt 7 napban létrehozott postafiókokat keresi. Megint nagyon egyszerű:

[string]$CheckDate = (Get-Date).AddDays(-7)
# Find all mailboxes created in the target period
[array]$Users = (Get-ExoMailbox -Filter "WhenMailboxCreated -gt '$CheckDate'" -RecipientTypeDetails UserMailbox -ResultSize Unlimited -Properties WhenMailboxCreated | Select WhenMailboxCreated, DisplayName, UserPrincipalName, PrimarySmtpAddress)
If ($Users -eq $Null) { Write-Host ("No mailboxes found that were created before {0}. Exiting!" -f $CheckDate) }

Üzenet létrehozása és küldése

Miután megtaláltuk a célpostafiókok készletét, végigpörgethetjük az egyes postafiókokat, hogy személyre szabott HTML-üzenetet hozzunk létre (1. ábra), és feltöltsük a Send-MgUserMessage parancsmag által az új üzenet elküldéséhez szükséges üzenettulajdonságokat. a címzettnek.

# Create and send welcome email message to each of the new mailboxes
ForEach ($User in $Users) {
      # Add the recipient using the mailbox's primary SMTP address
      $EmailAddress  = @{address = $User.PrimarySmtpAddress} 
      $EmailRecipient = @{EmailAddress = $EmailAddress}  
      Write-Host "Sending welcome email to" $User.DisplayName
      # Customize the message 
      $htmlHeaderUser = "<h2>New User " + $User.DisplayName + "</h2>"    
      $htmlbody = $htmlheaderUser + $htmlline1 + $htmlline2 + $htmlline3 + "<p>"
      $HtmlMsg = "</body></html>" + $HtmlHead + $HtmlBody
      # Construct the message body
      $MessageBody = @{
           content = "$($HtmlBody)"
           ContentType = 'html'
           }
     # Create a draft message in the signed-in user's mailbox
     $NewMessage = New-MgUserMessage -UserId $MsgFrom -Body $MessageBody -ToRecipients $EmailRecipient -Subject $MsgSubject
     # Send the message
     Send-MgUserMessage -UserId $MsgFrom -MessageId $NewMessage.Id  
} # End ForEach User

Sok más PowerShell-parancsmaggal ellentétben, különösen az Exchange Online-hoz, a Graph API-kkal való interakció során nagyon óvatosnak kell lennie az API által megkívánt bemeneti formátum használatával. Például elképzelhető, hogy lehetségesnek kell lennie egy célpostafiók elsődleges SMTP-címének lekérésére, és ennek a karakterláncnak a segítségével címzettet adni az üzenethez. Sajnos ez nem így van, és fel kell építeni egy tömböt az elemekből a megfelelő formátumban, mielőtt a grafikon boldoggá válik.

Címzettek kezelése

A fenti kód bemutatja az egyetlen TO: címzett hozzáadásának lépéseit. Ha további címzetteket szeretne hozzáadni, ugyanezen a lépéseken kell átmennie a bemeneti tömb felépítéséhez. Tételezzük fel például, hogy néhány BCC-címzettet szeretne hozzáadni az üzenethez. A címzetteket egy tömbben deklaráljuk (vagy lekérjük őket valamilyen forrásból a PowerShell segítségével):

$BCCRecipients = @("Brian.Weakliam@Office365itpros.com", "Kim.Akers@Office365itpros.com")

Ezután készítse el a bemeneti tömböt:

$BCC = $BCCRecipients | % {@{emailAddress = @{ address = $_ }}}

A tömb így néz ki:

$BCC

Name                           Value
----                           -----
emailAddress                   {address}
emailAddress                   {address}

A tömb értékeit a következő használatával láthatjuk:

$BCC.Values

Name                           Value
----                           -----
address                        Brian.Weakliam@Office365itpros.com
address                        Kim.Akers@Office365itpros.com

Az SDK fejlesztői mindannyiunknak szívességet tehetnének azzal, hogy megkönnyítik a címzettek hozzáadását az üzenetekhez. Biztos vagyok benne, hogy van logika annak, hogy az üzenetstruktúra miért követeli meg a beágyazott értékeket, de ez nem könnyíti meg az emberek meggyőzését arról, hogy frissítsék kódjukat az SDK használatára.

Mellékletek hozzáadása

Mellékletek hozzáadása az üzenetekhez egy másik hely, ahol az SDK-fejlesztők elrejthetik a bonyolultságokat a PowerShell-fejlesztők elől. Egyelőre a melléklet hozzáadásához létre kell hozni a fájl Base64 kódolású verzióját, és be kell helyezni egy bemeneti tömbbe. Például:

$AttachmentFile = "c:\temp\WelcometoOffice365ITPros.docx"
$EncodedAttachmentFile = [convert]::ToBase64String((Get-Content $AttachmentFile -Encoding byte)) 
$MsgAttachment = @{
    "@odata.type"= "#microsoft.graph.fileAttachment"
    name = ($AttachmentFile -split '\\')[-1]
    contentBytes = $EncodedAttachmentFile
}

Az imént felépített bemeneti tömb így néz ki:

$MsgAttachment

Name                           Value
----                           -----
contentBytes                   UEsDBBQABgAIAAAAIQD7xliMzwEAAEoKAAATAAgCW0NvbnRlbnRfVHlwZXNd…
name                           WelcometoOffice365ITPros.docx
@odata.type                    #microsoft.graph.fileAttachment

A mellékletnek az üzenetben való szerepeltetéséhez adja meg a tömböt a New-MgUserMessage Attachments paraméterének bemeneteként. A melléklet a várt módon jelenik meg (2. ábra).

$NewMessage = New-MgUserMessage -UserId $MsgFrom -Body $MessageBody -ToRecipients $EmailRecipient -Subject $MsgSubject -Attachments $MsgAttachment

Jó funkcionalitás; Lehetne könnyebb

Az újraválasztásukért könyörögve a politikusok néha azt állítják, hogy sokat tettek, de még sok a tennivalójuk. Ugyanez az érzésem a Microsoft Graph SDK for PowerShell használatával kapcsolatban az Exchange Online-on keresztüli üzenetek létrehozására és küldésére. Nagyon sok funkció áll rendelkezésre, de az animáció nélküliek nehezen férhetnek hozzá, különösen, ha a Send-MailMessage parancsmag viszonylagos egyszerűségéből fakad. További akadályt jelent a megfelelő dokumentáció hiánya.

Ma a Microsoft Graph SDK for PowerShell utánozza az alapul szolgáló Graph API-k működését. Ez helyénvaló és szükséges a fejlődés korai szakaszában. De ahhoz, hogy meggyőzzék az embereket az SDK elfogadásáról és használatáról, úgy gondolom, hogy fejlesztőinek sokkal egyszerűbbé kell tenniük a rendszergazdák számára, hogy az SDK-parancsmagokon keresztül hozzáférjenek a Graph teljesítményéhez.

Kapcsolódó cikkek