共用方式為

Microsoft 資訊保護 SDK - 設定檔和引擎物件概念

  • 發行項

設定檔

MipContext其中 是用來儲存 SDK 特定設定的類別，設定檔是 MIP SDK 中所有 MIP 標籤和保護特定作業的根類別。 使用三個 API 集合中的任何一個之前，用戶端應用程式必須建立設定檔。 未來的作業會由設定檔執行，或由新增 至設定檔的其他物件 執行。 建議每個進程只使用單一設定檔物件。 建立多個可能會導致非預期的行為。

MIP SDK 中有三種類型的設定檔：

取用應用程式中所使用的 API 會決定應該使用哪一個設定檔類別。

設定檔本身提供下列功能：

  • 定義狀態應該載入記憶體中或保存至磁片，如果保存至磁片，則為加密狀態。
  • mip::ConsentDelegate定義應該用於同意作業的 。
  • mip::FileProfile::Observer定義將用於設定檔作業之非同步回呼的實作。

設定檔設定

  • MipContextMipContext：初始化以儲存應用程式資訊、狀態路徑等的物件。
  • CacheStorageType：定義如何儲存狀態：在記憶體、磁片或磁片上，以及加密。
  • consentDelegate：類別 mip::ConsentDelegate 的共用指標。
  • observer：設定檔 Observer 實作的共用指標（在 PolicyProfile 、 ProtectionProfile 和 FileProfile 中）。
  • applicationInfomip::ApplicationInfo：物件。 取用 SDK 之應用程式的相關資訊，其符合您的 Microsoft Entra 應用程式註冊識別碼和名稱。

引擎

檔案、設定檔和保護 SDK 引擎提供特定身分識別所執行作業的介面。 每個登入應用程式的使用者或服務主體都會將一個引擎新增至 Profile 物件。 可以透過 mip::ProtectionSettings 和 檔案或保護處理常式執行委派作業。 如需詳細資訊，請參閱 FileHandler 概念 中的保護設定一節。

SDK 中有三個引擎類別，每個 API 各有一個。 下列清單顯示引擎類別和一些與每個函式相關聯的函式：

  • mip::ProtectionEngine
  • mip::PolicyEngine
    • ListSensitivityLabels()：取得已載入引擎的標籤清單。
    • GetSensitivityLabel()：從現有內容取得標籤。
    • ComputeActions()：提供標籤識別碼和選擇性中繼資料，會傳回特定專案應該發生的動作清單。
  • mip::FileEngine
    • ListSensitivityLabels()：取得已載入引擎的標籤清單。
    • CreateFileHandler()：為特定檔案或資料流程建立 mip::FileHandler 。

建立引擎需要傳入包含要建立之引擎類型的設定的特定引擎設定物件。 settings 物件可讓開發人員指定引擎識別碼、實作、 mip::AuthDelegate 地區設定和自訂設定的詳細資料，以及其他 API 特定詳細資料。

引擎狀態

引擎可能有兩種狀態之一：

  • CREATED：建立表示 SDK 在呼叫必要的後端服務之後，有足夠的本機狀態資訊。
  • LOADED：SDK 已建置必要的資料結構，讓引擎能夠運作。

必須同時建立和載入引擎，才能執行任何作業。 類別 Profile 會公開幾個引擎管理方法： AddEngineAsync 、 DeleteEngineAsync 和 UnloadEngineAsync 。

下表描述可能的引擎狀態，以及哪些方法可以變更該狀態：

引擎狀態 NONE CREATED 載入
NONE AddEngineAsync
CREATED DeleteEngineAsync AddEngineAsync
載入 DeleteEngineAsync UnloadEngineAsync

引擎識別碼

每個引擎都有用於所有引擎管理作業的唯一識別碼 id 。 如果應用程式未提供 ，則應用程式可以提供 id ，或 SDK 可以產生一個。 所有其他引擎屬性（例如，身分識別資訊中的電子郵件地址）都是 SDK 的不透明承載。 SDK 不會執行任何邏輯來保留任何其他屬性的唯一，或強制執行任何其他條件約束。

重要

**最佳做法是，使用使用者唯一的引擎識別碼，並在每次使用者與 SDK 執行作業時使用該識別碼。 若無法為使用者或服務提供現有的唯一 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 。

這個方法可讓應用程式藉由卸載不預期很快就會使用的引擎，來讓應用程式對記憶體使用量有條理。

後續步驟