共用方式為

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。

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

後續步驟