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

配置文件

其中 是存储特定于 SDK 的设置的类,配置文件是 MIP SDK 中所有 MIP 标签和保护 MipContext 特定操作的根类。 在使用这三个 API 集之一之前,客户端应用程序必须创建配置文件。 将来的操作由配置文件执行,或者由添加到 配置文件的其他 对象执行。 建议每个进程只有一个配置文件对象。 创建多个可能导致意外行为。

MIP SDK 中有三种类型的配置文件:

使用应用程序中使用的 API 确定应该使用哪个配置文件类。

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

  • 定义状态是应加载到内存中还是持久化到磁盘,如果保留到磁盘,则应该加密。
  • 定义 mip::ConsentDelegate 应用于许可操作。
  • 定义 mip::FileProfile::Observer 将用于配置文件操作异步回调的实现。

配置文件设置

  • MipContextMipContext 已初始化以存储应用程序信息、状态路径等的对象。
  • CacheStorageType:定义如何存储状态:在内存中、磁盘上或磁盘上并加密。
  • consentDelegate:类的共享指针 mip::ConsentDelegate
  • observer:指向 、 和 (ObserverPolicyProfileProtectionProfile 中的配置文件实现 FileProfile) 。
  • applicationInfomip::ApplicationInfo 对象。 有关使用 SDK 的应用程序的信息,与Azure Active Directory ID 和名称匹配。

引擎

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

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

  • mip::ProtectionEngine
  • mip::PolicyEngine
    • ListSensitivityLabels():获取加载的引擎的标签列表。
    • GetSensitivityLabel():从现有内容获取标签。
    • ComputeActions():提供标签 ID 和可选元数据,返回特定项应发生的操作列表。
  • mip::FileEngine
    • ListSensitivityLabels():获取加载的引擎的标签列表。
    • CreateFileHandler():为 mip::FileHandler 特定文件或流创建 。

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

引擎状态

引擎可能具有两种状态之一:

  • CREATED:Created 表示 SDK 在调用所需的后端服务后有足够的本地状态信息。
  • LOADED:SDK 已生成使引擎正常运行所需的数据结构。

必须同时创建和加载引擎才能执行任何操作。 类 Profile 公开一些引擎管理方法 AddEngineAsyncDeleteEngineAsync :、 和 UnloadEngineAsync

下表描述了可能的引擎状态,以及哪些方法可以更改该状态:

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

引擎 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 中具有三种引擎管理方法 AddEngineAsyncDeleteEngineAsync :、 和 UnloadEngineAsync

AddEngineAsync

此方法加载现有引擎,或者创建一个(如果本地状态中不存在)。

如果应用程序未在 id 中提供 FileEngineSettingsAddEngineAsync 则生成新的 id 。 然后,它会检查本地存储缓存中是否存在 id 具有 该引擎的引擎。 如果已加载,则加载该引擎。 如果本地 缓存中 不存在该引擎,则通过调用必要的 API 和后端服务来创建一个新引擎。

在这两种情况下,如果方法成功,则加载引擎并准备好使用。

DeleteEngineAsync

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

UnloadEngineAsync

使用给定的 卸载引擎的内存中数据结构 id 。 此引擎的本地状态仍保持不变,可以使用 重新加载 AddEngineAsync

此方法允许应用程序通过卸载预期不会很快使用的引擎,对内存使用情况进行明智选择。

下一步