Microsoft 資訊保護 SDK - 檔案處理概念

在 MIP 檔案 SDK 中，mip::FileHandler 會公開可跨具有內建支援的檔案類型讀取及寫入標籤或保護的作業。

支援的檔案類型

• 基於 OPC（Office 2010 及以後版本）的 Office 檔案格式
• 舊版 Office 檔案格式（Office 2007）
• PDF
• 通用 PFILE 支援
• 支援 Adobe XMP 的檔案

檔案處理程式函式

mip::FileHandler 會公開讀取、寫入及移除標籤和保護資訊的方法。 如需完整清單，請參閱 API 參考。

本文涵蓋以下方法：

• GetLabel()
• SetLabel()
• DeleteLabel()
• RemoveProtection()
• CommitAsync()

需求

若要建立可搭配特定檔案使用的 FileHandler，請提供：

• 一個 FileProfile
• FileEngine已新增至FileProfile
• 繼承的類別 mip::FileHandler::Observer

建立檔案處理器

在 File SDK 中管理檔案的第一步是建立一個 FileHandler 物件。 此類別包含取得、設定、更新、刪除及提交檔案標籤變更所需的功能。

藉由使用 promise/future 模式呼叫 CreateFileHandlerAsync 的 FileHandler 函式來建立 FileEngine。

CreateFileHandlerAsync 接受以下參數：要讀取或修改之檔案的路徑、用於稽核報告的路徑、啟用稽核探索的旗標、用於非同步事件通知的 mip::FileHandler::Observer，以及用於 FileHandler 的 promise。

auto createFileHandlerPromise = std::make_shared<std::promise<std::shared_ptr<mip::FileHandler>>>();
auto createFileHandlerFuture = createFileHandlerPromise->get_future();
fileEngine->CreateFileHandlerAsync(filePath, filePath, true, std::make_shared<FileHandlerObserver>(), createFileHandlerPromise);
auto fileHandler = createFileHandlerFuture.get();

建立 FileHandler 物件後，你可以執行檔案操作（取得/設定/刪除/提交）。

讀取標籤

元數據需求

成功從檔案讀取元資料並將其轉換成應用程式可用的內容，有幾個條件。

• 正在讀取的標籤仍必須存在於 Microsoft 365 服務中。 如果有人刪除了標籤，SDK 無法取得該標籤的資訊並回傳錯誤。
• 檔案元數據必須保持不變。 此元資料包括：
  • 屬性1
  • 屬性2

GetLabel（）

當你建立指向特定檔案的處理器後，請透過呼叫 fileHandler->GetLabel() 同步讀取標籤。 該方法會回傳一個 mip::ContentLabel 物件，其中包含已套用標籤的所有資訊。

auto label = fileHandler->GetLabel();

你可以從物件讀取標籤資料 label ，並將其傳達給應用程式中的任何其他元件或功能。

設定標籤

設定標籤是一個分為兩部分的過程。 當你建立一個指向相關檔案的處理常式後，請呼叫 FileHandler->SetLabel() 並傳入一些參數來設定標籤：mip::Label、mip::LabelingOptions 和 mip::ProtectionOptions。 首先，將標籤 ID 解析成標籤，然後定義標籤選項。

將標籤標識碼解析為 mip：：Label

SetLabel 函式的第一個mip::Label參數是 。 應用程式通常使用標籤識別碼而非標籤。 透過在檔案或政策引擎呼叫 GetLabelById，將標籤識別碼解析為mip::Label：

std::shared_ptr<mip::Label> label = engine->GetLabelById(labelId);

標籤選項

設定標籤的第二個參數是 mip::LabelingOptions。

LabelingOptions 指定標籤的更多資訊，例如 AssignmentMethod 和動作的理由。

• mip::AssignmentMethod 是具有三個值的列舉值： STANDARD、 PRIVILEGED或 AUTO。 如需詳細資訊，請檢閱 mip::AssignmentMethod 參考。
• 只有在服務原則要求提供理由 且 降低檔案現有敏感度時，才提供理由。

以下片段示範如何建立 mip::LabelingOptions 物件並設定降級理由與訊息。

auto labelingOptions = mip::LabelingOptions(mip::AssignmentMethod::STANDARD);
labelingOptions.SetDowngradeJustification(true, "Because I made an educated decision based upon the contents of this file.");

保護設定

有些應用程式可能需要代表委派的使用者身份執行操作。 mip::ProtectionSettings 類別可讓應用程式為 每個處理常式 定義委派身分。 先前，由引擎類別執行委派。 該設計在應用間接費用及往返服務上有顯著缺點。 將委派的使用者設定移至 mip::ProtectionSettings 並成為處理程式類別的一部分，消除了這些開銷，提升了代表多組使用者身份執行多項操作的應用程式的效能。

