使用 PowerShell 为域创建邮件活动使用情况报告

有人问我生成有关 Microsoft 365 租户中每个域发送的电子邮件数量的报告有多容易。我最初的回应主要集中在消息跟踪日志上，其想法是您可以提取每封出站电子邮件的域并对其进行计数。这是一个坏主意。消息跟踪日志仅保存最近十天的数据，并且充斥着有关系统消息的信息，例如公用文件夹复制（对于仍然使用公用文件夹的用户）。无论如何，提取和提炼信息来回答问题都需要花费大量的工作。

邮件使用报告

然后我灵机一动。为什么不使用 Microsoft 生成的邮件使用情况报告在 Microsoft 365 管理中心等地方使用？ Graph GetEmailActivityUserDetail API 返回过去 7、30、90 或 180 天内用户的邮件活动数据。例如，此命令返回过去 90 天的活动数据并将其存储在 CSV 文件中：

Invoke-MgGraphRequest -Uri "https://graph.microsoft.com/v1.0/reports/getEmailActivityUserDetail(period='D90')" -OutputFilePath 'c:\temp\Data.csv'

为每个用户帐户返回的数据如下所示：

Report Refresh Date      : 2023-07-22
User Principal Name      : [email protected]
Display Name             : Jeff Clark
Is Deleted               : False
Deleted Date             :
Last Activity Date       : 2023-07-22
Send Count               : 129
Receive Count            : 637
Read Count               : 692
Meeting Created Count    : 0
Meeting Interacted Count : 0
Assigned Products        : OFFICE 365 E3
Report Period            : 90

此外，由于 Microsoft 每天都会计算邮件活动数据（总是晚几天），因此获取此数据将比尝试检索和处理消息跟踪事件更快、更具可扩展性。

最重要的是，我在 Microsoft 365 用户活动脚本中使用这些 API，因此我可以重新调整一些代码的用途。

Microsoft Graph PowerShell SDK 访问使用数据

使用 Graph API 请求通常意味着您需要一个注册的应用程序来持有运行请求所需的权限。 Microsoft Graph PowerShell SDK 包含用于访问用户活动数据的 cmdlet，如果您想要运行交互式命令或交互式脚本，这会使事情变得稍微容易一些。例如，要获取最近 7 天的邮件使用活动，请使用所需的权限连接到图表（读取活动数据、读取用户信息的目录以及更改用户隐藏设置 - 我们稍后会介绍） ，然后运行 Get-MgReportEmailActivityUserDetail cmdlet：

Connect-MgGraph -Scopes ReportSettings.ReadWrite.All, Directory.Read.All, Reports.Read.All
Get-MgReportEmailActivityUserDetail -Period 'D7' -OutFile 'c:\temp\d7.csv'

我编写的脚本执行了以下初始步骤：

• 运行 Get-MgReportEmailActivityUserDetail 以检索 7、30、90 和 180 天的邮件使用数据。
• 该 cmdlet 将邮件使用数据写入 CSV 文件。我们最终得到 4 个文件，每个时期一个，脚本可以将其导入到一个数组中。
• 使用 Get-MgUser 查找所有许可的用户帐户。我使用的代码是：

[array]$Users = Get-MgUser -Filter "assignedLicenses/`$count ne 0 and userType eq 'Member'" -ConsistencyLevel eventual -CountVariable Records -All | Sort-Object UserPrincipalName

• 对于每个帐户，获取其邮件使用活动并构建该帐户在 6、30、90 和 180 天内的邮件活动地图。
• 将信息写入 PowerShell 列表。

这是我写的代码：

Write-Output "Fetching mail activity usage report data..."
Get-MgReportEmailActivityUserDetail -Period 'D7' -OutFile 'c:\temp\d7.csv'
Get-MgReportEmailActivityUserDetail -Period 'D30' -OutFile 'c:\temp\d30.csv'
Get-MgReportEmailActivityUserDetail -Period 'D90' -OutFile 'c:\temp\d90.csv'
Get-MgReportEmailActivityUserDetail -Period 'D180' -OutFile 'c:\temp\d180.csv'
# Import the data into arrays
[array]$D7Data = Import-CSV 'c:\temp\d7.csv' | Sort-Object 'User Principal Name'
[array]$D30Data = Import-CSV 'c:\temp\d30.csv' | Sort-Object 'User Principal Name'
[array]$D90ata = Import-CSV 'c:\temp\d90.csv' | Sort-Object 'User Principal Name'
[array]$D180Data = Import-CSV 'c:\temp\d180.csv' | Sort-Object 'User Principal Name'

