共用方式為

Microsoft 資訊保護 SDK - 檔案 SDK 引擎概念

  • 發行項

mip::FileEngine MIP 檔案 SDK 中的 提供介面給代表指定身分識別執行的所有作業。 系統會為每個登入應用程式的使用者新增一個引擎，而引擎執行的所有作業都會在該身分識別的內容中執行。

FileEngine有兩個主要責任：列出已驗證使用者的標籤，並建立檔案處理程式來代表使用者執行檔案作業。

  • mip::FileEngine
  • ListSensitivityLabels()：取得已載入引擎的標籤清單。
  • CreateFileHandler()：為特定檔案或數據流建立 mip::FileHandler 。

新增檔案引擎

如設定檔案與引擎物件中所述，引擎可以有兩種狀態 - CREATED 或 LOADED。 如果不是這兩個狀態之一，則不存在。 若要建立和載入狀態，只需要對 進行單一呼叫 FileProfile::LoadAsync。 如果引擎已處於快取狀態，則會是 LOADED。 如果不存在，則會是 CREATED 和 LOADED。 CREATED 表示應用程式具有載入引擎所需的服務的所有資訊。 LOADED 表示利用引擎所需的所有數據結構都已在記憶體中建立。

建立檔案引擎 設定

與設定檔類似，引擎也需要設定物件 mip::FileEngine::Settings 此物件會儲存唯一的引擎標識碼、 mip::AuthDelegate 實作、可用於偵錯或遙測的可自定義客戶端數據，以及選擇性地儲存地區設定。

在這裡，我們會使用應用程式使用者的身分識別來建立FileEngine::Settings稱為 engine 的物件 設定。

FileEngine::Settings engineSettings(
  mip::Identity(mUsername), // mip::Identity.
  authDelegateImpl,         // auth delegate object
  "",                       // Client data. Customizable by developer, stored with engine.
  "en-US",                  // Locale.
  false);                   // Load sensitive information types for driving classification.

以這種方式建立引擎 設定 請務必透過下列方式明確設定唯一的 engineId：

engineSettings.SetEngineId(engineId);

使用使用者名稱或電子郵件有助於確保每次使用者使用服務或應用程式時，都會載入相同的引擎。

此外，也提供自定義引擎識別碼：

FileEngine::Settings engineSettings(
  "myEngineId",     // string
  authDelegateImpl, // auth delegate object
  "",               // Client data in string format. Customizable by developer, stored with engine.
  "en-US",          // Locale. Default is en-US
  false);           // Load sensitive information types for driving classification. Default is false.

最佳做法是，第一個參數 id應該是一些可讓引擎輕鬆連線至相關聯用戶的專案。 類似電子郵件位址、UPN 或 AAD 物件 GUID 之類的專案可確保識別碼是唯一的，而且可以從本機狀態載入，而不需要呼叫服務。

新增檔案引擎

若要新增引擎，我們將回到用來載入配置檔的承諾/未來模式。 它不是建立的承諾 mip::FileProfile，而是使用 mip::FileEngine來建立。

  //auto profile will be std::shared_ptr<mip::FileProfile>
  auto profile = profileFuture.get();

  // Instantiate the AuthDelegate implementation.
  auto authDelegateImpl = std::make_shared<sample::auth::AuthDelegateImpl>(appInfo, userName, password);

  //Create the FileEngine::Settings object
  FileEngine::Settings engineSettings("UniqueID", authDelegateImpl, "");

  //Create a promise for std::shared_ptr<mip::FileEngine>
  auto enginePromise = std::make_shared<std::promise<std::shared_ptr<mip::FileEngine>>>();

  //Instantiate the future from the promise
  auto engineFuture = enginePromise->get_future();

  //Add the engine using AddEngineAsync, passing in the engine settings and the promise
  profile->AddEngineAsync(engineSettings, enginePromise);

  //get the future value and store in std::shared_ptr<mip::FileEngine>
  auto engine = engineFuture.get();

上述程式代碼的最終結果是，已驗證用戶的引擎將會新增至配置檔。

列出敏感度標籤

使用新增的引擎，現在可以藉由呼叫 engine->ListSensitivityLabels()來列出已驗證使用者可用的所有敏感度標籤。

ListSensitivityLabels() 會從服務擷取特定使用者的標籤和屬性清單。 結果會儲存在的 std::shared_ptr<mip::Label>向量中。

如需詳細資訊，請參閱 mip::Label。

ListSensitivityLabels（）

std::vector<shared_ptr<mip::Label>> labels = engine->ListSensitivityLabels();

或者，簡化：

auto labels = engine->ListSensitivityLabels();

列印名稱是顯示我們已成功從服務提取原則並能夠取得標籤的簡單方式。 若要套用標籤，則需要標籤標識碼。 下列程式代碼會逐一查看所有標籤，並顯示 name 每個父卷標和子捲標的 和 id 。

//Iterate through all labels in the vector
for (const auto& label : labels) {
  //Print label name and GUID
  cout << label->GetName() << " : " << label->GetId() << endl;

  //Print child label name and GUID
  for (const auto& child : label->GetChildren()) {
    cout << "->  " << child->GetName() <<  " : " << child->GetId() << endl;
  }
}

傳GetSensitivityLabels()回的 mip::Label 集合可用來顯示使用者可用的所有標籤，然後在選取時，使用標識符將標籤套用至檔案。

後續步驟

現在已載入配置檔，引擎已新增，而且我們有標籤，我們可以新增處理程式，開始讀取、寫入或移除檔案中的標籤。 請參閱 MIP SDK 中的檔案處理程式。