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

  • Artykuł

W zestawie SDK plików MIP uwidacznia wszystkie różne operacje, mip::FileHandler które mogą służyć do odczytywania i zapisywania etykiet lub ochrony w zestawie typów 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ą interfejsu 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 dziedziczona mip::FileHandler::Observer

Tworzenie procedury obsługi plików

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

FileHandler Tworzenie elementu jest tak proste, jak wywoływanie FileEnginefunkcji przy CreateFileHandlerAsync użyciu wzorca obietnicy/przyszłości.

CreateFileHandlerAsync akceptuje trzy parametry: ścieżka do pliku, który ma zostać odczytany lub zmodyfikowany, mip::FileHandler::Observer powiadomienia o zdarzeniach asynchronicznych i obietnica dla elementu 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 promise wystąpienia obiektów i future odczytamy etykietę, wywołując fileHandler->GetLabelAsync() i podając parametr promise jako samotny. 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ługi wskazującej plik można ustawić etykietę za pomocą FileHandler->SetLabel() niektórych parametrów: mip::Label, mip::LabelingOptions, i mip::ProtectionOptions. Najpierw musimy rozpoznać identyfikator etykiety do etykiety, a następnie zdefiniować opcje etykietowania.

Rozpoznawanie identyfikatora etykiety do mip::Label

Pierwszy parametr funkcji SetLabel to mip::Label. Często aplikacja pracuje z identyfikatorami etykiet, a nie etykietami. Identyfikator etykiety można rozpoznać przez mip::Label wywołanie polecenia GetLabelById w pliku lub a aparatu 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 dokumentacją, mip::AssignmentMethod 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 mip::LabelingOptions obiektu i ustawianie uzasadnienia i komunikatu obniżania 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 tożsamości delegowanej na program obsługi. Wcześniej delegowanie było wykonywane przez klasy aparatu. 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() polecenie 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 identyfikatora, ustawieniu opcji etykietowania i opcjonalnie ustawieniu ustawień ochrony można teraz ustawić etykietę w procedurze obsługi.

Jeśli nie ustawiono ustawień ochrony, ustaw etykietę, wywołując SetLabel program obsługi:

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 elementu i CommitAsync()futurejest wywoływana promise i podano 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ą.

W przypadku zapisywania etykiety w pliku FileA.docx zostanie utworzona kopia pliku FileB.docx z zastosowaną etykietą. Kod należy zapisać, aby usunąć/zmienić nazwę FileA.docx i zmienić nazwę 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. Niepowodzenie prawidłowego sprawdzania dostępu może ponownie uruchomić w wycieku 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.Extract) || 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.");
    }
}