使用 Graph PowerShell SDK 创建 SharePoint Online 文件报告

更新 SharePoint Online 文件报告脚本以使用 Graph PowerShell SDK

2022 年 7 月，我撰写了有关使用图形 API 报告 SharePoint Online 文档库中的文件的文章。脚本结构很简单：选择一个站点，选择该站点内的文档库，然后报告在库中找到的文件和文件夹。这是我第一次有机会使用图形 API 使用 SharePoint Online，并且是一次宝贵的学习经历。

随着时间和技术的进步，使用 Microsoft Graph PowerShell SDK 可以完成相同的工作。如果可能的话，我更喜欢使用 Graph PowerShell SDK，因为它更容易使用。 Cmdlet 会在必要时更新访问令牌，并在获取数据时处理分页。 Cmdlet 输出 PowerShell 对象，等等。当然，Graph PowerShell SDK 有一些令人恼火的缺点，但通常我会尽可能尝试使用它的 cmdlet 而不是 Graph API 请求。

Microsoft 于 2023 年发布了 Graph PowerShell SDK V2。我决定重写脚本以使用 Graph SDK cmdlet 来探索 SDK 处理 SharePoint Online 内容的能力。 Microsoft 有一个用于 SharePoint Online 管理的预览版 Graph API，它模仿了 SharePoint Online 管理 PowerShell 模块中提供的一些功能。该模块的开发还没有取得太大进展，这里不做介绍。

SharePoint Online 在其省略号菜单中包含“导出到 Excel”选项。此选项生成 Microsoft Excel Web 查询文件 (.iqy) 以连接到 SharePoint 站点中的当前位置，并将有关项目和文件夹的信息导出到 Excel 工作簿中的表中。有用的是，导出包括默认视图中显示的所有属性。您可以使用此选项而不是我将要解释的脚本，但是您将无法学习如何使用 Graph SDK cmdlet 与 SharePoint Online 交互！

站点、驱动器和 DriveItem

人们熟悉 SharePoint Online 网站的概念。该脚本首先使用 Get-MgSite cmdlet 搜索具有匹配显示名称或描述的网站。第一个示例使用字符串进行搜索，第二个示例使用变量进行搜索：

Get-MgSite -Search 'Projects'
$SiteName = 'Office 365'
Get-MgSite -Search ($SiteName)

SharePoint Online 会修剪网站集以排除登录用户无法访问的任何网站。即使拥有 SharePoint 管理员或全局管理员角色的帐户也无法访问网站，除非他们是网站成员。 Get-MgSite 返回的网站集包括为 Teams 专用和共享频道创建的网站。该脚本通过要求用户选择一个站点来处理此问题。返回的值包括站点标识符，如下所示：

Office365itpros.sharepoint.com,acfe74d8-edfb-436d-924b-e018666605ee,a2aba197-5f1d-4864-a2c7-4daf0ff6379b

SharePoint Online 网站有一个名为“文档”（英文）的默认文档库。但是，一个网站可以跨越多个文档库。在 API 术语中，这些被称为驱动器。 Get-MgSiteDrive cmdlet 获取站点中的驱动器集：

[array]$Drives = Get-MgSiteDrive -SiteId $Site.Id

每个驱动器都有一个标识符 (Id)，如下所示：

b!2HT-rPvtbUOSS-AYZmYF7pehq6IdX2RIosdNrw_2N5t7xp_DBXMQTalVjpKlwdxk

通过站点标识符和驱动器标识符，我们可以获取驱动器中的项目（driveitems）。驱动器包括文件和文件夹，因此需要一些工作来处理这两种类型的项目。该脚本包含一个名为 Get-DriveItems 的函数，用于处理文件夹中的文件，包括对嵌套文件夹中的项目进行递归处理。首先，脚本从根（顶级）文件夹开始：

Get-DriveItems -Drive $Drive.Id -FolderId "root"

为每个文件收集的信息包括其显示名称、所属文件夹、作者和上次修改文件的人员、创建和上次修改日期、文件大小以及是否分配了保留和敏感度标签。图 1 显示了脚本的运行情况。

我测试的最大文件夹包含 6,523 个文件。

获取文件的保留标签

拥有 Office 365 E3 及更高版本的租户支持保留标签。并非每个租户都使用保留标签，因此首先要检查保留标签是否存在。该脚本使用 Get-MgSecurityLabelRetentionLabel cmdlet 来检查保留标签。运行 cmdlet 需要同意 RecordsManagement.Read.All 权限。

# Discover if the tenant uses retention labels
[array]$RetentionLabels = Get-MgSecurityLabelRetentionLabel
If ($RetentionLabels) {
    $Global:RetentionLabelsAvailable = $true
} Else {
    $Global:RetentionLabelsAvailable = $false
}

然后，脚本知道是否应该尝试检索文件的保留标签。 Graph SDK cmdlet 涵盖保留标签的管理，但不包括从文件中检索保留标签信息。为了获取保留标签，该脚本使用图形请求：

