Udostępnij za pośrednictwem

Microsoft Information Protection SDK — pojęcia dotyczące obsługi plików

W zestawie SDK plików MIP, mip::FileHandler udostępnia wszystkie operacje, które mogą być używane do odczytywania i zapisywania etykiet lub ochrony w różnych typach plików, dla których obsługa jest wbudowana.

Typy obsługiwanych plików

  • Formaty plików pakietu Office oparte na OPC (pakiet Office 2010 i nowsze)
  • Starsze formaty plików pakietu Office (Office 2007)
  • PDF
  • Ogólna obsługa pliku PFILE
  • Pliki obsługujące program Adobe XMP

Funkcje obsługi plików

mip::FileHandler uwidacznia metody odczytywania, zapisywania i usuwania zarówno etykiet, jak i informacji o ochronie. Aby uzyskać pełną listę, zapoznaj się z dokumentacją API.

W tym artykule zostaną omówione następujące metody:

  • GetLabelAsync()
  • SetLabel()
  • DeleteLabel()
  • RemoveProtection()
  • CommitAsync()

Wymagania

Utworzenie elementu FileHandler do pracy z określonym plikiem wymaga:

  • Polecenie FileProfile
  • Element FileEngine dodany do elementu FileProfile
  • Klasa, która dziedziczy mip::FileHandler::Observer

Utwórz procedurę obsługi plików

Pierwszym krokiem wymaganym do zarządzania dowolnymi plikami w SDK plików jest utworzenie obiektu FileHandler. Ta klasa implementuje wszystkie funkcje wymagane do pobierania, ustawiania, aktualizowania, usuwania i zatwierdzania zmian etykiet w plikach.

Tworzenie FileHandler jest tak proste, jak wywołanie funkcji CreateFileHandlerAsync obiektu FileEngine przy użyciu wzorca obietnica/przyszłość.

CreateFileHandlerAsync akceptuje trzy parametry: ścieżkę do pliku, który ma być odczytany lub zmodyfikowany, mip::FileHandler::Observer do powiadomień o zdarzeniach asynchronicznych i promesę dla FileHandler.

Uwaga:mip::FileHandler::Observer klasa musi być zaimplementowana w klasie pochodnej, ponieważ CreateFileHandler wymaga Observer obiektu .

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();

Po pomyślnym utworzeniu FileHandler obiektu można wykonać operacje na plikach (get/set/delete/commit).

Odczytywanie etykiety

Wymagania dotyczące metadanych

Istnieje kilka wymagań dotyczących pomyślnego odczytywania metadanych z pliku i tłumaczenia ich na coś, co może być używane w aplikacjach.

  • Odczytywana etykieta musi nadal istnieć w usłudze Microsoft 365. Jeśli zostanie on całkowicie usunięty, zestaw SDK nie będzie mógł uzyskać informacji o tej etykiecie i zwróci błąd.
  • Metadane pliku muszą być nienaruszone. Te metadane obejmują:
    • Atrybut1
    • Atrybut2

GetLabelAsync()

Po utworzeniu programu obsługi w celu wskazania określonego pliku wrócimy do wzorca obietnicy/przyszłego, aby asynchronicznie odczytać etykietę. Obietnica mip::ContentLabel dotyczy obiektu zawierającego wszystkie informacje o zastosowanej etykiecie.

Po utworzeniu obiektów promise i future, odczytujemy etykietę, wywołując fileHandler->GetLabelAsync() i podając promise jako jedyny parametr. Na koniec etykietę można przechowywać w mip::ContentLabel obiekcie, który otrzymamy z obiektu future.

auto loadPromise = std::make_shared<std::promise<std::shared_ptr<mip::ContentLabel>>>();
auto loadFuture = loadPromise->get_future();
fileHandler->GetLabelAsync(loadPromise);
auto label = loadFuture.get();

Dane etykiet mogą być odczytywane z label obiektu i przekazywane do dowolnego innego składnika lub funkcji w aplikacji.

Ustawianie etykiety

Ustawianie etykiety jest procesem dwuczęściowym. Najpierw po utworzeniu procedury obsługiwania wskazującej plik można ustawić etykietę, wywołując FileHandler->SetLabel() z pewnymi parametrami: mip::Label, mip::LabelingOptions i mip::ProtectionOptions. Najpierw musimy przypisać identyfikator etykiety do samej etykiety, a następnie zdefiniować opcje etykietowania.

Rozwiąż identyfikator etykiety na mip::Label

Pierwszy parametr funkcji SetLabel to mip::Label. Często aplikacja pracuje z identyfikatorami etykiet, a nie etykietami. Identyfikator etykiety można przypisać do mip::Label przez wywołanie GetLabelById na pliku lub aparacie zasad.

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

Opcje etykietowania

Drugi parametr wymagany do ustawienia etykiety to mip::LabelingOptions.

