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

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

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

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

添加文件引擎

如配置文件和 引擎对象中介绍,引擎可以有两种状态 - LOADED 。 如果不是这两种状态之一,则不存在。 若要创建和加载状态,只需对 进行单个调用 FileProfile::LoadAsync 。 如果引擎已存在于缓存状态中,则它是 LOADED 。 如果不存在,它将为 和 CREATEDLOADEDCREATED 这意味着应用程序具有加载引擎所需的服务提供的所有信息。 LOADED 这意味着,利用引擎所需的所有数据结构已在内存中创建。

创建文件引擎设置

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

此处,我们使用 FileEngine::Settings 应用程序用户的标识 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 等对象 GUID 可确保 ID 是唯一的,并且可以从本地状态加载,而无需调用服务。

添加文件引擎

若要添加引擎,我们将返回到用于加载配置文件的 promise/future 模式。 不是为 创建 mip::FileProfile promise,而是使用 创建 mip::FileEngine

  //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>

在此处详细了解

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;
  }
}

返回 的 集合可用于显示可供用户使用的所有标签,然后在选中后使用 ID 将标签 mip::LabelGetSensitivityLabels() 应用到文件。

下一步

加载配置文件、添加引擎并创建标签后,我们可以添加一个处理程序,用于开始读取、写入或删除文件的标签。 请参阅 MIP SDK 中的文件处理程序