通过

Microsoft 信息保护 SDK - 文件 SDK 引擎概念

  • 项目

MIP 文件 SDK 中的 mip::FileEngine 为代表指定标识执行的所有操作提供接口。 将为登录到应用程序的每个用户添加一个引擎，并且该引擎执行的所有操作都将在该标识的上下文中执行。

FileEngine 主要有两个职责：列出已通过身份验证的用户的标签，以及创建文件处理程序来代表用户执行文件操作。

  • mip::FileEngine
  • ListSensitivityLabels()：获取已加载引擎的标签列表。
  • CreateFileHandler()：为特定文件或流创建一个 mip::FileHandler。

添加文件引擎

如配置文件和引擎对象中所述，引擎可以有两种状态：CREATED 或 LOADED。 如果这两种状态都不存在，则该引擎不存在。 要创建和加载状态，只需调用一次 FileProfile::LoadAsync 即可。 如果该引擎已处于缓存状态，则将为 LOADED。 如果该引擎不存在，则将为 CREATED 和 LOADED。 CREATED 表示应用程序包含加载该引擎所需服务的所有信息。 LOADED 表示利用该引擎所需的所有数据结构都已在内存中创建。

创建文件引擎设置

与配置文件类似，引擎也需要设置对象 mip::FileEngine::Settings。 此对象用于存储唯一的引擎标识符、mip::AuthDelegate 实现、可用于调试或遥测的可自定义客户端数据，以及可选的区域设置。

在这里，我们使用应用程序用户的标识创建一个名为 engineSettings 的 FileEngine::Settings 对象。

FileEngine::Settings engineSettings(
  mip::Identity(mUsername), // mip::Identity.
  authDelegateImpl,         // auth delegate object
  "",                       // Client data. Customizable by developer, stored with engine.
  "en-US",                  // Locale.
  false);                   // Load sensitive information types for driving classification.

以这种方式创建 engineSettings 时，通过以下方式显式设置唯一的 engineId 也很重要：

engineSettings.SetEngineId(engineId);

使用用户名或电子邮件有助于确保每次用户使用服务或应用程序时加载相同的引擎。

提供自定义引擎 ID 也是有效的：

FileEngine::Settings engineSettings(
  "myEngineId",     // string
  authDelegateImpl, // auth delegate object
  "",               // Client data in string format. Customizable by developer, stored with engine.
  "en-US",          // Locale. Default is en-US
  false);           // Load sensitive information types for driving classification. Default is false.

最佳做法是，第一个参数 id 应能让引擎轻松连接到关联的用户。 电子邮件地址、UPN 或 AAD 对象 GUID 等均可确保 ID 的唯一性，并且可以从本地状态加载，而无需调用服务。

添加文件引擎

为了添加引擎，我们将返回用于加载配置文件的承诺/未来模式。 它是使用 mip::FileEngine 创建的，而不是通过创建 mip::FileProfile 的承诺。

  //auto profile will be std::shared_ptr<mip::FileProfile>
  auto profile = profileFuture.get();

  // Instantiate the AuthDelegate implementation.
  auto authDelegateImpl = std::make_shared<sample::auth::AuthDelegateImpl>(appInfo, userName, password);

  //Create the FileEngine::Settings object
  FileEngine::Settings engineSettings("UniqueID", authDelegateImpl, "");

  //Create a promise for std::shared_ptr<mip::FileEngine>
  auto enginePromise = std::make_shared<std::promise<std::shared_ptr<mip::FileEngine>>>();

  //Instantiate the future from the promise
  auto engineFuture = enginePromise->get_future();

  //Add the engine using AddEngineAsync, passing in the engine settings and the promise
  profile->AddEngineAsync(engineSettings, enginePromise);

  //get the future value and store in std::shared_ptr<mip::FileEngine>
  auto engine = engineFuture.get();

上述代码的最终结果是，已通过身份验证的用户的引擎将会添加到该配置文件。

列出敏感度标签

使用添加的引擎，现在可以通过调用 engine->ListSensitivityLabels() 来列出可供已通过身份验证的用户使用的所有敏感度标签。

ListSensitivityLabels() 将从服务中为特定用户提取标签列表和这些标签的属性。 结果将存储在 std::shared_ptr<mip::Label> 的矢量中。

单机此处阅读有关 mip::Label 的更多信息。

ListSensitivityLabels()

std::vector<shared_ptr<mip::Label>> labels = engine->ListSensitivityLabels();

或者简化为：

auto labels = engine->ListSensitivityLabels();

打印名称是显示我们已成功从服务中拉取策略并且能够获取标签的简单方法。 要应用标签，则需要标签的标识符。 下面的代码会循环访问所有标签，并显示每个父标签和子标签的 name 和 id。

//Iterate through all labels in the vector
for (const auto& label : labels) {
  //Print label name and GUID
  cout << label->GetName() << " : " << label->GetId() << endl;

  //Print child label name and GUID
  for (const auto& child : label->GetChildren()) {
    cout << "->  " << child->GetName() <<  " : " << child->GetId() << endl;
  }
}

GetSensitivityLabels() 返回的 mip::Label 集合可用于显示可供用户使用的所有标签，然后时使用 ID（如果选中）将标签应用于文件。

后续步骤

加载配置文件、添加引擎并且拥有标签后，我们可以添加处理程序来开始读取、写入或移除文件中的标签。 请参阅 MIP SDK 中的文件处理程序。