管理 Office 加载项中的敏感度标签

工作场所协作通常不仅限于组织,还扩展到外部合作伙伴。 在组织网络之外共享信息需要采取措施防止数据丢失并实施合规性策略。 Microsoft Purview 信息保护提供用于对敏感信息进行分类和保护的解决方案。 敏感度标签将此保护应用于 Excel、Outlook、PowerPoint 和 Word 中的数据。

使用 Office JavaScript API 在 Office 加载项项目中实现敏感度标签解决方案,并支持以下方案。

  • 将敏感度标签应用于文档、消息或约会,以符合业务和法律策略。
  • 如果应用了特定敏感度标签,则限制其他操作,例如阻止用户将外部收件人添加到邮件。
  • 根据敏感度标签对数据进行分类,以支持审核和报告。

注意

在 Excel、PowerPoint 和 Word 中,敏感度标签 API 处于预览状态。 在 Outlook 中, 要求集 1.13 中引入了对敏感度标签功能的支持。 有关客户端支持的信息,请参阅 支持的客户端和平台。

先决条件

敏感度标签功能需要 Microsoft 365 E5 订阅。 在计划常见问题解答中检查你是否有资格通过 Microsoft 365 开发人员计划获得 Microsoft 365 E5 开发人员订阅。 否则, 请开始 1 个月的免费试用 版或 购买 Microsoft 365 计划。

支持的客户端和平台

敏感度标签 API 支持因 Office 应用程序和平台而异。 Outlook 支持需要 Exchange Online。 下表列出了支持的组合。

应用程序 Web Windows Mac
Excel 预览 预览 预览
Outlook 支持 支持
(全新和经典 (版本 2304 (内部版本 16327.20248) 或更高版本) )
支持
(版本 16.77 (23081600) 或更高版本)
PowerPoint 预览 预览 预览
Word 预览 预览 预览

配置敏感度标签支持

注意

预览 API 可能会发生更改,不适合在生产环境中使用。 我们建议你仅在测试和开发环境中试用它们。 请勿在生产环境或业务关键文档中使用预览 API。

若要使用预览 API:

Excel、PowerPoint 和 Word 敏感度标签 API 遵循类似的编程模式。 在每个主机中,请求上下文提供对敏感度标签目录的访问权限,而特定于主机的文件对象提供获取或更新其标签的方法。

下表列出了用于访问敏感度标签目录以及应用于每个 Office 主机应用程序中文件的标签的 API 成员。

应用程序 敏感度标签目录 文件上的敏感度标签
Excel context.sensitivityLabelsCatalog context.workbook.sensitivityLabel
PowerPoint context.sensitivityLabelsCatalog context.presentation.sensitivityLabel
Word context.sensitivityLabelsCatalog context.document.sensitivityLabel

以下各节中的示例使用 Word。 若要使用 Excel 或 PowerPoint,请替换相应的主机命名空间和文件级敏感度标签对象。

在 Script Lab 中试用 API

获取 Script Lab 加载项,并尝试适用于 Office 应用程序的管理敏感度标签示例。

这些示例演示如何检查标签功能、列出标签和子标签、检索 ABAC 属性、获取当前标签以及应用带或不带 ABAC 属性的标签。

若要了解详细信息,请参阅使用 Script Lab 探索 Office JavaScript API。

验证敏感度标签是否可用

敏感度标签和策略由组织的管理员通过 Microsoft Purview 合规门户配置。 有关如何在租户中配置敏感度标签的指南,请参阅 创建和配置敏感度标签及其策略。

若要确定当前用户是否可以使用敏感度标签,getLabelingCapability请从敏感度标签目录加载 (Excel、PowerPointWord) 。