# Process mailboxes
$Report = [System.Collections.Generic.List[Object]]::new()
ForEach ($User in $Users) {
    [array]$D7Email = $D7Data | Where-Object {$_.'User Principal Name' -eq $User.UserPrincipalName}
    [array]$D30Email = $D30Data| Where-Object {$_.'User Principal Name' -eq $User.UserPrincipalName}
    [array]$D90Email = $D90ata | Where-Object {$_.'User Principal Name' -eq $User.UserPrincipalName}
    [array]$D180Email = $D180Data | Where-Object {$_.'User Principal Name' -eq $User.UserPrincipalName}

    If ($D7Email.'Report Refresh Date') {
      $ReportDate = Get-Date($D7Email.'Report Refresh Date') -format dd-MMM-yyyy
    } Else {
      $ReportDate = $Null }

    If ($D7Email.'Last Activity Date') {
      $LastActivityDate = Get-Date($D7Email.'Last Activity Date') -format  dd-MMM-yyyy   
    } Else {                              
      $LastActivityDate = $Null }      
    
    $ReportLine = [PSCustomObject] @{  
        User            = $User.UserPrincipalName
        Name            = $User.DisplayName      
        'Data Date'     = $ReportDate            
        'Last Activity' = $LastActivityDate      
        'D7 Mail In'    = $D7Email.'Receive Count'
        'D7 Mail Out'   = $D7Email.'Send Count'         
        'D30 Mail In'   = $D30Email.'Receive Count'  
        'D30 Mail Out'  = $D30EMail.'Send Count'     
        'D90 Mail In'   = $D90Email.'Receive Count'   
        'D90 Mail Out'  = $D90Email.'Send Count'      
        'D180 Mail In'  = $D180Email.'Receive Count'  
        'D180 Mail Out' = $D180Email.'Send Count'     
        Domain         = $User.Mail.Split('@')[1]}    
    $Report.Add($ReportLine)               
}    

我们现在有一系列用户帐户记录。看起来像这样：

User          : [email protected]
Name          : Jeff Clark
Data Date     : 22-Jul-2023
Last Activity : 22-Jul-2023
D7 Mail In    : 53
D7 Mail Out   : 9
D30 Mail In   : 105
D30 Mail Out  : 17
D90 Mail In   : 200
D90 Mail Out  : 27
D180 Mail In  : 637
D180 Mail Out : 129
Domain        : Office365itpros.com

将数据传送到 Out-GridView 可以很好地概述四个时期内帐户的邮件使用活动（图 1）。

为了计算域的电子邮件活动，该脚本运行 Get-MgDomain cmdlet 来获取租户的一组注册域，并循环访问域以获取有关预先捕获的用户活动的信息。然后，它测量 180 天发送的邮件数据的总和，以计算使用该域的人员发送的电子邮件总数。代码如下：

[array]$Domains = Get-MgDomain | Select-Object -ExpandProperty Id 
$OutputData = [System.Collections.Generic.List[Object]]::new()     
ForEach ($Domain in $Domains) {                         
    $DomainData = $Report | Where-Object {$_.Domain -eq $Domain}  
    $DomainSendCount = ($DomainData.'D180 Mail out' | Measure-Object -Sum).Sum 
    $DomainOutput = [PSCustomObject] @{   
       'Domain'     = $Domain          
       'Send Count' = $DomainSendCount } 
    $OutputData.Add($DomainOutput)                                                          
 }                                                                                                        

# Display the domain data
$OutputData | Sort-Object 'Send Count' -Descending

结果输出如下所示：

Domain                             Send Count
------                             ----------
redmondwork.org                          2503
office365itpros.com                       212
office365itproebook.com                     0

处理混淆的用户数据

当然，无需编写 PowerShell 来访问使用数据。您可以转到 Microsoft 365 管理中心，然后将电子邮件活动数据下载到 CSV 文件中（图 2）。运行 Excel 来处理 CSV 文件，并进行排序和一些求和，很快就会显示信息。

但请查看 Microsoft 365 管理中心中报告的信息。它被混淆了，因为租户的报告设置规定应隐藏个人信息。管理员可以更改报告设置以公开真实信息，但这只是一个麻烦，并且存在该设置不会重置为其原始值的可能性。

幸运的是，我们可以在代码中处理这种情况。此代码片段检查显示隐藏名称设置是否为 True。如果是，脚本会将其重置为 False 以公开真实数据。

If ((Get-MgBetaAdminReportSetting).DisplayConcealedNames -eq $True) {
    $Parameters = @{ displayConcealedNames = $False }
    Update-MgBetaAdminReportSetting -BodyParameter $Parameters
    $DisplayConcealedNames = $True
}

处理完成后，脚本可以使用以下命令将值重置为 True：

If ($DisplayConcealedNames -eq $True) {
    $Parameters = @{ displayConcealedNames = $True }
    Update-MgBetaAdminReportSetting -BodyParameter $Parameters
    $DisplayConcealedNames = $Null
}

更改显示隐藏名称设置是脚本需要 ReportSettings.ReadWrite.All 权限的原因。您可以从 GitHub 下载完整的脚本。

永远不要在 PowerShell 上浪费时间

这是对一个我认为会很快的问题的冗长回答。但是，编写 PowerShell 永远不会浪费时间，此响应使我能够展示如何使用 Microsoft Graph for PowerShell SDK (V2) 下载使用数据和更改报告设置。你永远不知道这些知识什么时候会有用！

按需迁移

使用一种全面的 Office 365 租户到租户迁移解决方案迁移所有工作负载和 Active Directory。