пакет SDK Microsoft Information Protection — основные понятия обработчика файлов

В SDK MIP File mip::FileHandler предоставляет операции для чтения и записи меток и параметров защиты для различных типов файлов, для которых предусмотрена встроенная поддержка.

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

  • Форматы файлов Office на основе OPC (Office 2010 и более поздних версий)
  • Устаревшие форматы файлов Office (Office 2007)
  • PDF
  • Поддержка универсального PFILE
  • Файлы, поддерживающие Adobe XMP

Функции обработчика файлов

mip::FileHandler предоставляет методы чтения, записи и удаления меток и сведений о защите. Полный список см. в справочнике по API.

В этой статье рассматриваются следующие методы:

  • GetLabelAsync()
  • SetLabel()
  • DeleteLabel()
  • RemoveProtection()
  • CommitAsync()

Требования

Чтобы создать FileHandler для работы с определённым файлом, укажите:

  • FileProfile
  • FileEngine добавлен в FileProfile
  • Класс, наследующий mip::FileHandler::Observer

Создание обработчика файла

Первым шагом в управлении файлами в пакете SDK для файлов является создание FileHandler объекта. Этот класс включает функции, необходимые для получения, установки, обновления, удаления и фиксации изменений меток в файлах.

Создайте FileHandler, вызвав функцию CreateFileHandlerAsync объекта FileEngine с помощью шаблона promise/future.

CreateFileHandlerAsync принимает три параметра: путь к файлу для чтения или изменения, параметр mip::FileHandler::Observer для асинхронных уведомлений о событиях и обещание для FileHandler.

Note

Реализуйте класс mip::FileHandler::Observer в производном классе, так как для CreateFileHandler требуется объект Observer.

auto createFileHandlerPromise = std::make_shared<std::promise<std::shared_ptr<mip::FileHandler>>>();
auto createFileHandlerFuture = createFileHandlerPromise->get_future();
fileEngine->CreateFileHandlerAsync(filePath, std::make_shared<FileHandlerObserver>(), createFileHandlerPromise);
auto fileHandler = createFileHandlerFuture.get();

После создания FileHandler объекта можно выполнять операции с файлами (get/set/delete/commit).

Чтение метки

Требования к метаданным

Для успешного считывания метаданных из файла и преобразования их в форму, пригодную для использования приложениями, необходимо выполнить несколько условий.

  • Метка, считываемая, по-прежнему должна существовать в службе Microsoft 365. Если кто-то удалил метку, пакет SDK не получает сведения об этой метки и возвращает ошибку.
  • Метаданные файла должны быть нетронутыми. Эти метаданные включают:
    • Атрибут1
    • Атрибут2

GetLabelAsync()

После создания обработчика, указывающего на определенный файл, вернитесь к шаблону Promise/Future, чтобы асинхронно прочитать метку. Обещание предназначено для mip::ContentLabel объекта, содержащего всю информацию о примененной метки.

После создания экземпляра promise и future объектов считывайте метку путем вызова fileHandler->GetLabelAsync() и предоставления promise в качестве параметра lone. Наконец, сохраните метку в объекте mip::ContentLabel, который вы получаете из future.

auto loadPromise = std::make_shared<std::promise<std::shared_ptr<mip::ContentLabel>>>();
auto loadFuture = loadPromise->get_future();
fileHandler->GetLabelAsync(loadPromise);
auto label = loadFuture.get();

Данные метки из label объекта можно считывать и передавать в любой другой компонент или функциональные возможности приложения.

Установка метки

Установка метки — это двухкомпонентный процесс. После того как вы создадите обработчик, который указывает на соответствующий файл, задайте метку, вызвав FileHandler->SetLabel() с некоторыми параметрами: mip::Label, mip::LabelingOptions и mip::ProtectionOptions. Сначала преобразуйте идентификатор метки в саму метку, а затем определите параметры разметки.

Преобразовать идентификатор метки в тип mip::Label

Первый параметр функции SetLabel — это mip::Label. Часто приложение работает с идентификаторами меток, а не с метками. Разрешение идентификатора mip::Label метки путем вызова GetLabelById в обработчике файлов или политик:

mip::Label label = mEngine->GetLabelById(labelId);

Параметры маркировки

Второй параметр, необходимый для задания метки mip::LabelingOptions.

LabelingOptions указывает дополнительные сведения о метках, таких как AssignmentMethod и обоснование действия.

  • mip::AssignmentMethod — перечислитель, имеющий три значения: STANDARD, PRIVILEGEDили AUTO. Дополнительные сведения см. в справочнике mip::AssignmentMethod .
  • Укажите обоснование, только если политика службы требует ее и при снижении существующей конфиденциальности файла.

В этом фрагменте показано, как создать объект mip::LabelingOptions и задать обоснование понижения версии и сообщение.

auto labelingOptions = mip::LabelingOptions(mip::AssignmentMethod::STANDARD);
labelingOptions.SetDowngradeJustification(true, "Because I made an educated decision based upon the contents of this file.");