如果你不需要委派，就直接切換 mip::ProtectionSettings() 到 SetLabel 函式。 如果你需要委派，請建立一個 mip::ProtectionSettings 物件並設定委派的郵件地址：

mip::ProtectionSettings protectionSettings;
protectionSettings.SetDelegatedUserEmail("alice@contoso.com");

設定標籤

在使用 ID 擷取 mip::Label、設定標籤選項，並視需要設定保護設定之後，你可以在處理常式上設定標籤。

如果您未設定保護設定，請在處理程式上呼叫 SetLabel 來設定標籤：

fileHandler->SetLabel(label, labelingOptions, mip::ProtectionSettings());

如果你需要保護設定來執行委派操作，請使用：

fileHandler->SetLabel(label, labelingOptions, protectionSettings);

在你設定處理程式參考的檔案標籤後，提交變更並寫入檔案到磁碟或建立輸出串流。

提交變更

在 MIP SDK 中，將任何變更認可到檔案的最後一步是 認可 該變更。 使用 FileHandler->CommitAsync() 函數。

要實作 commitment function，回到 promise/future，為 bool 建立一個 promise。 若操作成功，該 CommitAsync() 函式回傳真;若因任何原因失敗，則回傳假。

建立 promise 和 future後，呼叫 CommitAsync() 並提供兩個參數：輸出檔案路徑（std::string）和承諾。 最後，透過取得物件的 future 值來得到結果。

auto commitPromise = std::make_shared<std::promise<bool>>();
auto commitFuture = commitPromise->get_future();
fileHandler->CommitAsync(outputFile, commitPromise);
auto wasCommitted = commitFuture.get();

如果你寫標籤給 FileA.docx， CommitAsync() 會產生一個帶有標籤的檔案副本， FileB.docx。 寫程式碼移除或重命名 FileA.docx 並重新命名 FileB.docx。

刪除標籤

auto createFileHandlerPromise = std::make_shared<std::promise<std::shared_ptr<mip::FileHandler>>>();
auto createFileHandlerFuture = createFileHandlerPromise->get_future();
mEngine->CreateFileHandlerAsync(filePath, filePath, true, std::make_shared<FileHandlerObserver>(), createFileHandlerPromise);
auto fileHandler = createFileHandlerFuture.get();

mip::LabelingOptions labelingOptions(mip::AssignmentMethod::PRIVILEGED);
labelingOptions.SetDowngradeJustification(true, "Label unnecessary.");
fileHandler->DeleteLabel(labelingOptions);

auto commitPromise = std::make_shared<std::promise<bool>>();
auto commitFuture = commitPromise->get_future();
fileHandler->CommitAsync(outputFile, commitPromise);

拿掉保護

驗證使用者是否有權移除被存取檔案的保護。 移除保護前請先進行 存取檢查 。

RemoveProtection() 函數的行為類似於 DeleteLabel() 或 SetLabel()。 呼叫現有 FileHandler 物件的方法，然後提交變更。

C++範例：

// Validate that the file referred to by the FileHandler is protected.
if (fileHandler->GetProtection() != nullptr)
{
    // Validate that user is allowed to remove protection.
    if (fileHandler->GetProtection()->AccessCheck(mip::rights::Export()) || fileHandler->GetProtection()->AccessCheck(mip::rights::Owner()))
    {
        auto commitPromise = std::make_shared<std::promise<bool>>();
        auto commitFuture = commitPromise->get_future();
        // Remove protection and commit changes to file.
        fileHandler->RemoveProtection();
        fileHandler->CommitAsync(outputFile, commitPromise);
        result = commitFuture.get();
    }
    else
    {
        // Throw an exception if the user doesn't have rights to remove protection.
        throw std::runtime_error("User doesn't have EXPORT or OWNER right.");
    }
}

.NET 範例：

if(handler.Protection != null)
{
    // Validate that user has rights to remove protection from the file.
    if(handler.Protection.AccessCheck(Rights.Export) || handler.Protection.AccessCheck(Rights.Owner))
    {
        // If user has Extract right, remove protection and commit the change. Otherwise, throw exception.
        handler.RemoveProtection();
        bool result = handler.CommitAsync(outputPath).GetAwaiter().GetResult();
        return result;
    }
    else
    {
        throw new Microsoft.InformationProtection.Exceptions.AccessDeniedException("User lacks EXPORT right.");
    }
}

下一步

• 請在 GitHub 上探索 MIP 檔案 SDK C++ 範例。