在撰写模式下管理邮件或约会的敏感度标签

项目
04/12/2024

工作场所中的协作不仅发生在组织内部，而且延伸到外部合作伙伴。由于信息在组织网络之外共享，因此必须制定防止数据丢失并强制实施合规性策略的措施。 Microsoft Purview 信息保护可帮助你实现对敏感信息进行分类和保护的解决方案。在 Outlook 中使用敏感度标签是一项可以配置为保护数据的功能。

可以使用 Office JavaScript API 在 Outlook 外接程序项目中实现敏感度标签解决方案，并支持以下方案。

撰写某些邮件和约会时自动应用敏感度标签，以便用户可以专注于其工作。
如果对邮件或约会应用了特定敏感度标签，例如阻止用户向邮件添加外部收件人，则限制其他操作。
根据邮件或约会的敏感度标签向邮件或约会添加页眉或页脚，以符合业务和法律策略。

注意

要求集 1.13 中引入了对敏感度标签功能的支持。有关此功能的客户端支持的信息，请参阅支持的客户端和平台。

先决条件

若要在外接程序中实现敏感度标签功能，必须具有Microsoft 365 E5订阅。你可能有资格通过 Microsoft 365 开发人员计划获得Microsoft 365 E5开发人员订阅;有关详细信息，请参阅常见问题解答。或者，可以注册 1 个月的免费试用版或购买 Microsoft 365 计划。

支持的客户端和平台

下表列出了支持在 Outlook 外接程序中使用敏感度标签功能的客户端-服务器组合。不支持排除的组合。

客户端	Exchange Online
Web 浏览器 (新式 UI) 新的 Outlook on Windows	支持
Windows (经典) 版本 2304 (内部版本 16327.20248) 或更高版本	支持
Mac 版本 16.77 (23081600) 或更高版本	支持
Android	不适用
iOS	不适用

配置清单

若要在 Outlook 外接程序项目中使用敏感度功能，必须在外接程序清单中配置 读/写项目 权限。

Microsoft 365 的统一清单：在“authorization.permissions.resourceSpecific”数组中，将对象的“name”属性设置为“MailboxItem.ReadWrite.User”。
仅外接程序清单：将 <Permissions> 元素设置为 ReadWriteItem。

如果外接程序将检测并处理事件 OnSensitivityLabelChanged ，则需要其他清单配置才能启用基于事件的激活功能。若要了解详细信息，请参阅使用 OnSensitivityLabelChanged 事件检测敏感度标签更改。

验证敏感度标签目录的状态

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

在获取或设置邮件或约会的敏感度标签之前，必须先确保在安装加载项的邮箱上启用了敏感度标签目录。若要检查敏感度标签目录的状态，请在撰写模式下调用 context.sensitivityLabelsCatalog.getIsEnabledAsync。

// Check whether the catalog of sensitivity labels is enabled.
Office.context.sensitivityLabelsCatalog.getIsEnabledAsync((asyncResult) => {
    if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
        console.log(asyncResult.value);
    } else {
        console.log("Action failed with error: " + asyncResult.error.message);
    }
});

识别可用的敏感度标签

如果要确定在撰写模式下可用于邮件或约会的敏感度标签，请使用 context.sensitivityLabelsCatalog.getAsync。可用标签以 SensitivityLabelDetails 对象的形式返回，这些对象提供以下详细信息。

标签的名称。
标签 (GUID) 的唯一标识符。
标签的说明。
分配给标签的颜色。
配置的子标签（如果有）。

以下示例演示如何标识目录中可用的敏感度标签。

// It's recommended to check the status of the catalog of sensitivity labels before
// calling other sensitivity label methods.
Office.context.sensitivityLabelsCatalog.getIsEnabledAsync((asyncResult) => {
    if (asyncResult.status === Office.AsyncResultStatus.Succeeded && asyncResult.value == true) {
        // Identify available sensitivity labels in the catalog.
        Office.context.sensitivityLabelsCatalog.getAsync((asyncResult) => {
            if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
                const catalog = asyncResult.value;
                console.log("Sensitivity Labels Catalog:");
                catalog.forEach((sensitivityLabel) => {
                    console.log(`Name: ${sensitivityLabel.name}`);
                    console.log(`ID: ${sensitivityLabel.id}`);
                    console.log(`Tooltip: ${sensitivityLabel.tooltip}`);
                    console.log(`Color: ${sensitivityLabel.color}`);
                    console.log(`Sublabels: ${JSON.stringify(sensitivityLabel.children)}`);
                });
            } else {
                console.log("Action failed with error: " + asyncResult.error.message);
            }
        });
    } else {
        console.log("Action failed with error: " + asyncResult.error.message);
    }
});

