快速入門:設定並取得敏感度標籤 (C++)

本快速入門說明如何使用更多 MIP 檔案 SDK。 使用您在上一個快速入門中列出的其中一個敏感度標籤,您可以使用檔案處理常式來設定/取得檔案上的標籤。 File handler 類別會針對支援的檔案類型,公開設定/取得標籤或保護的各種作業。

必要條件

如果您尚未完成,請務必先完成下列必要條件,再繼續進行:

實作觀察者類別來監視 File 處理常式物件

類似于您在應用程式初始化快速入門中實作的觀察者(針對檔案設定檔和引擎),現在您會為 File 處理常式物件實作觀察者類別。

藉由擴充 SDK 的 類別,為檔案處理常式觀察者建立基本實作 mip::FileHandler::Observer 。 觀察者會具現化及稍後使用,以監視檔案處理常式作業。

  1. 開啟您在先前的<快速入門:列出敏感度標籤(C++)》一文中處理過的 Visual Studio 解決方案。

  2. 將新類別新增至您的專案,這會為您產生標頭/.h 和 implementation/.cpp 檔案:

    • 方案總管 中,再次以滑鼠右鍵按一下專案節點,選取 [新增 ],然後選取 [ 類別 ]。
    • 在 [ 新增類別 ] 對話方塊中:
      • 在 [ 類別名稱] 欄位中,輸入 「filehandler_observer」。 請注意, 根據您輸入的名稱,會自動填入 .h 檔案 .cpp 檔案 欄位。
      • 完成後,按一下 [ 確定] 按鈕。
  3. 產生 類別的 .h 和 .cpp 檔案之後,這兩個檔案都會在 [編輯器群組] 索引標籤中開啟。 現在更新每個檔案以實作新的觀察者類別:

    • 選取/刪除產生的 filehandler_observer 類別,以更新 「filehandler_observer.h」。 請勿 移除上一個步驟所產生的預處理器指示詞(#pragma、#include)。 然後在任何現有的預處理器指示詞之後,將下列來源複製/貼到檔案中:

      #include <memory>
      #include "mip/file/file_engine.h"
      #include "mip/file/file_handler.h"
      
      class FileHandlerObserver final : public mip::FileHandler::Observer {
      public:
         FileHandlerObserver() { }
         // Observer implementation
         void OnCreateFileHandlerSuccess(const std::shared_ptr<mip::FileHandler>& fileHandler, const std::shared_ptr<void>& context) override;
         void OnCreateFileHandlerFailure(const std::exception_ptr& error, const std::shared_ptr<void>& context) override;
         void OnCommitSuccess(bool committed, const std::shared_ptr<void>& context) override;
         void OnCommitFailure(const std::exception_ptr& error, const std::shared_ptr<void>& context) override;		
      };
      
    • 選取/刪除產生的 filehandler_observer 類別實作,以更新 「filehandler_observer.cpp」。 請勿 移除上一個步驟所產生的預處理器指示詞(#pragma、#include)。 然後在任何現有的預處理器指示詞之後,將下列來源複製/貼到檔案中:

      void FileHandlerObserver::OnCreateFileHandlerSuccess(const std::shared_ptr<mip::FileHandler>& fileHandler, const std::shared_ptr<void>& context) {
         auto promise = std::static_pointer_cast<std::promise<std::shared_ptr<mip::FileHandler>>>(context);
         promise->set_value(fileHandler);
      }
      
      void FileHandlerObserver::OnCreateFileHandlerFailure(const std::exception_ptr & error, const std::shared_ptr<void>& context) {
         auto promise = std::static_pointer_cast<std::promise<std::shared_ptr<mip::FileHandler>>>(context);
         promise->set_exception(error);
      }
      
      void FileHandlerObserver::OnCommitSuccess(bool committed, const std::shared_ptr<void>& context) {
         auto promise = std::static_pointer_cast<std::promise<bool>>(context);
         promise->set_value(committed);
      }
      
      void FileHandlerObserver::OnCommitFailure(const std::exception_ptr & error, const std::shared_ptr<void>& context) {
         auto promise = std::static_pointer_cast<std::promise<bool>>(context);
         promise->set_exception(error);
      }
      
  4. 您可以選擇性地使用 F6 ( 建置方案 ) 來執行解決方案的測試編譯/連結,以確保它成功建置,然後再繼續。

新增邏輯以設定並取得敏感度標籤

使用檔案引擎物件,新增邏輯以在檔案上設定並取得敏感度標籤。

  1. 使用 方案總管 ,在您的專案中開啟包含 方法實作的 main() .cpp 檔案。 它預設為與您在專案建立期間指定的專案相同名稱。

  2. 在檔案頂端的對應現有指示詞下方,新增下列 #includeusing 指示詞:

    #include "filehandler_observer.h" 
    #include "mip/file/file_handler.h" 
    
    using mip::FileHandler;
    
  3. 在本文結尾 main() 處、下方 system("pause"); 和上方 return 0; (您在上一個快速入門中離開的位置),插入下列程式碼:

    // Set up async FileHandler for input file operations
    string inputFilePath = "<input-file-path>";
    string actualFilePath = "<content-identifier>";
    std::shared_ptr<FileHandler> handler;
    try
    {
         auto handlerPromise = std::make_shared<std::promise<std::shared_ptr<FileHandler>>>();
         auto handlerFuture = handlerPromise->get_future();
         engine->CreateFileHandlerAsync(
              inputFilePath,
              actualFilePath,                       
              true, 
              std::make_shared<FileHandlerObserver>(), 
              handlerPromise);
         handler = handlerFuture.get();
    }
    catch (const std::exception& e)
    {
         cout << "An exception occurred... did you specify a valid input file path?\n\n" << e.what() << "'\n";
         system("pause");
         return 1;
    }
    
    // Set a label on input file
    try
    {
         string labelId = "<label-id>";
         cout << "\nApplying Label ID " << labelId << " to " << filePathIn << endl;
         mip::LabelingOptions labelingOptions(mip::AssignmentMethod::PRIVILEGED);
         handler->SetLabel(engine->GetLabelById(labelId), labelingOptions, new ProtectionSettings());
    }
    catch (const std::exception& e)
    {
         cout << "An exception occurred... did you specify a valid label ID?\n\n" << e.what() << "'\n";
         system("pause");
         return 1; 
    }
    
    // Commit changes, save as a different/output file
    string filePathOut = "<output-file-path>";
    try
    {
     	cout << "Committing changes" << endl;
         auto commitPromise = std::make_shared<std::promise<bool>>();
         auto commitFuture = commitPromise->get_future();
         handler->CommitAsync(filePathOut, commitPromise);
     	if (commitFuture.get()) {
     		cout << "\nLabel committed to file: " << filePathOut << endl;
     	}
     	else {
     		cout << "Failed to label: " + filePathOut << endl;
     		return 1;
     	}
    }
    catch (const std::exception& e)
    {
         cout << "An exception occurred... did you specify a valid commit file path?\n\n" << e.what() << "'\n";
         system("pause");
         return 1;
    }
    system("pause");
    
    // Set up async FileHandler for output file operations
    actualFilePath = "<content-identifier>";
    try
    {
         auto handlerPromise = std::make_shared<std::promise<std::shared_ptr<FileHandler>>>();
         auto handlerFuture = handlerPromise->get_future();
         engine->CreateFileHandlerAsync(
              filePathOut,
              actualFilePath,
              true,
              std::make_shared<FileHandlerObserver>(),
              handlerPromise);
    
         handler = handlerFuture.get();
    }
    catch (const std::exception& e)
    {
         cout << "An exception occurred... did you specify a valid output file path?\n\n" << e.what() << "'\n";
         system("pause");
         return 1;
    }
    
    // Get the label from output file
    try
    {
         cout << "\nGetting the label committed to file: " << filePathOut << endl;
         auto label = handler->GetLabel();
         cout << "Name: " + label->GetLabel()->GetName() << endl;
         cout << "Id: " + label->GetLabel()->GetId() << endl;
    }
    catch (const std::exception& e)
    {
         cout << "An exception occurred... did you specify a valid label ID?\n\n" << e.what() << "'\n";
         system("pause");
         return 1;
    }
    system("pause");
    
  4. 在結尾 main() 尋找在第一個快速入門中建立的應用程式關機區塊,並取消批註處理常式行:

    // Application shutdown. Null out profile and engine, call ReleaseAllResources();
    // Application may crash at shutdown if resources aren't properly released.
    profile = nullptr;
    engine = nullptr;
    handler = nullptr;
    mipContext = nullptr;
    
  5. 使用字串常數取代原始程式碼中的預留位置值:

    預留位置
    <input-file-path> 測試輸入檔的完整路徑,例如: "c:\\Test\\Test.docx"
    <content-identifier> 內容的人類可讀取識別碼。 例如:
    • 針對檔案,請考慮 path\filename: "c:\Test\Test.docx"
    • 針對電子郵件,請考慮 subject:sender : "RE: Audit design:user1@contoso.com"
    <label-id> 從上一個快速入門中的主控台輸出複製的敏感度標籤識別碼,例如: "f42a3342-8706-4288-bd31-ebb85995028z"
    <output-file-path> 輸出檔案的完整路徑,這會是輸入檔的標籤複本,例如: "c:\\Test\\Test_labeled.docx"

建置及測試應用程式

建置及測試用戶端應用程式。

  1. 使用 F6 ( 建置解決方案 ) 來建置用戶端應用程式。 如果您沒有建置錯誤,請使用 F5 ( 開始偵錯 ) 來執行應用程式。

  2. 如果您的專案建置並成功執行,應用程式會在每次 SDK 呼叫您的 AcquireOAuth2Token() 方法時,提示輸入存取權杖。 如同您先前在「列出敏感度標籤」快速入門中所做的,請使用針對$authority和$resourceUrl提供的值,執行 PowerShell 腳本以每次取得權杖。

    Run the PowerShell script to generate an access token using the following values, then copy/paste it below:
    
    Sensitivity labels for your organization:
    Non-Business : 87ba5c36-17cf-14793-bbc2-bd5b3a9f95cz
    Public : 83867195-f2b8-2ac2-b0b6-6bb73cb33afz
    General : f42a3342-8706-4288-bd31-ebb85995028z
    Confidential : 074e457c-5848-4542-9a6f-34a182080e7z
    Highly Confidential : f55c2dea-db0f-47cd-8520-a52e1590fb6z
    Press any key to continue . . .
    
    Applying Label ID 074e457c-5848-4542-9a6f-34a182080e7z to c:\Test\Test.docx
    Committing changes
    
    Label committed to file: c:\Test\Test_labeled.docx
    Press any key to continue . . .
    
    Getting the label committed to file: c:\Test\Test_labeled.docx
    Name: Confidential
    Id: 074e457c-5848-4542-9a6f-34a182080e7z
    Press any key to continue . . .
    

您可以開啟輸出檔案,並以視覺化方式檢查檔的資訊保護設定,來驗證標籤的應用程式。

注意

如果您要標記 Office 檔,但未使用取得存取權杖的 Microsoft Entra 租使用者帳戶登入(且已設定敏感度標籤),則系統可能會提示您登入,才能開啟標示的檔。