通过

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。

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

引擎状态

引擎可能有以下两种状态：

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

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

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

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

引擎 ID

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

重要

**最佳做法是，使用用户独有的引擎 ID，并在每次用户使用 SDK 执行操作时使用该 ID。 未能为用户或服务提供现有、唯一的 engineId 将导致额外的服务往返。 这些服务往返可能导致性能降低和限制。 **

// 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、DeleteEngineAsync 和 UnloadEngineAsync。

AddEngineAsync

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

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

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

DeleteEngineAsync

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

UnloadEngineAsync

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

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

后续步骤