driveItem:assignSensitivityLabel

命名空间:microsoft.graph

重要

Microsoft Graph /beta 版本下的 API 可能会发生更改。 不支持在生产应用程序中使用这些 API。 若要确定 API 是否在 v1.0 中可用,请使用 版本 选择器。

driveItem 异步分配敏感度标签。

此 API 是执行高级管理功能的 Microsoft SharePoint 和 OneDrive API 的一部分,被视为受保护的 API。 受保护的 API 要求你进行更多验证(超出权限和同意),然后才能使用它们。

注意

这是按流量计费的 API,可能会收取一些使用费用。 有关详细信息,请参阅 Microsoft Graph 中按流量计费的 Microsoft 365 API 概述。 在调用此 API 之前,必须在 Microsoft Graph 中启用按流量计费的 API 和服务

此 API 将敏感度标签应用于静态文件。 Office 客户端不会对包含标签信息的文件应用水印、页眉或页脚。 有关管理员角度的敏感度标签的详细信息,请参阅 在 SharePoint 和 OneDrive 中为 Office 文件启用敏感度标签

此 API 可用于以下国家级云部署

全局服务 美国政府 L4 美国政府 L5 (DOD) 由世纪互联运营的中国

权限

为此 API 选择标记为最低特权的权限。 只有在应用需要它时,才使用更高的特权权限。 有关委派权限和应用程序权限的详细信息,请参阅权限类型。 要了解有关这些权限的详细信息,请参阅 权限参考

权限类型 最低特权权限 更高特权权限
委派(工作或学校帐户) Files.ReadWrite.All Sites.ReadWrite.All
委派(个人 Microsoft 帐户) 不支持。 不支持。
应用程序 Files.ReadWrite.All Sites.ReadWrite.All

HTTP 请求

POST /drives/{drive-id}/items/{item-id}/assignSensitivityLabel
POST /drives/{drive-id}/root:/{item-path}:/assignSensitivityLabel
POST /groups/{group-id}/drive/items/{item-id}/assignSensitivityLabel
POST /groups/{group-id}/drive/root:/{item-path}:/assignSensitivityLabel
POST /me/drive/items/{item-id}/assignSensitivityLabel
POST /me/drive/root:/{item-path}:/assignSensitivityLabel
POST /sites/{site-id}/drive/items/{item-id}/assignSensitivityLabel
POST /sites/{site-id}/drive/root:/{item-path}:/assignSensitivityLabel
POST /users/{user-id}/drive/items/{item-id}/assignSensitivityLabel
POST /users/{user-id}/drive/root:/{item-path}:/assignSensitivityLabel

请求标头

名称 说明
Authorization 持有者 {token}。 必填。 详细了解 身份验证和授权

请求正文

在请求正文中,提供要分配给给定文件的敏感度标签的 ID。 下表列出了必需的和可选的输入参数。

名称 说明
sensitivityLabelId String 必填。 要分配的敏感度标签的 ID,或用于删除敏感度标签的空字符串。
assignmentMethod sensitivityLabelAssignmentMethod 可选。 文档上标签的赋值方法。 指示标签的分配是自动、标准还是作为特权操作完成, (与管理员操作) 等效。
justificationText String 可选。 用于审核目的的理由文本。 降级或删除标签时是必需的。

响应

如果成功,API 将返回响应 202 Accepted 正文为空的 HTTP 响应代码。 标头 Location 提供用于获取操作详细信息的 URL。 有关如何监视分配敏感度标签操作的进度的详细信息,请参阅 监视长时间运行的操作

除了适用于 Microsoft Graph 的常规错误外,此 API 还 423 Locked 返回响应代码,该代码指示正在访问的文件已锁定。 在这种情况下,响应对象的 code 属性指示阻止操作的错误类型。 此外,应用程序无法更新少数 Irm Protected 敏感度标签,并且需要委派用户访问权限来验证用户是否具有适当的权限。 对于这些方案,API 会 Not Supported 引发响应代码。

下表列出了错误类型的可能值。

说明
fileDoubleKeyEncrypted 指示文件通过双密钥加密进行保护;因此,无法打开它。
fileDecryptionNotSupported 指示加密文件具有不允许 SharePoint 打开这些文件的特定属性。
fileDecryptionDeferred 指示正在处理文件以用于解密;因此,无法打开它。
unknownFutureValue 可演变枚举 sentinel 值。 请勿使用。

示例

请求

以下示例显示了一个请求。

POST https://graph.microsoft.com/beta/drive/root/items/016GVDAP3RCQS5VBQHORFIVU2ZMOSBL25U/assignSensitivityLabel
Content-Type: application/json

{
  "sensitivityLabelId": "5feba255-812e-446a-ac59-a7044ef827b5",
  "assignmentMethod": "standard",
  "justificationText": "test_justification"
}

响应

以下示例显示了相应的响应。

HTTP/1.1 202 Accepted
Location: https://contoso.sharepoint.com/_api/v2.0/monitor/QXNzaWduU2Vuc2l0aXZpdHlMYWJlbCxiMzc3ODY3OS04OWQ3LTRkYmYtYjg0MC1jYWM1NzRhY2FlNmE?tempAuth=eyJ0eXAiOiJKV1QiLCJhb....

标头的值 Location 提供服务的 URL,该服务将返回分配敏感度标签操作的当前状态。 可以使用此信息 来确定分配敏感度标签操作何时完成

备注

来自 API 的响应仅指示已接受或拒绝分配敏感度标签操作。 操作可能会被拒绝,例如,如果文件类型不受支持,或者文件是双重加密的。