共用方式為

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

在 MIP 檔案 SDK 中，mip::FileHandler 提供可用於讀取和寫入標籤或保護的各種操作，適用於支援內建的多種檔案類型。

支援的檔案類型

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

檔案處理程式函式

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

在本文中，將涵蓋下列方法：

  • GetLabelAsync()
  • SetLabel()
  • DeleteLabel()
  • RemoveProtection()
  • CommitAsync()

需求

建立FileHandler來使用特定檔案需要：

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

建立檔案處理器

在管理檔案 SDK 中的任何檔案時，第一個步驟是建立一個FileHandler物件。 這個類別會實作取得、設定、更新、刪除和認可檔案標籤變更所需的所有功能。

創建FileHandler 就像使用 promise/future 模式，呼叫FileEngine的函數CreateFileHandlerAsync一樣簡單。

CreateFileHandlerAsync 接受三個參數：應該讀取或修改之檔案的路徑、mip::FileHandler::Observer 用於異步事件通知，以及用於 FileHandler 的承諾。

注意： 類別 mip::FileHandler::Observer 必須在衍生類別中實作，因為 CreateFileHandler 需要 Observer 物件。

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

成功建立 FileHandler 對象之後，可以執行檔案作業（get/set/delete/commit）。

讀取標籤

元數據需求

為了成功地從檔案中讀取元數據，並將其轉換成可在應用程式中使用的內容，需要符合一些要求。

  • 正在讀取的標籤仍必須存在於 Microsoft 365 服務中。 如果完全刪除，SDK 將無法取得該標籤的相關信息，而且會傳回錯誤。
  • 檔案元數據必須保持不變。 此元資料包括：
    • 屬性1
    • 屬性2

GetLabelAsync（）

建立處理程式以指向特定檔案之後，我們會回到 promise/future 模式，以異步方式讀取標籤。 這項承諾適用於 mip::ContentLabel 物件，其中包含套用標籤的所有資訊。

具現化 promise 和 對象之後，我們會藉由呼叫 future 並提供 fileHandler->GetLabelAsync()promise 作為單一參數來讀取標籤。 最後，標籤可以儲存在我們將從future獲得的mip::ContentLabel物件中。

auto loadPromise = std::make_shared<std::promise<std::shared_ptr<mip::ContentLabel>>>();
auto loadFuture = loadPromise->get_future();
fileHandler->GetLabelAsync(loadPromise);
auto label = loadFuture.get();

標籤數據可以從 label 物件中讀取，並傳遞至應用程式中的任何其他元件或功能。

設定標籤

設定標籤是一個包含兩部分的過程。 首先，建立指向有問題的檔案的處理程式之後，可以使用某些參數呼叫 FileHandler->SetLabel() 來設定標籤： mip::Label、 mip::LabelingOptions和 mip::ProtectionOptions。 首先，我們必須將標籤標識碼解析為標籤，然後定義標籤選項。

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

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

mip::Label label = mEngine->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");

設定標籤

使用標識符擷取 mip::Label 、設定標籤選項，以及選擇性地設定保護設定之後，現在可以在處理程式上設定標籤。

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

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

如果您確實需要保護設定來執行委派的作業，則：

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

現在，在處理程式所參考的檔案上設定標籤之後，還有一個步驟可以認可變更，並將檔案寫入磁碟或建立輸出數據流。

提交變更

在 MIP SDK 中，將任何變更認可到檔案的最後一步是 認可 該變更。 使用FileHandler->CommitAsync()函式來完成這項工作。

為了實作承諾功能，我們將回到 promise/future，為bool創造一個承諾。 CommitAsync()如果作業成功，則函式會傳回 true;如果作業因任何原因而失敗，則傳回 false。

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

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

重要：FileHandler不會更新或覆寫現有的檔案。 開發人員自行決定是否要實作取代已加上標籤的檔案。

如果將標籤添加至FileA.docx，則會建立一個名為FileB.docx的複本，並套用標籤。 程式代碼必須寫入以移除/重新命名 FileA.docx ，並重新命名 FileB.docx。

刪除標籤

auto fileHandler = mEngine->CreateFileHandler(filePath, std::make_shared<FileHandlerObserverImpl>());
fileHandler->DeleteLabel(mip::AssignmentMethod::PRIVILEGED, "Label unnecessary.");
auto commitPromise = std::make_shared<std::promise<bool>>();
auto commitFuture = commitPromise->get_future();
fileHandler->CommitAsync(outputFile, commitPromise);

拿掉保護

您的 MIP 檔案 SDK 應用程式必須驗證使用者有權移除所存取檔案的保護。 這可以藉由在移除保護之前執行 存取檢查 來完成。

函 RemoveProtection() 式的行為方式類似 SetLabel() 或 DeleteLabel()。 在現有的 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.");
    }
}
  • Last updated on