다음을 통해 공유

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
  • A가 FileEngine 에 추가됨 FileProfile
  • 상속되는 클래스 mip::FileHandler::Observer

파일 처리기 만들기

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

FileHandler 프라미스/미래 패턴을 사용하여 함수 CreateFileHandlerAsync 를 FileEngine호출하는 것만큼 쉽습니다.

CreateFileHandlerAsync 는 읽거나 수정해야 하는 파일의 경로, mip::FileHandler::Observer 비동기 이벤트 알림에 대한 경로 및 .에 대한 약속이라는 세 가지 매개 변수를 FileHandler허용합니다.

참고: 클래스는 mip::FileHandler::Observer 개체가 필요 Observer 하므로 파생 클래스 CreateFileHandler 에서 구현해야 합니다.

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() 하여 고독한 매개 변수로 제공하여 promise 레이블을 읽 future 습니다. 마지막으로 레이블을 가져올 개체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 다른 구성 요소 또는 기능으로 전달할 수 있습니다.

레이블 설정

레이블 설정은 두 부분으로 구성된 프로세스입니다. 먼저 문제의 파일을 가리키는 처리기를 만든 후 mip::Label, mip::LabelingOptions 및 mip::ProtectionOptions와 같은 일부 매개 변수를 사용해 FileHandler->SetLabel()을 호출하여 레이블을 설정할 수 있습니다. 먼저 레이블 ID를 레이블로 확인하고 레이블 지정 옵션을 정의해야 합니다.

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

SetLabel 함수의 첫 번째 매개 변수는 mip::Label입니다. 애플리케이션은 레이블이 아닌 레이블 식별자를 사용하는 경우가 많습니다. 레이블 식별자는 파일 또는 정책 엔진에서 GetLabelById를 호출하여 mip::Label로 확인할 수 있습니다.

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

레이블 지정 옵션

레이블을 설정하는 데 필요한 두 번째 매개 변수는 mip::LabelingOptions입니다.

LabelingOptions 는 작업에 대한 근거와 같은 레이블에 AssignmentMethod 대한 추가 정보를 지정합니다.

  • mip::AssignmentMethod는 세 개의 값이 PRIVILEGEDAUTO있는 열거자입니다STANDARD. 자세한 내용은 참조를 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. 함수는 CommitAsync() 작업이 성공하면 true를 반환하고 어떤 이유로든 실패하면 false를 반환합니다.

및 future를 CommitAsync() 만든 promise 후 호출되고 출력 파일 경로(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() 다음과 비슷하거나 DeleteLabel()같은 SetLabel() 방식으로 동작합니다. 메서드는 기존 FileHandler 개체에서 호출된 다음 변경 내용이 커밋되어야 합니다.

Important

애플리케이션 개발자는 이 액세스 검사를 수행하는 것이 사용자의 리포지토리입니다. 액세스 검사를 제대로 수행하지 못하면 데이터 누수에 다시 사용할 수 있습니다.

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.");
    }
}