使用 allocateSensitivityLabel API 来标记 SharePoint 文件

读取敏感度标签是免费的，但分配敏感度标签需要付费

2023 年初，微软推出了 Graph API 来读取和应用敏感度标签。在 API 可用后发布的一篇文章中，我描述了如何使用 extractSensitivityLabels API 读取 SharePoint Online 中存储的 Office 文档和 PDF 的敏感度标签信息。从那时起，我使用 API 在其他脚本中报告敏感度标签信息，其中包括生成有关存储在 SharePoint Online 文档库中的文件的报告的脚本。总而言之，查找分配给文件的敏感度标签没有问题。

为文件分配敏感度标签是另一回事。 Microsoft 非常高兴租户能够阅读和报告现有的敏感度标签，但他们认为 assignSensitivityLabel API 是“高级 API”。当我写 2023 年的文章时，要获得使用 API 的批准需要与微软官僚机构进行一些曲解，在浪费了几个小时但结果为零后我放弃了。

启用受保护的 API

现在，这个过程变得更加容易，因为 Microsoft 现在允许租户通过将应用程序与 Azure 订阅关联来启用运行 API 的应用程序来使用高级 API。显然，付费使用高级 API 被认为是“在使用它们之前，除了许可和同意之外的额外验证。”

全套计量 API 已在线记录。目前，该集包括备份/导出 Teams 聊天和频道对话（高容量 API）所需的 API、Teams 更改通知以及为文件分配敏感度标签的 API。

弄清楚如何分配敏感度标签

众所周知，Microsoft 365 中有很多新功能可以让任何人忙得不可开交，因此我没有回去测试 assignSensitivityLabel API。但该网站的忠实读者提示需要更多信息。唯一的答案是分解 Visual Studio 代码并查阅 allocateSensitivityLabel API 的文档。

将 Entra ID 应用程序与 Azure 订阅链接

您首先需要注册一个合适的 Entra ID 应用程序。您可以重复使用某个应用程序或创建一个新应用程序。该应用程序有两个目的。其服务主体拥有与数据（在本例中为 SharePoint Online 网站的内容）交互所需的权限，而应用程序标识符是 Azure 知道应用程序有权使用计量 API 的方式。该应用程序需要 X.509 证书进行身份验证。确保应用同意使用 Sites.ReadWrite.All 应用程序权限，因为应用需要能够更新文档库中的文档。

下一步是将应用程序注册与 Azure 订阅链接起来。该链接允许 Microsoft 对应用程序对计量 API 进行的任何调用收费。如果 Azure 订阅中不存在合适的资源组，则需要先创建一个资源组，然后再将应用程序链接到订阅。您还需要知道应用程序和 Azure 订阅的 GUID。

以下是我在 Azure Cloud shell 中输入的用于创建关联的命令。在文本编辑器中准备命令然后将其粘贴到云 shell 中（使用 CTRL-Shift-V）会更容易。图 1 显示了响应。

az resource create --resource-group SensitivityLabels --name AssignLabels --resource-type Microsoft.GraphServices/accounts --properties "{""appId"": ""43685887-266e-46cf-915b-ea69bd84fe25""}" --location Global --subscription 35429342-a1a5-4427-9a2d-551840f2ed25

在使用应用程序运行计量 API 之前未能将应用程序与 Azure 订阅关联会导致 402 错误。

选择要应用的敏感度标签

现在我们有了一个具有链接到 Azure 订阅的正确权限的应用程序，我们可以找到一些要标记的文档。当您调用assignSensitivityLabel API 时，代码必须传递要分配的标签的不可变标识符。您可以通过两种方式找到此信息：

1. 连接到 Exchange Online，然后连接到合规性终结点并运行 Get-Label cmdlet。该 cmdlet 返回租户中所有已知的敏感度标签。有些标签可能仅用于容器管理。只有可应用于文件的标签才能与assignSensitivityLabel API 一起使用。
2. 从 Microsoft Graph PowerShell SDK 运行 Get-MgBetaUserSecurityInformationProtectionSensitivityLabel cmdlet。这相当于运行列出敏感度标签图 API 并返回发布给登录用户的标签集。

以下是使用 Get-Label cmdlet 查找可应用于文件的敏感度标签的示例：

Connect-ExchangeOnline
Connect-IPPSSession
[array]$Labels = Get-Label | Where-Object {$_.ContentType -like "*File*"}
$Labels | Format-Table ImmutableId, DisplayName

ImmutableId                          DisplayName
-----------                          -----------
2fe7f66d-096a-469e-835f-595532b63560 Public
8b652c9a-a8b7-40ec-bb1a-c5334b1b7fef No Encryption
fb0975b2-1ea1-4c3c-850c-e859e690d282 Partner-Accessible Content
27451a5b-5823-4853-bcd4-2204d03ab477 Internal

连接到图表

要使用计量 API，我们需要使用与 Azure 订阅关联的应用程序的标识符连接到 Microsoft Graph PowerShell SDK。连接请求还传递租户标识符（以告诉 Graph 使用哪个租户）和加载到应用程序中的证书的指纹。这是连接命令：

Connect-MgGraph -NoWelcome -AppId $AppId -TenantId $TenantId -CertificateThumbprint $CertThumbprint

之后运行 Get-MgContext cmdlet 应显示连接身份验证为 AppOnly（意味着使用应用程序权限）以及应用程序可用的范围（权限）。在本例中，我们看到 Sites.ReadWrite.All 权限可用。此权限允许应用程序读取和写入租户中任何 SharePoint Online 网站中的数据（更新带有标签的文件需要写入权限）。

