Microsoft 信息保护 SDK - 配置文件和引擎对象概念

配置文件

该 MipContext 类存储特定于 SDK 的设置。 此配置文件是 MIP SDK 中所有 MIP 标记和保护特定操作的根类。 在使用三个 API 集中的任何一个之前，客户端应用程序必须创建配置文件。 配置文件或添加到配置文件中的其他对象会执行后续操作。 每个进程只使用一个配置文件对象。 创建一个以上可能会导致不可预期的行为。

MIP SDK 有三种配置文件类型：

调用应用程序所使用的 API 决定了应使用哪个配置文件类。

配置文件本身提供了以下功能：

  • 状态存储：定义是加载内存中的状态还是将其保存到磁盘，以及是否在保存到磁盘时加密状态。
  • 同意委托对象：定义用于同意操作的 mip::ConsentDelegate。
  • 文件配置文件观察器：定义用于配置文件操作异步回调的 mip::FileProfile::Observer 实现。

个人资料设置

  • MipContext：已初始化为存储应用程序信息、状态路径等的 MipContext 对象。
  • CacheStorageType：定义如何存储状态：在内存中、在磁盘上或在磁盘上并加密。
  • consentDelegate：mip::ConsentDelegate 类的共享指针。
  • observer：指向配置文件 Observer 实现的共享指针（在 PolicyProfile、ProtectionProfile 和 FileProfile 中）。
  • applicationInfo：一种 mip::ApplicationInfo 对象。 有关使用该 SDK 且其 Microsoft Entra 应用程序注册 ID 和名称与之匹配的应用程序的信息。

引擎

文件、策略和保护 SDK 引擎为特定标识执行的操作提供接口。 将一个引擎添加到登录到应用程序的每个用户或服务主体的配置文件对象。 您可以使用 mip::ProtectionSettings 以及文件或保护处理程序来执行委派操作。 有关详细信息，请参阅 FileHandler 概念中的保护设置部分。

SDK 有三个引擎类，每个 API 各有一个引擎类。 以下列表显示了这些引擎类以及与每个引擎类关联的一些函数：

  • mip::ProtectionEngine
  • mip::PolicyEngine
    • ListSensitivityLabels()：获取已加载引擎的标签列表。
    • GetSensitivityLabel()：获取现有内容中的标签。
    • ComputeActions()：在提供标签 ID 和可选的元数据后，将返回对于特定项应执行的操作列表。
  • mip::FileEngine
    • ListSensitivityLabels()：获取已加载引擎的标签列表。
    • CreateFileHandler()：为特定文件或流创建一个 mip::FileHandler。

若要创建引擎，请传入包含要创建的引擎类型的设置的特定引擎设置对象。 设置对象允许开发人员指定有关引擎标识符、mip::AuthDelegate 实现、区域设置、自定义设置以及其他特定于 API 的详细信息。

引擎状态

引擎可以有两种状态之一：

  • CREATED：“已创建”指示 SDK 在调用所需的后端服务后具有充分的本地状态信息。
  • LOADED：SDK 已生成引擎正常运行所需的数据结构。

必须完成引擎的创建并加载后才能执行任何操作。 Profile 类会公开一些引擎管理方法：AddEngineAsync、DeleteEngineAsync 和 UnloadEngineAsync。

下表介绍可能的引擎状态，以及哪些方法可以更改该状态：

引擎状态 无 CREATED 已加载
无 AddEngineAsync
CREATED DeleteEngineAsync AddEngineAsync
已加载 DeleteEngineAsync UnloadEngineAsync

引擎 ID

每个引擎都有一个唯一标识符， id用于所有引擎管理操作。 应用程序可以提供 id。 如果应用程序不提供一个，SDK 可以生成它。 所有其他引擎属性（如标识信息中的电子邮件地址）都是 SDK 的不透明有效负载。 SDK 不执行逻辑来保留任何其他属性的唯一性或强制实施其他约束。

重要

使用用户唯一的引擎 ID，并在用户每次使用 SDK 执行操作时使用该引擎 ID。 如果未为用户或服务提供现有的唯一引擎 ID，则 SDK 会进行额外的服务往返。 这些服务往返调用可能会导致性能下降和限流。

// Create the FileEngineSettings object
FileEngine::Settings engineSettings(mip::Identity(mUsername), // This will be the engine ID. UPN, email address, or other unique user identifiers are recommended. 
													          mAuthDelegate,            // authDelegate implementation 
													          "",                       // ClientData
													          "en-US",                  // Client Locale
                                    false);                   // Load Sensitive Information Types

引擎管理方法

SDK 有三种引擎管理方法：AddEngineAsync和DeleteEngineAsyncUnloadEngineAsync。

AddEngineAsync

此方法加载现有引擎或创建一个（如果在本地状态下尚不存在）。

如果应用程序不提供 id 中的 FileEngineSettings，则 AddEngineAsync 会生成新的 id。 然后检查带有 id 的引擎是否已存在于本地存储缓存中。 如果提供了此信息，则将加载该引擎。 如果引擎不存在于本地缓存中，则会通过调用必要的 API 和后端服务来创建新引擎。

对于这两种情况，如果方法成功，则将加载引擎并使其可供使用。

DeleteEngineAsync

删除具有给定 id 的引擎。 所有引擎的痕迹已从本地缓存中删除。

UnloadEngineAsync

卸载具有给定 id 的引擎的内存中数据结构。 此引擎的本地状态仍然完好无损，你可以使用 AddEngineAsync 重新加载该引擎。

借助此方法，应用程序可以通过卸载预计不会即将使用的引擎来审慎地使用内存。

后续步骤

  • 上次更新时间为