If ($RetentionLabelsAvailable -eq $true) {
  Try {
    $Uri = ("https://graph.microsoft.com/v1.0/drives/{0}/items/{1}/retentionLabel" -f $Drive, $File.Id)
   [array]$RetentionLabelInfo = Invoke-MgGraphRequest -Uri $Uri -Method Get
   RetentionLabelName = $RetentionLabelInfo.name
   } Catch {
   Write-Host ("Error reading retention label data from file {0}" -f $File.Name) 
   }
}

获取文件的敏感度标签

Get-MgBetaUserSecurityInformationProtectionSensitivityLabel cmdlet 检索登录用户帐户可用（发布）的敏感度标签，这需要获得 InformationProtectionPolicy.Read 权限的同意。此代码运行 cmdlet 以获取敏感度标签集，并根据标签标识符和名称构建哈希表。还定义了保存敏感度标签支持的文件类型的数组。

$Account = (Get-MgContext).Account
[array]$SensitivityLabels = Get-MgBetaUserSecurityInformationProtectionSensitivityLabel -UserId $Account
If ($SensitivityLabels) {
    $Global:SensitivityLabelsAvailable = $true
    [array]$Global:ValidFileTypes = "docx", "pptx", "xlsx", "pdf"
    $Global:SensitivityLabelsHash = @{}
    ForEach ($Label in $SensitivityLabels) {
        $SensitivityLabelsHash.Add($Label.Id, $Label.Name)
    }
} Else {
    $Global:SensitivityLabelsAvailable = $false
}

要检索文件的敏感度标签，该脚本使用 extractSensitivityLabels API。一个文件可以有多个敏感度标签，但只有一个标签可以通过基于权限管理的加密来应用保护。正如您所看到的，使用了 POST 请求。这是因为 API 会使用敏感度标签的详细信息更新 SharePoint Online 网站。正如我在上一篇文章中指出的，此操作可能会导致生成不兼容的标签错误。

If ($SensitivityLabelsAvailable -eq $true) {
  # Only check for sensitivity labels if they are available
  $FileType = $File.Name.Split(".")[1]
  If ($FileType -in $ValidFileTypes) { 
    $Uri = ("https://graph.microsoft.com/beta/sites/{0}/drive/items/{1}/extractSensitivityLabels" -f $Site.Id, $file.id)
    Try {
     [array]$SensitivityLabelInfo = Invoke-MgGraphRequest -Uri $Uri -Method POST 
     If ($SensitivityLabelInfo.labels.sensitivityLabelId) { 
       [array]$LabelName = $SensitivityLabelsHash[$SensitivityLabelInfo.labels.sensitivityLabelId]
     } Catch {
        Write-Host ("Error reading sensitivity label data from file {0}" -f $File.Name) 
       }
     }
}  

有时，从文件中读取敏感度标签时会发生错误，您会看到如下消息：

从文件第 1 章 - Office 365 概述 - Final.docx 读取敏感度标签数据时出错

发生这种情况的原因之一是文件受到 Office 信息权限管理 (IRM) 而不是敏感度标签的保护。解决方案是通过打开文件信息的“保护文档”部分并将保护设置为无限制访问来从文件中删除 IRM（图 2）。

另一个原因是文件分配了一个敏感度标签，该标签已从租户中删除或更改为子标签或从子标签更改为子标签。这里的解决方案是要求作者（始终有权打开文件）打开该文件并分配不同的敏感度标签。我确信 API 可能会失败还存在其他原因。只是我没有遇到过这些条件。

报告输出

该脚本以每分钟 225 到 300 个文件的速度处理文件。通常，在站点中找到的带有敏感度标签的文件越少，脚本运行的速度就越快。要更快地运行脚本，请编辑代码以删除获取有关租户中定义的敏感度标签集信息的行，以及调用 extractSensitivityLabels API 以从文件中检索敏感度标签的行。

输出是 PowerShell 列表（如图 3 所示）。该脚本还将列表内容导出到 CSV 文件。

您可以从 GitHub 下载完整的脚本。

生成式人工智能使数字碎片变得危险

人们倾向于将文件单独保留在 SharePoint 网站中。保留策略有助于控制不断膨胀的文件数量，但不会删除任何具有较长保留期的保留标签的文件。从图 3 中可以看出，我使用的一些站点包含可追溯到 2017 年的文件。除非租户存储配额面临压力，否则管理员没有理由花时间查找和删除过时的和可能具有误导性的文件。

直到生成人工智能时代到来。 Copilot for Microsoft 365 等工具可以访问登录用户可用的任何站点中的任何文件。 Copilot 不知道文件内容是否准确或相关。内容只是为 Copilot 提供更多的单词来处理，因为它会根据用户提示（请求）生成输出。除非 Copilot 用户仔细检查生成的输出，否则可能会出现不准确的信息。这是从 SharePoint Online 中删除旧的和过时的文件而不是让数字碎片堆积的一个很好的理由。

希望此脚本可以帮助人们了解如何使用 Microsoft Graph PowerShell SDK 导航 SharePoint Online 网站，并深入了解有多少旧内容仍然存在。合乎逻辑的下一步可能是编辑 CSV 文件以删除应保留的项目，并使用剩余的内容作为删除项目 API 删除的输入。这是一个值得写另一篇文章的话题！