Параметры защиты

Некоторым приложениям может потребоваться выполнять операции от имени делегированных учетных данных пользователя. Класс mip::ProtectionSettings позволяет приложению определять делегированное удостоверение для каждого обработчика. Ранее классы движка осуществляли делегирование. Эта конструкция имеет значительные недостатки в затратах на приложениях и круговых поездках службы. Перенос делегированных пользовательских параметров в mip::ProtectionSettings и включение их в класс обработчика устраняют эти издержки, что повышает производительность приложений, выполняющих множество операций от имени различных пользовательских удостоверений.

Если делегирование не требуется, передайте mip::ProtectionSettings() в функцию SetLabel. Если требуется делегирование, создайте объект и задайте делегированный почтовый mip::ProtectionSettings адрес:

mip::ProtectionSettings protectionSettings;
protectionSettings.SetDelegatedUserEmail("alice@contoso.com");

Установка метки

После того как вы получите mip::Label с помощью идентификатора, задайте параметры маркировки и, при необходимости, параметры защиты, а затем установите метку для обработчика.

Если вы не настроили параметры защиты, задайте метку, вызвав SetLabel для обработчика:

fileHandler->SetLabel(label, labelingOptions, mip::ProtectionSettings());

Если вам нужны параметры защиты для выполнения делегированной операции, используйте следующее:

fileHandler->SetLabel(label, labelingOptions, protectionSettings);

После установки метки в файле, на который ссылается обработчик, зафиксируйте изменение и напишите файл на диск или создайте выходной поток.

Зафиксируйте изменения

Последним шагом в фиксации любых изменений в файле в пакете SDK MIP является фиксация изменения. Используйте функцию FileHandler->CommitAsync() .

Чтобы реализовать функцию обязательств, вернитесь к обещанию или будущему, создайте обещание для bool. Функция CommitAsync() возвращает значение true, если операция завершилась успешно или false, если она завершилась ошибкой по какой-либо причине.

После создания future и promise вызовите CommitAsync() и передайте два параметра: путь к выходному файлу (std::string) и promise. Наконец, получите результат, получив значение future объекта.

auto commitPromise = std::make_shared<std::promise<bool>>();
auto commitFuture = commitPromise->get_future();
fileHandler->CommitAsync(outputFile, commitPromise);
auto wasCommitted = commitFuture.get();

Внимание

FileHandler не будет обновлять или перезаписывать существующие файлы. Необходимо реализовать замену для файла, который вы помечаете.

Если применить метку к FileA.docx, CommitAsync() создается копия файла FileB.docx с примененной меткой. Напишите код для удаления или переименования FileA.docx и переименования FileB.docx.

Удаление метки

auto fileHandler = mEngine->CreateFileHandler(filePath, std::make_shared<FileHandlerObserverImpl>());
fileHandler->DeleteLabel(mip::AssignmentMethod::PRIVILEGED, "Label unnecessary.");
auto commitPromise = std::make_shared<std::promise<bool>>();
auto commitFuture = commitPromise->get_future();
fileHandler->CommitAsync(outputFile, commitPromise);

Снятие защиты

Убедитесь, что у пользователя есть права на удаление защиты от доступа к файлу. Перед удалением защиты выполните проверку доступа .

Функция RemoveProtection() ведет себя аналогично SetLabel() или DeleteLabel(). Вызовите метод для существующего FileHandler объекта, а затем зафиксируйте изменение.

Внимание

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

Пример C++ :

// Validate that the file referred to by the FileHandler is protected.
if (fileHandler->GetProtection() != nullptr)
{
    // Validate that user is allowed to remove protection.
    if (fileHandler->GetProtection()->AccessCheck(mip::rights::Export()) || fileHandler->GetProtection()->AccessCheck(mip::rights::Owner()))
    {
        auto commitPromise = std::make_shared<std::promise<bool>>();
        auto commitFuture = commitPromise->get_future();
        // Remove protection and commit changes to file.
        fileHandler->RemoveProtection();
        fileHandler->CommitAsync(outputFile, commitPromise);
        result = commitFuture.get();
    }
    else
    {
        // Throw an exception if the user doesn't have rights to remove protection.
        throw std::runtime_error("User doesn't have EXPORT or OWNER right.");
    }
}

Пример .NET:

if(handler.Protection != null)
{
    // Validate that user has rights to remove protection from the file.
    if(handler.Protection.AccessCheck(Rights.Export) || handler.Protection.AccessCheck(Rights.Owner))
    {
        // If user has Extract right, remove protection and commit the change. Otherwise, throw exception.
        handler.RemoveProtection();
        bool result = handler.CommitAsync(outputPath).GetAwaiter().GetResult();
        return result;
    }
    else
    {
        throw new Microsoft.InformationProtection.Exceptions.AccessDeniedException("User lacks EXPORT right.");
    }
}

Дальнейшие действия

  • Last updated on