Microsoft Information Protection 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
  • FileProfileに FileEngine を追加
  • 継承するクラスmip::FileHandler::Observer

ファイル ハンドラーを作成する

ファイル SDK でファイルを管理するために必要な最初の手順は、FileHandler オブジェクトの作成です。 このクラスは、ファイルのラベル変更を取得、設定、更新、削除、およびコミットするために必要なすべての機能を実装します。

FileHandler の作成は、promise/future パターンを使用して FileEngineの CreateFileHandlerAsync 関数を呼び出すのと同じくらい簡単です。

CreateFileHandlerAsync は 3 つのパラメータを受け入れます: 読み取りまたは変更するファイルへのパス、mip::FileHandler::Observer は非同期イベント通知用、FileHandler は Promise です。

注:CreateFileHandler には Observer オブジェクトが必要であるため、 mip::FileHandler::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 オブジェクトの作成に成功すると、ファイル操作 (取得/設定/削除/コミット) を実行できるようになります。

ラベルを読む

メタデータの要件

ファイルからメタデータを正常に読み取り、アプリケーションで使用できるものに変換するには、いくつかの要件があります。

  • 読み取られるラベルは、Microsoft 365 サービスにまだ存在している必要があります。 完全に削除されている場合、SDK はそのラベルに関する情報を取得できず、エラーを返します。
  • ファイルのメタデータはそのままである必要があります。 このメタデータには次のものが含まれます。
    • 属性1
    • 属性2

GetLabelAsync()

特定のファイルを指すハンドラーを作成したら、promise/future パターンに戻り、ラベルを非同期的に読み取ります。 Promise は、適用されたラベルに関するすべての情報を含む 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 オブジェクトから読み取って、アプリケーション内の他のコンポーネントまたは機能に渡すことができます。

ラベルを設定する

ラベルの設定は 2 つの部分からなるプロセスです。 最初に、対象のファイルを指すハンドラーを作成したため、いくつかのパラメーター (mip::Label、mip::LabelingOptions、mip::ProtectionOptions) を指定して FileHandler->SetLabel() を呼び出すことで、ラベルを設定できます。 まず、ラベル ID をラベルに解決してから、ラベル付けオプションを定義する必要があります。

ラベル ID を mip::Label に解決します

SetLabel 関数の最初のパラメーターは mip::Label です。 多くの場合、アプリケーションで操作しているのはラベルではなくラベル識別子です。 ラベル識別子は、ファイルまたはポリシー エンジンで GetLabelById を呼び出すことによって mip::Label に解決できます。

mip::Label label = mEngine->GetLabelById(labelId);

ラベル付けオプション

ラベルを設定するために必要な 2 番目のパラメーターは mip::LabelingOptions です。

LabelingOptions は、AssignmentMethod やアクションの正当性など、ラベルに関する追加情報を指定します。

  • mip::AssignmentMethod は、STANDARD、PRIVILEGED、または AUTO の 3 つの値を持つ列挙子です。 詳細については、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.");

保護設定

アプリケーションによっては、委任されたユーザー ID に代わって操作を実行することが必要な場合があります。 アプリケーションでは mip::ProtectionSettings クラスを使用して、委任された ID をハンドラーごとに定義できます。 以前は、委任はエンジン クラスによって実行されていました。 これは、アプリケーションのオーバーヘッドとサービスのラウンド トリップの面で非常に不利でした。 委任されたユーザー設定を mip::ProtectionSettings に移動してハンドラー クラスの一部にすることにより、このオーバーヘッドが排除され、さまざまなユーザー ID のセットに代わって多くの操作を実行するアプリケーションのパフォーマンスが向上します。

委任が必要ない場合は、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);

ハンドラーによって参照されるファイルにラベルを設定したので、変更をコミットしてファイルをディスクに書き込むか、出力ストリームを作成する手順がさらに 1 つあります。

変更をコミットする

MIP SDK 内のファイルへの変更をコミットする最後のステップは、変更をコミットすることです。 これは、FileHandler->CommitAsync() 関数を使用して実現されます。

コミットメント関数を実装するには、promise/future に戻り、bool の Promise を作成します。 CommitAsync()関数は、操作が成功した場合は true を返し、何らかの理由で失敗した場合は false を返します。

promise と future を作成した後、CommitAsync() が呼び出され、出力ファイル パス (std::string) と Promise の 2 つのパラメーターが指定されます。 最後に、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 File 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.Extract) || 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.");
    }
}