管理 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，请替换相应的主机命名空间和文件级敏感度标签对象。

验证敏感度标签是否可用

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

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

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");
    await context.sync();

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

标识可用的敏感度标签

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

该方法返回一个集合，其项和属性在显式加载它们并调用 context.sync()之前不可用。 有关指南，请参阅 从集合加载。 加载 items 项和加载项所需的标签属性。 可用属性因主机而异。 有关完整列表，请参阅 SensitivityLabelDetails (Excel、PowerPointWord) 。

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");
    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"}`);
    });
});

获取敏感度标签

若要检索当前标签（如果应用了），请 (文件的敏感度标签对象上调用 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, and load its ID and name.
    const currentLabel = documentLabel.getCurrentOrNullObject();
    currentLabel.load("id,name");
    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})`);
    }
});

设置敏感度标签

应用标签之前，getLabels()调用 (Excel、PowerPointWord) ，然后从返回的集合中选择已启用的标签或子标签。 tryToUpdate() Excel、PowerPointWord) (方法需要所选标签的 ID 作为其参数。 首先调用可 getLabels() 让你检索此所需的 ID，并验证当前用户是否可以使用标签。 检查返回SensitivityLabelUpdateResult的 (Excel、PowerPointWord) 值以确定更新是否成功。

注意

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

async function setDocumentSensitivityLabel(labelId: string) {
    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);
        await context.sync();

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

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

注意

该 OnSensitivityLabelChanged 事件仅在 Outlook 中可用。

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

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

另请参阅

  • 上次更新时间为