Microsoft Graph PowerShell SDK ile Exchange Online E-postası Gönderin

Graph PowerShell SDK'sını keşfetme

Son zamanlarda, komut dosyalarının sonucunu bildirmek için Exchange Online postasının nasıl gönderileceği gibi bazı genel Microsoft 365 yönetim görevlerini otomatikleştirmek için Microsoft Graph'ı PowerShell ile nasıl kullanacağımı araştırıyorum. PowerShell ile Grafik API'lerini kullanmayı düşünmeme neden olan son faktörler arasında şunlar yer alıyor:

  • Microsoft'un 2022'de yeni bir lisanslama platformuna geçme kararı, bu, bazı Azure AD cmdlet'lerinin 30 Haziran 2022'den sonra çalışmayacağı anlamına geliyor. (Microsoft daha sonra bazı kiracılar için son tarihi Mart 2023'e kadar uzattı).
  • 1 Ocak 2023'ten itibaren Exchange Online bağlantı protokollerinden temel kimlik doğrulama desteğini kaldırmaya yönelik sağlam temellere dayanan kampanya). Microsoft şimdilik SMTP AUTH protokolünü muaf tutsa da, PowerShell'in Mesaj Gönder cmdlet'ine Graph SendMail API gibi alternatifleri değerlendirmeye hazırlanmak akıllıca olacaktır.

İlk sorunu çözmek için PowerShell için Microsoft Graph SDK'yı, ikincisinde ise yerel Graph API çağrılarını kullandım. Bu makalede, SDK'daki New-MgUserMessage ve Send-MgUserMessage cmdlet'lerini kullanarak Send-MailMessage cmdlet'ine ikinci bir alternatifi açıklayacağım. yeni çalışanlara hoş geldiniz mesajı oluşturmak ve göndermek için.

Hoş Geldiniz E-postası

Kuruluşlar genellikle işe alım süreçlerinin bir parçası olarak yeni çalışanlara hoş geldiniz e-postası gönderir. E-posta genellikle organizasyonda çalışmaya ilişkin yararlı ipuçları ve kafeteryanın nasıl bulunacağı gibi yeni çalışanların bilmesi gereken şeyleri içerir. İşlemi otomatikleştirmek için komut dosyası aşağıdakileri yapar:

  • Son 7 gün içinde eklenen çalışanların posta kutularını bulmak için Exchange Online'a bağlanır.
  • E-postayı oluşturmak ve göndermek için Microsoft Graph'a bağlanır. Grafiğe yapılan tüm bağlantılar gibi, verilere erişim için de izinlere ihtiyacınız var. Bu örnekte Mail.Send ve Mail.ReadWrite izinlerine ihtiyacımız var. Betik etkileşimli olarak çalışır, bu nedenle Grafiğe bağlanmak için kullanılan hizmet sorumlusundaki izin kaymasının farkında olmamız gerekir.
  • Bulunan kümedeki her posta kutusu için, oturum açmış kullanıcının posta kutusunda bir HTML iletisi oluşturmak üzere New-MgUserMessage cmdlet'ini kullanın.
  • Send-MgUserMessage cmdlet'ini kullanarak iletiyi gönderin.

Komut dosyası basittir (GitHub'dan indirebilirsiniz) ancak asıl amacı kanıtlamak için yeterlidir. Bir ek (belki yeni bir çalışan kılavuzu) ekleyerek veya alıcı grubunu değiştirerek onu süsleyebilirsiniz. Bu noktalara daha sonra geleceğiz.

Bağlanılacak Kod

Grafiğe bağlanmak için gereken kod basittir:

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

Connect-MgGraph cmdlet'i, kiracı tanımlayıcısını kullanarak bir kiracıya bağlanır (kiracınız için doğru değeri kullandığınızdan emin olun) ve ihtiyacımız olan iki izni ister. Graph SDK tarafından kullanılan hizmet sorumlusu bu izinler için halihazırda izin sahibi değilse Graph izin ister. Diğer komutlar, oturum açmış olduğunuz bağlamın ve kuruluş adının ayrıntılarını getirir.

Hedef Posta Kutularını Bulma

Hedef posta kutularını bulma kodu, son 7 gün içinde oluşturulan tüm posta kutularını arar. Yine oldukça basit:

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

Mesaj Oluşturma ve Gönderme

Hedef posta kutuları kümesini bulduktan sonra, özelleştirilmiş bir HTML iletisi oluşturmak (Şekil 1) için her bir posta kutusu arasında geçiş yapabiliriz ve yeni iletiyi göndermek için Send-MgUserMessage cmdlet'inin ihtiyaç duyduğu ileti özellikleri kümesini doldurabiliriz. alıcıya.

# 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

Diğer birçok PowerShell cmdlet'inin, özellikle de Exchange Online'ın aksine, Grafik API'leriyle etkileşimde bulunduğunuzda, API'nin gerektirdiği giriş biçimini kullanırken çok dikkatli olmalısınız. Örneğin, bir hedef posta kutusu için birincil SMTP adresini almanın ve bu dizeyi bir mesaja alıcı eklemek için kullanmanın mümkün olduğunu düşünebilirsiniz. Ne yazık ki durum böyle değil ve Grafiğin mutlu olması için doğru formatta öğeler içeren bir dizi oluşturmanız gerekiyor.

Alıcıları İşleme

Yukarıdaki kod, tek bir TO: alıcısı ekleme adımlarını gösterir. Başka alıcılar eklemek istiyorsanız, giriş dizisini oluşturmak için aynı tür işlemleri gerçekleştirirsiniz. Örneğin, mesaja birkaç BCC alıcısı eklemek istediğinizi varsayalım. Alıcıları bir dizide bildiririz (veya onları PowerShell kullanarak bazı kaynaklardan alırız):

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

Ve sonra giriş dizisini oluşturun:

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

Dizi şuna benzer:

$BCC

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

Dizinin değerlerini aşağıdakileri kullanarak görebiliriz:

$BCC.Values

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

SDK geliştiricileri, iletilere alıcı eklemeyi kolaylaştırarak hepimize bir iyilik yapabilirler. Mesaj yapısının neden iç içe geçmiş değerler gerektirdiğine dair bir mantık olduğundan eminim, ancak bu, insanları SDK'yı kullanmak için kodlarını güncellemeye ikna etmeyi kolaylaştırmıyor.

Ek Ekleme

İletilere ek eklemek, SDK geliştiricilerinin bazı karmaşıklıkları PowerShell geliştiricilerinden gizleyebileceği başka bir alandır. Şimdilik bir ek eklemek, dosyanın Base64 kodlu bir sürümünü oluşturmanızı ve bunu bir giriş dizisine eklemenizi gerektiriyor. Örneğin:

$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 önce oluşturduğumuz girdi dizisi şuna benzer:

$MsgAttachment

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

Eki iletiye eklemek için New-MgUserMessage için Ekler parametresine girdi olarak diziyi belirtin. Ek, beklediğiniz gibi görünür (Şekil 2).

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

İyi İşlevsellik; Daha Kolay Olabilir

Yeniden seçilmek için yalvaran politikacılar bazen çok şey yaptıklarını ama daha yapacak çok işleri olduğunu iddia ederler. Exchange Online aracılığıyla ileti oluşturmak ve göndermek için PowerShell için Microsoft Graph SDK'yı kullanma konusunda da aynı duyguyu yaşıyorum. Pek çok işlevsellik mevcuttur ancak animasyonsuz kişilerin bunlara erişmesi zordur, özellikle de Send-MailMessage cmdlet'inin göreli basitliği nedeniyle. İyi dokümantasyon eksikliği başka bir engeldir.

Bugün PowerShell için Microsoft Graph SDK'sı, temel Graph API'lerinin çalışma şeklini taklit ediyor. Gelişimin erken aşaması göz önüne alındığında bu uygun ve gereklidir. Ancak insanları SDK'yı benimsemeye ve kullanmaya ikna etmek için geliştiricilerin, yöneticilerin Graph'ın gücüne SDK cmdlet'leri aracılığıyla erişmesini çok daha basit hale getirmesi gerektiğini düşünüyorum.

İlgili makaleler