sensitivityLabel 资源类型

命名空间：microsoft.graph.security

描述信息保护标签，其中详细介绍了如何正确将敏感度标签应用于信息。 informationProtectionLabel 资源描述应用于用户或租户的敏感度标签的配置。

方法

属性

敏感度标签 API 筛选规则

本部分概述了可用于各种敏感度标签 API 调用的筛选规则和约束。

方案 1：返回敏感度标签 (1 个或多个)

用户调用 API 并按一个或多个标签 ID GUID 筛选。

示例

$filter=((id eq 'guid1') or (id eq 'guid2') or (id eq 'guid3'))

Rules

1. isScopedToUser 的 OR 限制

   • 如果 isScopedToUser 存在筛选器参数，则 or 不允许在筛选器参数中使用

2. 使用 OR 的预筛选行为

   • 如果 or 筛选器参数中存在 ，则 locale 和 contentFormats 筛选器参数 (如果存在) 将不用于预筛选

3. 内部 OR 异常

   • or允许属于参数树的内部作

方案 2：对单个 ID 和用户权限使用筛选器返回敏感度标签的结果

用户按一个标签 ID GUID 和一个用户权限调用 API 并筛选。

示例

$filter=(id eq 'guid1' and ownerEmail eq 'ownerEmail1')

Rules

1. 具有多个参数的 OR 限制

   • 如果存在以下任何筛选器参数： isScopedToUser、 id或 ownerEmail，则 or 不允许在筛选器参数中使用

2. ownerEmail 验证

   • ownerEmail 如果不存在 id ，则 ArgumentException引发 。

3. 使用 OR 的预筛选行为

   • 如果 or $filter 字符串中存在 ，则 locale 和 contentFormats 筛选器参数将被忽略，并且不用于预筛选结果。

4. 内部 OR 异常

   • 可以在各个子句之间使用内部 or 作。

方案 2.5：使用多个 ID 和用户权限筛选器返回敏感度标签的结果

用户希望调用 API 并按多个 ID 和 ownerEmail 进行筛选。 若要实现此结果，必须将标签 ID 和 ownerEmail 合并到一个布尔子句中。

示例

$filter=(
   (id eq 'guid1' and ownerEmail eq 'ownerEmail1')
  or (id eq 'guid2')
  or (id eq 'guid3' and ownerEmail eq 'ownerEmail2')
)

此 $filter 模式是标准 OData 规范的扩展。 在标准 OData 中，通常不支持以这种方式将多个元组与 组合在一起 or 。 但是，此 API 允许你使用基于元组的 OR 模式，在该模式中，每对单独 (id, ownerEmail) 计算，并合并生成的权限信息。 有关标准 OData $filter 行为的详细信息，请参阅 OData 规范。

我们建议使用具有多个 ID 的单个调用的筛选器来检索多个标签的权限，因为它可以减少需要从应用进行 API 调用的次数。

ownerEmail 是可选的，可以省略以仅提取标签级权限。

Rules

1. 严格 OR 模式

   • 仅支持由上述 OR作组合的基于元组的结构。

   • 不允许任何其他 OR作组合或混合不相关的筛选器，并导致 ArgumentException。

2. ownerEmail 验证

   • ownerEmail 必须始终与 id一起显示。 单独使用 ownerEmail 会导致 ArgumentException。

3. 内部 OR 异常

   • 可以使用子集组合子句。 下面是子示例： (id eq 'guid1' 和 ownerEmail eq 'ownerEmail1')

   • 在此示例中，有三个子项。 将 ID 和 ownerEmail 组合在一起时，请在子表中使用 AND。 请勿使用 OR，否则会引发异常。

4. 预筛选行为

   • 使用 时 or ， locale 和 contentFormats 参数 (（如果提供了) ，则忽略预筛选。

行为摘要

方案 3：敏感度标签权限 /id/rights

Rules

1. 使用 ownerEmail 的 OR 限制

   • or 具有筛选器参数 ownerEmail 的作会导致异常。

2. 内部 OR 异常

   • or允许参数树下的内部作。

isScopedToUser 参数规则

本部分概述了敏感度标签 API 中 参数的行为和约束 isScopedToUser 。

参数行为

isScopedToUser = true

• 结果：仅显示已启用的标签
• 用例：Standard筛选活动/已启用的标签
• 状态：建议的用法

isScopedToUser = false

• 结果：仅显示禁用的标签
• 用例：受限 - 理想情况下不与此值一起使用
• 状态：不建议用于典型作

isScopedToUser 未传递

• 结果：显示 (启用和禁用的所有标签)
• 用例：全面的标签检索
• 状态：省略参数时的默认行为

限制

租户标签异常

• 行为：获取租户标签时，使用 isScopedToUser 将引发 ArgumentException
• 原因：参数不适用于租户级标签作
• 解决方案：使用租户标签时省略 isScopedToUser 参数

关系

JSON 表示形式

以下 JSON 表示形式显示了资源类型。

{
  "@odata.type": "#microsoft.graph.security.sensitivityLabel",
  "actionSource": "String",
  "applicableTo": "String",
  "applicationMode": "String",
  "assignedPolicies": [{"@odata.type": "microsoft.graph.labelPolicy"}],
  "autoLabeling": {"@odata.type": "microsoft.graph.autoLabeling"},
  "autoTooltip": "String",
  "color": "String",
  "description": "String",
  "displayName": "String",
  "hasProtection": "Boolean",
  "id": "String (identifier)",
  "isDefault": "Boolean",
  "isEnabled": "Boolean",
  "isEndpointProtectionEnabled": "Boolean",
  "isScopedToUser": "Boolean",
  "labelActions": [{"@odata.type": "microsoft.graph.encryptWithUserDefinedRights"}],
  "locale": "String",
  "name": "String",
  "priority": "Int32",
  "toolTip": "String"
}