Управление метками конфиденциальности в надстройках Office

Совместная работа на рабочем месте часто выходит за рамки организации и распространяется на внешних партнеров. Для обмена информацией за пределами сети организации требуются меры по предотвращению потери данных и применению политик соответствия. Защита информации Microsoft Purview предоставляет решения для классификации и защиты конфиденциальной информации. Метки конфиденциальности применяют эту защиту к данным в Excel, Outlook, PowerPoint и Word.

Используйте API JavaScript Office для реализации решений по меткам конфиденциальности в проектах надстроек Office и поддерживайте следующие сценарии.

  • Применяйте метки конфиденциальности к документам, сообщениям или встречам в соответствии с бизнес-политиками и юридическими политиками.
  • Ограничьте дополнительные действия, если применяется определенная метка конфиденциальности, например запрет пользователям добавлять внешних получателей в сообщение.
  • Классифицируйте данные на основе метки конфиденциальности для поддержки аудита и отчетности.

Примечание.

В Excel, PowerPoint и Word API меток конфиденциальности доступны в предварительной версии. В Outlook поддержка функции меток конфиденциальности была введена в наборе требований 1.13. Сведения о поддержке клиентов см. в разделе Поддерживаемые клиенты и платформы.

Предварительные условия

Для использования функции меток конфиденциальности требуется подписка на Microsoft 365 E5. Проверьте, соответствуете ли вы требованиям для подписки разработчиков Microsoft 365 E5 в программе для разработчиков Microsoft 365 в разделе часто задаваемых вопросов о программе. В противном случае начните использовать бесплатную пробную версию на 1 месяц или приобретите план Microsoft 365.

Поддерживаемые клиенты и платформы

Поддержка API меток конфиденциальности зависит от приложения и платформы Office. Для поддержки Outlook требуется Exchange Online. В следующей таблице перечислены поддерживаемые сочетания.

Приложение Web Windows Mac
Excel Предварительная версия Предварительная версия Предварительная версия
Outlook Поддерживается Поддерживается
(новая и классическая (версия 2304 (сборка 16327.20248) или более поздняя))		 Поддерживается
(Версия 16.77 (23081600) или более поздняя)
PowerPoint Предварительная версия Предварительная версия Предварительная версия
Word Предварительная версия Предварительная версия Предварительная версия

Настройка поддержки меток конфиденциальности

Примечание.

Предварительные версии API могут быть изменены и не предназначены для использования в рабочей среде. Рекомендуется использовать их только в тестовой среде и среде разработки. Не используйте предварительные API в рабочей среде или в критически важных для бизнеса документах.

Чтобы использовать API предварительной версии:

API меток конфиденциальности Excel, PowerPoint и Word используют схожий шаблон программирования. В каждом узле контекст запроса предоставляет доступ к каталогу меток конфиденциальности, а объект-файл для хоста предоставляет методы для получения или обновления своей метки.

В следующей таблице перечислены члены API, используемые для доступа к каталогу меток конфиденциальности и меткам, применяемым к файлам в каждом хост-приложении Office.

Приложение Каталог меток конфиденциальности Метка конфиденциальности на файле
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, PowerPoint, Word) каталог меток конфиденциальности.

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,PowerPoint, Word) каталог.

Метод возвращает коллекцию, элементы и свойства которой недоступны, пока вы явно не загрузите их и не вызовете context.sync(). Инструкции см. в статье Загрузка из коллекции. Свойства загрузки items и метки, необходимые надстройке. Доступные свойства отличаются в зависимости от узла. Полный список см. в статьях SensitivityLabelDetails (Excel, PowerPoint, Word).

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, PowerPoint, Word) объект метки конфиденциальности файла.

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, PowerPoint, Word) и выберите включенную метку или вложенную метку из возвращенной коллекции. Метод tryToUpdate() (Excel, PowerPoint, Word) требует идентификатор выбранной метки в качестве параметра. Вызов getLabels() сначала позволяет получить этот обязательный идентификатор и убедиться, что метка доступна текущему пользователю. Проверьте возвращаемое SensitivityLabelUpdateResult значение (Excel, PowerPoint, Word), чтобы определить, прошло ли обновление успешно.

Примечание.

Родительскую метку с вложенными подписями нельзя применять напрямую. Вместо этого выберите одну из включенных дочерних меток.

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 события используется активация на основе событий. Руководство по настройке, отладке и развертыванию см. в статье "Активация надстроек с помощью событий".

См. также

  • Last updated on