共用方式為

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 將無法取得該標籤的相關信息，而且會傳回錯誤。
  • 檔案元數據必須保持不變。 此元資料包括：
    • Attribute1
    • Attribute2

GetLabelAsync（）

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

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

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 和 之後，CommitAsync()會呼叫 並提供兩個參數：輸出檔案路徑 （std::stringfuture）， 和 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.");
    }
}