获取邮件或约会的敏感度标签

若要获取当前应用于撰写模式下的邮件或约会的敏感度标签，请调用 item.sensitivityLabel.getAsync ，如以下示例所示。这将返回敏感度标签的 GUID。

// It's recommended to check the status of the catalog of sensitivity labels before
// calling other sensitivity label methods.
Office.context.sensitivityLabelsCatalog.getIsEnabledAsync((asyncResult) => {
    if (asyncResult.status === Office.AsyncResultStatus.Succeeded && asyncResult.value == true) {
        // Get the current sensitivity label of a message or appointment.
        Office.context.mailbox.item.sensitivityLabel.getAsync((asyncResult) => {
            if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
                console.log(asyncResult.value);
            } else {
                console.log("Action failed with error: " + asyncResult.error.message);
            }
        });
    } else {
        console.log("Action failed with error: " + asyncResult.error.message);
    }
});

在邮件或约会上设置敏感度标签

在撰写模式下，只能在邮件或约会上设置一个敏感度标签。在设置标签之前，请调用 context.sensitivityLabelsCatalog.getAsync。这可确保要应用的标签可供使用。它还有助于识别标签的 GUID，你需要将标签应用于邮件项。确认标签的可用性后，将其 GUID 作为参数传递给 item.sensitivityLabel.setAsync，如以下示例所示。

// It's recommended to check the status of the catalog of sensitivity labels before
// calling other sensitivity label methods.
Office.context.sensitivityLabelsCatalog.getIsEnabledAsync((asyncResult) => {
    if (asyncResult.status === Office.AsyncResultStatus.Succeeded && asyncResult.value == true) {
        // Identify available sensitivity labels in the catalog.
        Office.context.sensitivityLabelsCatalog.getAsync((asyncResult) => {
            if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
                const catalog = asyncResult.value;
                if (catalog.length > 0) {
                    // Get the GUID of the sensitivity label.
                    var id = catalog[0].id;
                    // Set the mail item's sensitivity label using the label's GUID.
                    Office.context.mailbox.item.sensitivityLabel.setAsync(id, (asyncResult) => {
                        if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
                            console.log(asyncResult.status);
                        } else {
                            console.log("Action failed with error: " + asyncResult.error.message);
                        }
                    });
                } else {
                    console.log("Catalog list is empty");
                }
            } else {
                console.log("Action failed with error: " + asyncResult.error.message);
            }
        });
    } else {
        console.log("Action failed with error: " + asyncResult.error.message);
    }
});

可以传递从目录调用检索到的 SensitivityLabelDetails 对象，而不是使用 GUID 设置敏感度标签，如以下示例所示。

// It's recommended to check the status of the catalog of sensitivity labels before
// calling other sensitivity label methods.
Office.context.sensitivityLabelsCatalog.getIsEnabledAsync((asyncResult) => {
    if (asyncResult.status === Office.AsyncResultStatus.Succeeded && asyncResult.value == true) {
        // Identify available sensitivity labels in the catalog.
        Office.context.sensitivityLabelsCatalog.getAsync((asyncResult) => {
            if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
                const catalog = asyncResult.value;
                if (catalog.length > 0) {
                    // Set the mail item's sensitivity label using the SensitivityLabelDetails object.
                    Office.context.mailbox.item.sensitivityLabel.setAsync(catalog[0], (asyncResult) => {
                        if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
                            console.log(asyncResult.status);
                        } else {
                            console.log("Action failed with error: " + asyncResult.error.message);
                        }
                    });
                } else {
                    console.log("Catalog list is empty");
                }
            } else {
                console.log("Action failed with error: " + asyncResult.error.message);
            }
        });
    } else {
        console.log("Action failed with error: " + asyncResult.error.message);
    }
});

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

使用事件采取额外措施来保护数据 OnSensitivityLabelChanged 。此事件使外接程序能够完成任务，以响应邮件或约会上的敏感度标签更改。例如，如果邮件项包含某些附件，则可以阻止用户降级邮件项目的敏感度标签。

事件 OnSensitivityLabelChanged 通过基于事件的激活功能提供。若要了解如何配置、调试和部署使用此事件的基于事件的外接程序，请参阅为基于事件的激活配置 Outlook 外接程序。

通过