Microsoft Information Protection SDK - ファイルハンドラーの概念

MIP ファイル SDK では、 mip::FileHandler は、組み込みのサポートを使用して、ファイルの種類間でラベルまたは保護の読み取りと書き込みを行う操作を公開します。

サポートされているファイルの種類

OPC に基づく Office ファイル形式 (Office 2010 以降)
従来の Office ファイル形式 (Office 2007)
PDF
汎用PFILEサポート
Adobe XMPをサポートするファイル

ファイルハンドラー関数

mip::FileHandler は、ラベルと保護情報の両方の読み取り、書き込み、および削除のメソッドを公開します。完全なリストについては、API リファレンスを参照してください。

この記事では、次の方法について説明します。

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

要件

特定のファイルを操作する FileHandler を作成するには、次を指定します。

A FileProfile
FileEngineに FileProfile を追加
mip::FileHandler::Observerを継承するクラス

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

File SDK でファイルを管理する最初の手順は、 FileHandler オブジェクトを作成することです。このクラスには、ファイルに対するラベルの変更を取得、設定、更新、削除、コミットするために必要な機能が含まれています。

promise/future パターンを使用してFileEngineのCreateFileHandlerAsync関数を呼び出して、FileHandlerを作成します。

CreateFileHandlerAsync は、読み取りまたは変更するファイルへのパス、監査レポートに使用するパス、監査検出を有効にするフラグ、非同期イベント通知の mip::FileHandler::Observer 、および FileHandlerの promise を受け取ります。

Note

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, filePath, true, std::make_shared<FileHandlerObserver>(), createFileHandlerPromise);
auto fileHandler = createFileHandlerFuture.get();

FileHandler オブジェクトを作成したら、ファイル操作 (get/set/delete/commit) を実行できます。

ラベルを読む

メタデータの要件

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

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

GetLabel()

特定のファイルを指すハンドラーを作成した後、 fileHandler->GetLabel()を呼び出してラベルを同期的に読み取ります。このメソッドは、適用されたラベルに関するすべての情報を含む mip::ContentLabel オブジェクトを返します。

auto label = fileHandler->GetLabel();

label オブジェクトからラベルデータを読み取り、アプリケーション内の他のコンポーネントまたは機能に渡すことができます。

ラベルを設定する

ラベルの設定は 2 部構成のプロセスです。問題のファイルを指すハンドラーを作成した後、いくつかのパラメーター (mip::Label、mip::LabelingOptions、mip::ProtectionOptions) でFileHandler->SetLabel()を呼び出してラベルを設定します。まず、ラベル ID をラベルに解決してから、ラベル付けオプションを定義します。

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

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

std::shared_ptr<mip::Label> label = engine->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);

ハンドラーが参照するファイルにラベルを設定したら、変更をコミットし、ファイルをディスクに書き込むか、出力ストリームを作成します。

変更をコミットする

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

コミットメント関数を実装するには、promise/future に戻り、 boolの約束を作成します。 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にラベルを書き込む場合は、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()関数は、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.");
    }
}

次のステップ

GitHubの MIP File SDK C++ サンプルを確認します。

フィードバック

このページはお役に立ちましたか?

最終更新: 2026-09-21