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

파일 처리기 만들기

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

FileEngine의 CreateFileHandlerAsync 함수를 promise/future 패턴을 사용해 호출하는 것만큼 FileHandler을(를) 만드는 일은 간단합니다.

CreateFileHandlerAsync는 세 가지 매개변수를 받습니다. 읽거나 수정해야 하는 파일의 경로, 비동기 이벤트 알림을 위한 mip::FileHandler::Observer, 그리고 FileHandler에 대한 Promise입니다.

참고: 클래스는 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 패턴으로 돌아가서 레이블을 비동기적으로 읽습니다. Promise는 적용된 레이블에 관한 모든 정보가 포함된 mip::ContentLabel 개체를 반환합니다.

promise 및 future 객체를 인스턴스화한 후, promise를 유일한 매개변수로 전달하여 fileHandler->GetLabelAsync()를 호출해 레이블을 읽습니다. 마지막으로, 레이블은 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을 호출하여 레이블을 설정할 수 있습니다. 먼저 레이블 ID를 해당 레이블로 확인한 다음 레이블 지정 옵션을 정의해야 합니다.

레이블 ID를 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.");

보호 설정

일부 애플리케이션은 위임된 사용자 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에 대한 promise를 생성합니다. 함수는 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