LabelingOptions Określa dodatkowe informacje o etykiecie, takie jak AssignmentMethod i uzasadnienie dla akcji.

  • mip::AssignmentMethodto moduł wyliczający, który ma trzy wartości: STANDARD, lub PRIVILEGEDAUTO. Zapoznaj się z mip::AssignmentMethod odniesieniem, aby uzyskać więcej informacji.
  • Uzasadnienie jest wymagane tylko wtedy, gdy zasady usługi tego wymagają i podczas obniżania istniejącej poufności pliku.

Ten fragment kodu przedstawia tworzenie obiektu mip::LabelingOptions oraz ustawianie uzasadnienia i komunikatu dotyczącego redukcji poziomu.

auto labelingOptions = mip::LabelingOptions(mip::AssignmentMethod::STANDARD);
labelingOptions.SetDowngradeJustification(true, "Because I made an educated decision based upon the contents of this file.");

Ustawienia zabezpieczeń

Niektóre aplikacje mogą wymagać wykonywania operacji w imieniu delegowanej tożsamości użytkownika. Klasa mip::ProtectionSettings umożliwia aplikacji zdefiniowanie delegowanej tożsamości dla każdego programu obsługi. Wcześniej delegowanie było wykonywane przez klasy silnika. Miało to znaczne wady związane z obciążeniem aplikacji i rundami usług. Przenosząc delegowane ustawienia użytkownika do mip::ProtectionSettings i tworząc tę część klasy obsługi, eliminujemy to obciążenie, co skutkuje lepszą wydajnością aplikacji wykonujących wiele operacji w imieniu różnych zestawów tożsamości użytkowników.

Jeśli delegowanie nie jest wymagane, przekaż mip::ProtectionSettings() do funkcji SetLabel. Jeśli delegowanie jest wymagane, można to osiągnąć, tworząc mip::ProtectionSettings obiekt i ustawiając delegowany adres e-mail:

mip::ProtectionSettings protectionSettings; 
protectionSettings.SetDelegatedUserEmail("alice@contoso.com");

Ustawianie etykiety

Po pobraniu mip::Label przy użyciu identyfikatora, ustawieniu opcji etykietowania i, opcjonalnie, ustawieniu ustawień ochrony, można teraz przypisać etykietę do procedury obsługi.

Jeśli nie ustawiono ustawień zabezpieczeń, ustaw etykietę, wywołując SetLabel na obsłudze:

fileHandler->SetLabel(label, labelingOptions, mip::ProtectionSettings());

Jeśli do wykonania operacji delegowanej wymagane są ustawienia ochrony, wykonaj następujące czynności:

fileHandler->SetLabel(label, labelingOptions, protectionSettings);

Po ustawieniu etykiety w pliku, do którego odwołuje się program obsługi, istnieje jeszcze jeden krok umożliwiający zatwierdzenie zmiany i zapisanie pliku na dysku lub utworzenie strumienia wyjściowego.

Zatwierdź zmiany

Ostatnim krokiem zatwierdzania wszelkich zmian w pliku w zestawie MIP SDK jest zatwierdzenie zmiany. Jest to realizowane przy użyciu FileHandler->CommitAsync() funkcji .

Aby zaimplementować funkcję zobowiązania, wracamy do obietnicy/przyszłości, tworząc obietnicę dla elementu bool. Funkcja CommitAsync() zwróci wartość true, jeśli operacja zakończyła się powodzeniem lub fałszem, jeśli nie powiodła się z jakiegokolwiek powodu.

Po utworzeniu promise i future, wywoływana jest CommitAsync() i podawane są dwa parametry: ścieżka pliku wyjściowego (std::string) i obietnica. Na koniec wynik jest uzyskiwany przez uzyskanie wartości future obiektu.

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

Ważne: Element FileHandler nie zaktualizuje ani nie zastąpi istniejących plików. Deweloper musi zaimplementować zastąpienie pliku, który jest oznaczony etykietą.

Jeśli napiszesz etykietę do FileA.docx, zostanie utworzona kopia pliku FileB.docx z zastosowaną etykietą. Kod musi zostać zapisany w celu usunięcia/zmiany nazwy FileA.docx i zmiany nazwy FileB.docx.

Usuwanie etykiety

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);

Usuwanie ochrony

Aplikacja zestawu MIP File SDK musi sprawdzić, czy użytkownik ma uprawnienia do usunięcia ochrony z pliku, do którego jest uzyskiwany dostęp. Można to zrobić, wykonując kontrolę dostępu przed usunięciem ochrony.

Funkcja RemoveProtection() zachowuje się w sposób podobny do SetLabel() lub DeleteLabel(). Metoda jest wywoływana w istniejącym FileHandler obiekcie, a następnie musi zostać zatwierdzona zmiana.

Ważne

Jako deweloper aplikacji można wykonać tę kontrolę dostępu. Nieprawidłowe sprawdzenie dostępu może skutkować wyciekiem danych.

Przykład języka 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.");
    }
}

Przykład platformy .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.");
    }
}