状态为 LabelingCapabilityExcel、PowerPointWord) (值,例如 labelingEnabled、 labelingDisabledlabelingPolicyNotFound、 或 noLicense。 若要检查其他功能,请 (Excel、PowerPointWord) 加载getLabelingCapabilities数组。 例如,在attributeBasedAccessControlEnabled检索基于属性的访问控制 (ABAC) 属性之前检查。

await Word.run(async (context) => {
    // Access the sensitivity label catalog for the current user.
    const labelCatalog = context.sensitivityLabelsCatalog;
    if (!labelCatalog) {
        console.warn("The sensitivity label catalog isn't available.");
        return;
    }

    // Load the labeling capability status before reading it.
    labelCatalog.load("getLabelingCapability,getLabelingCapabilities");
    await context.sync();

    // Display whether sensitivity labeling is enabled and available.
    console.log(`Sensitivity labeling capability: ${labelCatalog.getLabelingCapability}`);
    console.log("Available labeling capabilities:", labelCatalog.getLabelingCapabilities);
});

标识可用的敏感度标签

若要检索发布给当前用户的标签,请调用getLabels()目录上的 Excel、PowerPointWord () 。

该方法返回一个集合,其项和属性在显式加载它们并调用 context.sync()之前不可用。 有关指南,请参阅 从集合加载。 加载 items 项和加载项所需的标签属性。 SensitivityLabelDetails Excel、PowerPointWord) (对象提供以下信息。

  • 标签的 ID、名称、说明 (tooltip) 、颜色、顺序和租户 ID (siteId) 。
  • 标签是否启用 (isEnabled) 及其保护类型 (protectionType) 。
  • 集合中的 children 子标签。 显式加载加载项所需的子标签属性。
  • 标签是否支持 ABAC (isAbacEnabled) ,是否需要选择属性 (isAbacAttributesRequired) 。
await Word.run(async (context) => {
    // Access the sensitivity label catalog for the current user.
    const labelCatalog = context.sensitivityLabelsCatalog;
    if (!labelCatalog) {
        console.warn("The sensitivity label catalog isn't available.");
        return;
    }

    // Get the available labels and load the properties used by the add-in.
    const availableLabels = labelCatalog.getLabels();
    availableLabels.load(
        "items/id,items/name,items/isEnabled,items/isAbacEnabled,items/isAbacAttributesRequired," +
        "items/children/items/id,items/children/items/name,items/children/items/isEnabled"
    );
    await context.sync();

    // Display the available labels.
    console.log("Available sensitivity labels:");
    availableLabels.items.forEach((label) => {
        console.log(`${label.name} (${label.id}) - ${label.isEnabled ? "Enabled" : "Disabled"}`);
        console.log(`ABAC enabled: ${label.isAbacEnabled}; attributes required: ${label.isAbacAttributesRequired}`);
        if (label.children) {
            label.children.items.forEach((sublabel) => {
                console.log(`  ${sublabel.name} (${sublabel.id}) - ${sublabel.isEnabled ? "Enabled" : "Disabled"}`);
            });
        }
    });
});

获取敏感度标签

若要检索当前标签(如果应用了),请 (文件的敏感度标签对象上调用 getCurrentOrNullObject()Excel、PowerPointWord) 。

await Word.run(async (context) => {
    // Access the sensitivity label applied to the current document.
    const documentLabel = context.document.sensitivityLabel;

    // Get the current label, if one is applied.
    const currentLabel = documentLabel.getCurrentOrNullObject();
    currentLabel.load("id,name,isAbacEnabled");
    await context.sync();

    // Display the current label or report that the document isn't labeled.
    if (currentLabel.isNullObject) {
        console.log("The document doesn't have a sensitivity label.");
    } else {
        console.log(`Current label: ${currentLabel.name} (${currentLabel.id})`);
        if (currentLabel.isAbacEnabled) {
            currentLabel.load("abacAttributeValues");
            await context.sync();
            console.log("Applied ABAC attribute values:", currentLabel.abacAttributeValues);
        }
    }
});

设置敏感度标签

应用标签之前,getLabels()调用 (Excel、PowerPointWord) ,然后从返回的集合中选择已启用的标签或子标签。 tryToUpdate() Excel、PowerPointWord) (方法需要所选标签的 ID 作为其第一个参数,并接受 Excel、PowerPointWord) (可选SensitivityLabelTryUpdateOptions对象以选择 ABAC 属性。 首先调用使 getLabels() 您可以检索所需的 ID 并验证标签是否对当前用户可用。

调用context.sync()后,读取updateResult.value.status返回的SensitivityLabelUpdateResult对象 (Excel、PowerPointWord) 。 将其与 SensitivityLabelUpdateStatus.success (Excel、PowerPointWord) 进行比较,以确定更新是否成功。

注意

不能直接应用具有子标签的父标签。 请改为选择其启用的子标签之一。

async function setDocumentSensitivityLabel(labelId: string, options?: Word.SensitivityLabelTryUpdateOptions) {
    await Word.run(async (context) => {
        // Access the sensitivity label applied to the current document.
        const documentLabel = context.document.sensitivityLabel;

        // Apply the selected label.
        const updateResult = documentLabel.tryToUpdate(labelId, options);
        await context.sync();

        // Check whether the label update succeeded.
        if (updateResult.value.status === Word.SensitivityLabelUpdateStatus.success) {
            console.log("Applied the sensitivity label to the document.");
        } else {
            console.error(`The sensitivity label wasn't applied. Status: ${updateResult.value.status}`);
        }
    });
}

应用具有 ABAC 属性的标签

对于启用 ABAC 的标签,通过 SensitivityLabelsCatalog.getAttributes() (Excel、PowerPointWord) 检索可用属性。 首先,加载 getLabelingCapabilities 并验证它是否包含 LabelingCapability.attributeBasedAccessControlEnabled. 该方法返回其ClientResultvalue属性包含 Excel、PowerPointWord) (对象数组SensitivityLabelAbacAttribute。 在读取此属性之前调用 context.sync() 。

每个属性都有显示名称、显示顺序、数据类型、活动状态、 isMultiValued 标志和 values 数组。

await Word.run(async (context) => {
    const labelCatalog = context.sensitivityLabelsCatalog;
    if (!labelCatalog) {
        console.warn("The sensitivity label catalog isn't available.");
        return;
    }

    labelCatalog.load("getLabelingCapabilities");
    await context.sync();

    if (!labelCatalog.getLabelingCapabilities.includes(Word.LabelingCapability.attributeBasedAccessControlEnabled)) {
        console.warn("ABAC attributes aren't enabled or available for the current user.");
        return;
    }

    const catalogAttributes: OfficeExtension.ClientResult<Word.SensitivityLabelAbacAttribute[]> =
        labelCatalog.getAttributes();
    await context.sync();

    console.log("Available ABAC attributes:", catalogAttributes.value);
});

要应用具有 ABAC 属性的标签,请使用目录中的属性,并在每个属性的 values 数组中仅包含用户选择的值。 仅使用活动属性和活动值,仅在 为true时允许isMultiValued多个值。 在应用标签之前,请根据当前策略验证所选内容。

通过提供给 tryToUpdate()的 options 对象的属性传递abacAttributes所选属性。 以下规则适用。

  • 如果为 ,则isAbacEnabled省略abacAttributes或传递空数false组。 否则,更新状态为 abacAttributesNotAllowed。
  • 如果 和 isAbacAttributesRequired 都true为 ,则isAbacEnabled提供属性选择。 否则,更新状态为 abacAttributesRequired。
  • 检查更新状态是否存在其他故障,例如 unsupportedAbac、 labelDisabled或 insufficientPermission。 完成 context.sync() 并不意味着应用了标签。

若要读取当前应用于文件的 ABAC 值,请加载 abacAttributeValues 返回的对象 getCurrentOrNullObject(),如获取 敏感度标签中所示。 在isNullObjectisAbacEnabled加载值之前检查。

使用 OnSensitivityLabelChanged 事件检测敏感度标签更改

注意

该 OnSensitivityLabelChanged 事件仅在 Outlook 中可用。

当邮件或约会上的敏感度标签更改时,使用 OnSensitivityLabelChanged 该事件运行加载项逻辑。 例如,防止用户降级包含某些附件的邮件项的标签。

OnSensitivityLabelChanged该事件使用基于事件的激活。 有关配置、调试和部署指南,请参阅 通过事件激活加载项。

另请参阅