Microsoft Graph PowerShell Kullanarak E-posta Nasıl Gönderilir

Eski e-posta kimlik doğrulama yöntemleri geçmişte kaldı; Exchange Online için eski kimlik doğrulama artık ölü ve 3. taraf hizmetlerinin korunması giderek zorlaşıyor; özellikle de bunları alan adınız için güvenilir posta kaynakları olarak eklemeniz gerektiğinde, programlı olarak alternatif bir yöntem olarak. e-posta göndermek önemlidir.

Microsoft Graph PowerShell'deki Send-MgUserMail cmdlet'i, hem etkileşimli hem de etkileşimli olmayan PowerShell oturumlarında PowerShell'i kullanarak programlı olarak e-posta göndermenin kullanışlı ve kolay bir yolunu sağlar.

Bu eğitimde, mevcut Exchange Online hizmetinizi kullanarak programlı olarak e-posta göndermek için Microsoft Graph PowerShell ve Graph API'yi nasıl kullanacağınızı göstereceğim.

3. parti hizmetlere olan ihtiyacın ortadan kaldırılması

Exchange Online için eski kimlik doğrulamanın artık kullanılamaz olması nedeniyle, e-postaları güvenli bir şekilde aktarmanın diğer yöntemleri birçok kuruluş için sürekli bir ihtiyaç olmuştur. Zorlu uygulamalar (Microsoft Dynamics gibi) veya ileri teknoloji cihazlar (MFP'ler gibi), Office 365 Direct Send gibi yöntemleri (statik bir genel IP arkasında olmaları koşuluyla) kolayca kullanabilir veya mevcut hibrit altyapıyı kullanabilir (eğer hala buna sahip olmak ne yazık ki…), programatik çözümler, özellikle Azure Otomasyonu gibi hizmetleri kullanırken ve 3. taraf altyapısının kullanımını engellemeye çalışırken zorlu olmuştur.

SMTP2Go veya SendGrid gibi üçüncü taraf hizmetler bu sorunu çözmek için cazip seçenekler gibi görünebilir ancak şu soru ortaya çıkıyor:

• Şifreleri döndürmeli misiniz?
• Gerçekten ne kadar güvenliler?
• Uyumlular mı?
• Güvenlik açıklarını nasıl takip edip izlerim?
• Liste devam ediyor…

Bu soruna basit bir cevap vermek gerekirse, bunları hiç kullanmamak ve bunun yerine kullanabileceğiniz PowerShell'li Graph API'yi kullanmaktır!

Send-MgUserMail Hakkında

Send-MgUserMail cmdlet'i, Microsoft Graph PowerShell SDK'nın Microsoft.Graph.Users.Actions modülünde bulunabilir ve komut, hem temsilci hem de uygulama izinleriyle kullanılabilir. farklı bağlamlarda.

Cmdlet'i kullanmak için mail.send izin kapsamına izin vermeniz gerekir, ancak bu izne devredilen izinleri veya uygulama izinlerini kullanarak izin vermenize bağlı olarak farklı bir erişim düzeyi verilir.

Yetki verilen bir senaryoda mail.send iznini kabul ederseniz, yalnızca geçerli oturumunuzda (geçerli kullanıcı bağlamı) kimliği doğrulanmış kullanıcı olarak posta gönderebileceğinizi fark edebilirsiniz.

Ancak eşdeğer başvuru iznine onay verdiğinizde, kuruluşunuzdaki herhangi bir kullanıcı olarak posta gönderebileceğinizi fark edeceksiniz.

Gördüğünüz gibi mail.send tehlikeli derecede güçlü bir izindir ve dikkatli kullanılmalıdır. Bu izni Azure Otomasyonu ile kullanmayı planlıyorsanız istemci sırlarını veya sertifikalarını yönetme ihtiyacını ortadan kaldırmak ve ortamınızı güvende tutmak için Yönetilen Kimlikler kullanmayı düşünün.

Microsoft Graph PowerShell ile E-posta Gönderin

Yetki verilen izinlere sahip bir e-posta gönderin

Kendi kullanıcı bağlamınız altında yetkilendirilmiş izinlere sahip e-postalar göndermek için Microsoft Graph'a Connect-MgGraph cmdlet'i ve Mail.Send izin kapsamıyla bağlanmanız gerekir:

Connect-MgGraph -scope Mail.Send

Daha sonra, gerçek posta mesajının karma tablosu olarak tanımlanması gerekir; burada belirli bir adresten basit bir metin tabanlı e-posta göndermenin basit bir örneği verilmiştir. 'E-POSTANIZ BURADA' metnini Microsoft Graph'te kimlik doğrulaması yapmak için kullandığınız hesabın e-posta adresiyle değiştirdiğinizden emin olun.

$body = @{
	message = @{
		subject = "My Microsoft Graph Test Email"
		body = @{
			contentType = "Text"
			content = "Hello, this is a test email"
		}
		toRecipients = @(
			@{
				emailAddress = @{
					address = "YOUR EMAIL HERE"
				}
			}
		)
	}
	saveToSentItems = "false"
}

Son olarak, e-postayı göndermek için Send-MgUserMail cmdlet'ini aşağıdaki gibi kullanın:

Send-MgUserMail -UserId %YourUPN% -BodyParameter $body

Uygulama izinlerini içeren bir e-posta gönderin

Zaten bildiğimiz gibi, uygulama izinleri Mail.Send iznini tanımlarken daha fazla gücü açığa çıkarır. Bu, senaryomuzda daha esnek olabileceğimiz anlamına gelir.

Microsoft Graph'a bağlanarak başlayın. Bunun nasıl yapılacağına henüz aşina değilseniz, buradaki rehberimi izleyin: Microsoft Graph PowerShell'e İstemci Sırrı ile Nasıl Bağlanılır.

Uygulama izinlerini kullanırken aşağıdaki örneğimde olduğu gibi biraz farklı bir yaklaşım izlenebilir. Burada, kullanıcının e-postanın kime ve kimden gönderileceğini tanımlamasına olanak tanıyan -to ve -from parametrelerini komut dosyasına eklediğimi görebilirsiniz. Kime/kimden adresi otomatik bir eylemin sonucuna bağlıysa, örneğin Azure Otomasyonu kullanıyorsanız, bu parametrelerin değeri diğer kaynaklardan da elde edilebilir.

Param(
    [Parameter(Mandatory)]
    [ValidateNotNull()]
    [mailaddress]
    ${to},

    [Parameter(Mandatory)]
    [ValidateNotNull()]
    [mailaddress]
    ${from}
)

$ApplicationId = "APPID"
$SecuredPassword = "SECRETKEY"
$tenantID = "TENANTID"
$SecuredPasswordPassword = ConvertTo-SecureString -String $SecuredPassword -AsPlainText -Force
$ClientSecretCredential = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $ApplicationId, $SecuredPasswordPassword
Connect-MgGraph -TenantId $tenantID -ClientSecretCredential $ClientSecretCredential

$body = @{
	message = @{
		subject = "My Microsoft Graph Test Email"
		body = @{
			contentType = "Text"
			content = "Hello, this is a test email"
		}
		toRecipients = @(
			@{
				emailAddress = @{
					address = "$to"
				}
			}
		)
	}
	saveToSentItems = "false"
}

Send-MgUserMail -UserId $from -BodyParameter $body

Send-MgUserMail ile mesaj başlıklarını değiştirin

İleti üstbilgileri, bir e-postanın kaynağı ve iletinin geçtiği e-posta sunucuları hakkında önemli bilgiler içerir. Bizim gibi yöneticiler daha sonra sorun giderme amacıyla bir e-postanın ayrıntılarını belirlemek için mesaj başlığındaki bilgileri kullanabilir. İleti üstbilgileri hakkında daha ayrıntılı bilgi için eğitimime bakın: Exchange Online'da İleti Başlıklarını İnceleme ve Yorumlama.

Bizim durumumuzda, diğer kullanıcıların e-postanın kaynağını ve diğer sorun giderme faktörlerini belirlemesine yardımcı olmak için Send-MgUserMail cmdlet'ini kullanarak gönderilen bir mesaja ek bilgiler ekleyebiliriz. Bunu yapmak isteyebileceğiniz bir diğer iyi neden, bu iletilere belirli Exchange aktarım kurallarını uygulayabilmeniz veya hariç tutabilmenizdir; örneğin, bu iletileri herhangi bir günlük kaydı kuralı için hariç tutabilirsiniz.

Bunu yapmak için message=@{ karma tablosuna aşağıdaki kodu eklemeniz gerekir:

InternetMessageHeaders = @(
			@{
				Name = "x-custom-header-name"
				Value = "custom value"
			}
		)

Ayrıca aşağıdaki karma tabloyu kopyalayarak mesajınıza birden fazla başlık ekleyebilirsiniz:

InternetMessageHeaders = @(
			@{
				Name = "x-custom-header-name"
				Value = "custom value"
			}
			@{
				Name = "x-custom-header-name2"
				Value = "custom value2"
			}	
		)

x-özel-başlık-adı'nı (başlığın x- ile başladığından emin olarak) özel değer ile birlikte daha spesifik bir değerle değiştirin. Aşağıda şu ana kadar yazdığım mesajın bir örneğini görebilirsiniz:

$body = @{
	message = @{
		subject = "My Microsoft Graph Test Email"
		body = @{
			contentType = "Text"
			content = "Hello, this is a test email"
		}
		toRecipients = @(
			@{
				emailAddress = @{
					address = "[email "
				}
			}
		)
       	InternetMessageHeaders = @(
			@{
				Name = "x-ocn-header-source"
				Value = "azure-automation"
			}
		)
	}
	saveToSentItems = "false"
}

Başlığınızı oluşturduktan sonra bir test e-postası gönderin ve mesaj başlığı özelliklerini görüntüleyin. OWA kullanıyorsanız mesajı sağ tıklayıp ardından Görüntüle > Mesaj ayrıntılarını görüntüle'yi tıklayabilirsiniz.

Ekleri Microsoft Graph PowerShell ile gönderme

Ekler alıcı için önemli bilgiler içerebilir, bu nedenle programlı olarak e-posta gönderirken e-postalara nasıl ek ekleneceğini öğrenmek faydalı olacaktır.

PowerShell kullanılırken çeşitli kaynaklardan ekler eklenebilir, örneğin:

• Invoke-WebRequest kullanılarak internetten indirildi
• Windows'ta dosya gezgini kullanılarak manuel olarak seçildi
• PowerShell'in kendisinde oluşturulmuştur

Etkileşimli PowerShell oturumları sırasında bir dosyayı manuel olarak seçmek yararlı olsa da etkileşimli olmayan oturumlar, ek ekleme işlemini otomatik olarak yapmanızı gerektirir. Hem manuel hem de otomatik olarak eklerin nasıl ekleneceğine bakalım.

Ekleri manuel olarak seçme

Mevcut ekler, e-posta iletilerinde kullanılmak üzere kodunuzda manuel olarak tanımlanabilir. Bunu, dosyanızın yolunu tanımlayarak, onu 64 tabanlı bir dizeye dönüştürerek ve mesajınızın gövdesine ekleyerek yapabilirsiniz.

Eki almak için aşağıdaki örneği kullanabilir ve C:\temp\MyTextFile.txt dosya yolunu değiştirebilirsiniz.

$Attachment = "C:\temp\MyTextFile.txt"
$MailAttachement = [Convert]::ToBase64String([IO.File]::ReadAllBytes($Attachment))

Daha sonra message@{ karma tablosundaki ekleri tanımlayın.

  attachments = @(
			@{
				"@odata.type" = "#microsoft.graph.fileAttachment"
				name = "$Attachment"
				contentType = "text/plain"
				contentBytes = $MailAttachement
			}
    )

Tam gövde karma tablosu artık aşağıdaki gibi görünmelidir:

$body = @{
	message = @{
		subject = "My Microsoft Graph Test Email"
		body = @{
			contentType = "Text"
			content = "Hello, this is a test email"
		}
		toRecipients = @(
			@{
				emailAddress = @{
					address = "[email "
				}
			}
		)
        attachments = @(
			@{
				"@odata.type" = "#microsoft.graph.fileAttachment"
				name = "$Attachment"
				contentType = "text/plain"
				contentBytes = $MailAttachement
			}
        )
	}
	saveToSentItems = "false"
}

Ekleri çevrimiçi indirme

Dosyaları depolamak için daha uygun bir yer merkezi GitHub deposudur. Elbette, belgeleri herkese açık hale getiriyorsanız, bunlar yalnızca temel şablon dosyaları veya işlevsel komut dosyaları olmalıdır (bunlar şirket veya tanımlanabilir veriler içermez; aksi takdirde, özel bir depoya erişmek için bir erişim belirtecine ihtiyaç vardır).

Aşağıdaki örnek, genel GitHub deposundan bir dosya indirmek ve onu bir mesaja eklenmeye hazırlamak için Invoke-WebRequest cmdlet'ini kullanır.

$attachment = Invoke-WebRequest -Uri "https://raw.githubusercontent.com/DanielBradley1/Public/main/Testing/MyTestCSVFile.csv"
$encodedBytes = [System.Text.Encoding]::UTF8.GetBytes($attachment.Content)
$MailAttachment = [System.Convert]::ToBase64String($encodedBytes)

Ek adını dinamik olarak da tanımlamak isteyebilirsiniz; bu durumda, dosya yolundaki son eğik çizgiden sonraki dosya adını seçmek için Regex'i kullanabilirsiniz. Örneğin:

$attachment.BaseResponse.ResponseUri.AbsolutePath -match '([^\/]+$)'
$matches[1]

Kodun tamamı aşağıdaki gibi görünecektir:

$attachment = Invoke-WebRequest -Uri "https://raw.githubusercontent.com/DanielBradley1/Public/main/Testing/MyTestTextFile.txt"
$encodedBytes = [System.Text.Encoding]::UTF8.GetBytes($attachment.Content)
$MailAttachment = [System.Convert]::ToBase64String($encodedBytes)
$attachment.BaseResponse.ResponseUri.AbsolutePath -match '([^\/]+$)'
$matches[1]

$params = @{
	message = @{
		subject = "Automated - Inactive User Report"
		body = @{
			contentType = "Text"
			content = "Please see the attached!"
		}
		toRecipients = @(
			@{
				emailAddress = @{
					address = "[email "
				}
			}
		)
    attachments = @(
			@{
				"@odata.type" = "#microsoft.graph.fileAttachment"
				name = $matches[1]
				contentType = "text/plain"
				contentBytes = $MailAttachment
			}
    )
	}
	saveToSentItems = "false"
    
}

PowerShell nesneleriyle ekler oluşturma

Daha yaygın olarak, PowerShell'i kullanarak raporlar oluşturmanız ve ardından bu verileri bir e-postaya eklenmiş olarak göndermeniz muhtemeldir. Bunu yapmanın basit bir yolu, sabit bir veri dizisi oluşturmak, ardından bunu bir HTML raporuna dönüştürmek ve e-postanıza eklemektir.

Diyelim ki veri diziniz zaten var, buna iyi bir örnek buradaki etkin olmayan kullanıcı raporu komut dosyamdır: https://ourcloudnetwork.com/create-an-inactive-m365-user-report-with-microsoft-graph-powershell /.

Komut dosyamızla oluşturulan $report dizisini bir e-postaya eklemek için, aşağıdaki örneği kullanarak onu HTML biçimine dönüştürebilir, tabloyu düzenlemek için bir kenarlık uygulayabilir ve ardından onu e-postaya eklenmeye hazırlayabilirsiniz.

$report = $report | ConvertTo-Html
$Report = $report -replace '<table>', '<table border="1">'
$encodedBytes = [System.Text.Encoding]::UTF8.GetBytes($report)
$MailAttachment = [System.Convert]::ToBase64String($encodedBytes)

Dosya daha sonra önceki örneklerle aynı şekilde e-postaya eklenebilir.

Send-MgUserMail için tüm e-posta seçenekleri

Temel olarak, Microsoft Graph kullanılarak gönderilebilecek mesaj özelliklerinin birçok başka çeşidi vardır. Özelleştirebileceğiniz bir mesajın özellikleri hakkında daha fazla bilgi edinmek için Microsoft Graph Docs'taki mesaj kaynağı türü belgelerine bakın: https://learn.microsoft.com/en-us/graph/api/resources/message? görünüm=grafik-dinlenme-beta

Daha fazla mülk ekleme konusunda sorun yaşıyorsanız aşağıya yorum yapın; en kısa sürede yardımcı olmaktan memnuniyet duyarım.