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를 만들려면 다음을 제공하세요:

• FileProfile
• FileEngine에 FileProfile 추가됨
• 상속되는 클래스 mip::FileHandler::Observer

파일 처리기 만들기

파일 SDK에서 파일을 관리하는 첫 번째 단계는 개체를 FileHandler 만드는 것입니다. 이 클래스에는 파일에 대한 레이블 변경 내용을 가져오기, 설정, 업데이트, 삭제 및 커밋하는 데 필요한 기능이 포함됩니다.

promise/future 패턴을 사용하여 CreateFileHandlerAsync의 FileEngine 함수를 호출해 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는 해당 레이블에 대한 정보를 가져오지 못하고 오류를 반환합니다.
• 파일 메타데이터는 그대로 유지되어야 합니다. 이 메타데이터에는 다음이 포함됩니다.
  • Attribute1
  • Attribute2

GetLabel()

특정 파일을 가리키는 처리기를 만든 후 호출 fileHandler->GetLabel()하여 레이블을 동기적으로 읽습니다. 이 메서드는 적용된 mip::ContentLabel 레이블에 대한 모든 정보를 포함하는 개체를 반환합니다.

auto label = fileHandler->GetLabel();

label 객체에서 레이블 데이터를 읽어 애플리케이션의 다른 구성 요소나 기능에 전달할 수 있습니다.

---

레이블 설정

레이블 설정은 두 부분으로 구성된 프로세스입니다. 해당 파일을 가리키는 처리기를 만든 후 일부 매개 변수mip::Labelmip::LabelingOptionsmip::ProtectionOptions를 사용하여 호출 FileHandler->SetLabel() 하여 레이블을 설정합니다. 먼저 레이블 ID를 해당 레이블로 확인한 다음 레이블 지정 옵션을 정의합니다.

레이블 ID를 mip::Label으로 확인

SetLabel 함수의 첫 번째 매개 변수는 mip::Label입니다. 애플리케이션은 대개 레이블 자체가 아니라 레이블 식별자를 사용합니다. 파일 또는 정책 엔진에서 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.");

보호 설정

일부 애플리케이션은 위임된 사용자 ID를 대신하여 작업을 수행해야 할 수 있습니다. 클래스 mip::ProtectionSettings 를 사용하면 애플리케이션이 처리기당 위임된 ID를 정의할 수 있습니다. 이전에는 엔진 클래스가 위임을 수행했습니다. 이러한 디자인은 애플리케이션 오버헤드 및 서비스 왕복에 상당한 단점이 있었습니다. 위임된 사용자 설정을 mip::ProtectionSettings 처리기 클래스의 일부로 이동하면 이러한 오버헤드가 없어지므로 다양한 사용자 ID 집합을 대신하여 많은 작업을 수행하는 애플리케이션의 성능이 향상됩니다.

위임이 필요하지 않은 경우 SetLabel 함수에 전달 mip::ProtectionSettings() 합니다. 위임이 필요한 경우 개체를 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에 대한 promise를 생성합니다. 함수는 CommitAsync() 작업이 성공하면 true를 반환하고 어떤 이유로든 실패하면 false를 반환합니다.

promise 및 future를 만든 후 std::string를 호출하고, 출력 파일 경로(CommitAsync())와 프라미스, 이렇게 두 개의 매개변수를 전달합니다. 마지막으로 개체의 future 값을 가져와 결과를 가져옵니다.

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

중요

FileHandler 기존 파일을 업데이트하거나 덮어쓰지 않습니다. 레이블을 지정할 파일에 대해 대체를 구현해야 합니다.

FileA.docxCommitAsync() 레이블을 작성하는 경우 레이블이 적용된 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 파일 SDK C++ 샘플을 탐색합니다.