Get-MgContext

ClientId               : 43685887-266e-46cf-915b-ea69bd84fe25
TenantId               : a662313f-14fc-43a2-9a7a-d2e27f4f3478
Scopes                 : {Sites.ReadWrite.All}
AuthType               : AppOnly
TokenCredentialType    : ClientCertificate
CertificateThumbprint  : F79286DB88C21491110109A0222348FACF694CBD
CertificateSubjectName :
SendCertificateChain   : False
Account                :
AppName                : AssignSensitivityLabels

从此时开始，代码需要找到目标站点，在站点中选择一个驱动器，并找到该驱动器中的文件。所有这些都是通过标准图形命令完成的，例如有关如何报告文档库内容的文章中描述的脚本中使用的命令。

我重构了该脚本，将敏感度标签分配给尚未具有标签的受支持文件。您可以从 GitHub 下载脚本来分配敏感度标签。这些脚本混合使用 Microsoft Graph PowerShell SDK cmdlet 和使用 Invoke-MgGraphRequest cmdlet 运行的常规图形请求。

将敏感度标签应用于文档

不同的是，当需要将敏感度标签应用于未标记的文件时。 assignSensitivityLabel API 非常简单。您需要知道：

• 存储目标文件的驱动器（文档库）的标识符。
• 目标文件的标识符。
• 要分配给目标文件的敏感度标签的标识符。
• POST 请求的请求正文（有效负载）。有效负载中唯一必需的项目是敏感度标签的标识符。您还可以传递理由和分配方法。

请求正文作为哈希表传递。这是一个例子：

$AssignmentPayload = @{}
$AssignmentPayload.Add("AssignmentMethod", "Auto")
$AssignmentPayload.Add("Justification", "Trying out the assignSensivityLabel API")
$AssignmentPayload.Add("SensitivityLabelId", "27451a5b-5823-4853-bcd4-2204d03ab477")

一切就绪后，将请求发布到 API 就需要执行以下操作：

Write-Host ("Assigning sensitivity label to {0}" -f $File.Name)
$Uri = ("https://graph.microsoft.com/v1.0/drives/{0}/items/{1}/assignSensitivityLabel" -f $Drive.Id, $File.Id)
Try {
    Invoke-MgGraphRequest -Method "POST" -Uri $Uri -Body $AssignmentPayload -OutputType PSObject
    }
Catch {
    Write-Host ("Failed to assign sensitivity label to file {0}" -f $File.Name ) -ForegroundColor Red
}

插入驱动器和文件标识符的值后，用于请求的 URI 将如下所示：

https://graph.microsoft.com/v1.0/drives/b!VjyyeCWK3EGr4WX2V2zF5eWwPtRGxu9AgzwoRtLDUpDOiuY22Vv_SJt-wwtCTPyp/items/0142U6OAA3Z4BZZNZEDFHZ36VBP6I2ZQ2G/assignSensitivityLabel

如果一切顺利，SharePoint Online 会接受为文件添加标签的请求，并且标签将显示在 Office UI、SharePoint 视图等中。

关于分配敏感度标签的一些要点

能够以编程方式为 Office 文档和 PDF 文件分配敏感度标签真是太好了。但是，您确实需要考虑一些要点，包括：

• 自动分配的敏感度标签（例如，使用自动标签策略）不会优先于手动分配的标签。因此，该脚本会忽略已经具有标签的文件。如果需要，您可以检查文档的 extractSensitivityLabels API 返回的标签信息中的分配方法，如果正在应用的标签比现有标签和分配具有更高的优先级，则更新敏感度标签标签是“auto”（由自动标签策略应用）。
• 只有现代格式的 Office 文档和 PDF 文件支持敏感度标签。脚本应忽略其他文件类型。
• extractSensitivityLabels API 无法读取使用双密钥加密的敏感度标签。
• assignSensitivityLabel API 在后台运行，因此敏感度文件的更新是异步发生的。 API 将作业排队等待，直到目标文件被锁定或可更新，然后应用敏感度标签。更新应该在运行请求后十分钟内可见，但我发现更新需要更长的时间才能完成。

我注意到的一个问题是，如果您尝试更新 SharePoint Online 仍在处理的文档的敏感度标签（例如，由于之前的标签更改而更新加密），API 应用的更新似乎会成功，但什么也没发生。

我还观察到，尝试从 PDF 读取敏感度标签信息时会发生许多内部服务器错误。因此，该脚本在处理 PDF 时会忽略这种性质的错误。

成本

每次成功使用 assignSensitivityLabel API 的费用为 0.00185 美元（请参阅计量 API 列表）。图 2 显示了测试脚本以应用标签（似乎适用于大约 75 个文件）时产生的成本。您可以看到成本已分配给在 Azure 中创建的资源的名称。

除非您打算为数以万计的文件分配标签，否则成本不会很高。此计量 API 不会像翻译 SharePoint Online 文档那样收取费用。

不能替代自动标签策略

assignSensitivityLabel API 不能替代自动标签策略。这些策略旨在通过使用敏感信息类型或可训练分类器等标准来识别目标文件，从而处理跨租户的大量 SharePoint Online 文档。 API 的存在是为了处理诸如在选定站点中标记少量文档之类的情况。如果您想结合自动识别目标文档等智能功能，则需要开发代码来查找和识别要标记的文档。

您可能永远不需要以编程方式分配敏感度标签，但很高兴知道如果有必要，这是可能的。