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

W zestawie MIP File SDK mip::FileHandler udostępnia operacje służące do odczytywania i zapisywania etykiet lub ustawień ochrony w różnych typach plików objętych wbudowaną obsługą.

Typy obsługiwanych plików

  • Formaty plików pakietu Office oparte na protokole OPC (pakiet Office 2010 lub nowszy)
  • 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 omówiono następujące metody:

  • GetLabel()
  • SetLabel()
  • DeleteLabel()
  • RemoveProtection()
  • CommitAsync()

Wymagania

Aby utworzyć element FileHandler do pracy z określonym plikiem, podaj:

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

Utwórz procedurę obsługi plików

Pierwszym krokiem w zarządzaniu plikami w zestawie SDK File jest utworzenie obiektu FileHandler. Ta klasa zawiera funkcje wymagane do pobierania, ustawiania, aktualizowania, usuwania i zatwierdzania zmian etykiet w plikach.

Utwórz FileHandler, wywołując funkcję CreateFileHandlerAsync obiektu FileEngine przy użyciu wzorca promise/future.

CreateFileHandlerAsync przyjmuje następujące parametry: ścieżkę do pliku do odczytu lub modyfikacji, ścieżkę używaną do raportowania inspekcji, flagę włączającą wykrywanie inspekcji, mip::FileHandler::Observer do asynchronicznych powiadomień o zdarzeniach oraz obietnicę dla FileHandler.

Note

Zaimplementuj klasę mip::FileHandler::Observer 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, filePath, true, std::make_shared<FileHandlerObserver>(), createFileHandlerPromise);
auto fileHandler = createFileHandlerFuture.get();

Po utworzeniu FileHandler obiektu można wykonywać operacje na plikach (get/set/delete/commit).

Odczytywanie etykiety

Wymagania dotyczące metadanych

Pomyślne odczytywanie metadanych z pliku i przekształcanie ich do postaci, z której aplikacje mogą korzystać, ma kilka wymagań.

  • Odczytywana etykieta musi nadal istnieć w usłudze Microsoft 365. Jeśli ktoś usunął etykietę, zestaw SDK nie może uzyskać informacji o tej etykiecie i zwróci błąd.
  • Metadane pliku muszą być nienaruszone. Te metadane obejmują:
    • Atrybut1
    • Atrybut2

GetLabel()

Po utworzeniu procedury obsługi wskazującej określony plik należy odczytać etykietę synchronicznie, wywołując metodę fileHandler->GetLabel(). Metoda zwraca mip::ContentLabel obiekt zawierający wszystkie informacje o zastosowanej etykiecie.

auto label = fileHandler->GetLabel();

Możesz odczytać dane etykiety z label obiektu i przekazać je do dowolnego innego składnika lub funkcji w aplikacji.

Ustawianie etykiety

Ustawianie etykiety jest procesem dwuczęściowym. Po utworzeniu procedury obsługi wskazującej na dany plik ustaw etykietę, wywołując FileHandler->SetLabel() z kilkoma parametrami: mip::Label, mip::LabelingOptions i mip::ProtectionOptions. Najpierw przypisz identyfikator etykiety do etykiety, a następnie zdefiniuj opcje etykietowania.

Rozwiąż identyfikator etykiety na mip::Label

Pierwszy parametr funkcji SetLabel to mip::Label. Często aplikacja współpracuje z identyfikatorami etykiet, a nie etykietami. Ustal identyfikator etykiety na mip::Label, wywołując metodę GetLabelById w aparacie plików lub aparacie zasad:

std::shared_ptr<mip::Label> label = engine->GetLabelById(labelId);

Opcje etykietowania

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

LabelingOptions określa więcej informacji o etykiecie, takich jak AssignmentMethod i uzasadnienie 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.
  • Podaj uzasadnienie tylko wtedy, gdy zasady usługi tego wymagają i podczas obniżania istniejącej poufności pliku.

Ten fragment kodu pokazuje, jak utworzyć obiekt mip::LabelingOptions oraz ustawić uzasadnienie i komunikat dotyczące obniżenia wersji.

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 dla każdej procedury obsługi. Wcześniej klasy silnika odpowiadały za delegowanie. Ten projekt miał znaczne wady w obciążeniach aplikacji i rundach usług. Przeniesienie delegowanych ustawień użytkownika do mip::ProtectionSettings klasy obsługi i uczynienie ich częścią klasy obsługi eliminuje to obciążenie, co zwiększa wydajność aplikacji wykonujących wiele operacji w imieniu różnych zestawów tożsamości użytkowników.

Jeśli nie potrzebujesz delegowania, przekaż mip::ProtectionSettings() do funkcji SetLabel . Jeśli potrzebujesz delegowania, utwórz obiekt mip::ProtectionSettings i ustaw adres e-mail delegata:

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

Ustawianie etykiety

Po pobraniu elementu mip::Label za pomocą identyfikatora ustaw opcje etykietowania i opcjonalnie ustawienia ochrony, a następnie możesz ustawić etykietę w programie 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 potrzebujesz ustawień ochrony do wykonania operacji delegowanej, użyj:

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

Po ustawieniu etykiety w pliku, do którego odwołuje się program obsługi, zatwierdź zmianę i zapisz plik na dysku lub utwórz strumień wyjściowy.

Zatwierdź zmiany

Ostatnim krokiem zatwierdzania wszelkich zmian w pliku w zestawie MIP SDK jest zatwierdzenie zmiany. Użyj funkcji FileHandler->CommitAsync().

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

Po utworzeniu CommitAsync() i promise wywołaj future i przekaż dwa parametry: ścieżkę pliku wyjściowego (std::string) i obietnicę. Na koniec uzyskaj wynik, uzyskując wartość 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. Musisz zaimplementować zamiennik dla pliku, który oznaczasz.

Jeśli zapiszesz etykietę do FileA.docx, CommitAsync() utworzy kopię pliku, FileB.docx, z zastosowaną etykietą. Napisz kod, aby usunąć lub zmienić nazwę FileA.docx i zmienić nazwę FileB.docx.

Usuwanie etykiety

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

Usuwanie ochrony

Sprawdź, czy użytkownik ma prawa do usunięcia ochrony z pliku, do którego jest uzyskiwany dostęp. Przed usunięciem ochrony wykonaj kontrolę dostępu .

Funkcja RemoveProtection() działa podobnie jak SetLabel() lub DeleteLabel(). Wywołaj metodę w istniejącym FileHandler obiekcie, a następnie zatwierdź zmianę.

Ważne

Jako deweloper aplikacji ponosisz odpowiedzialność za wykonanie tej kontroli dostępu. Niepowodzenie prawidłowego sprawdzania dostępu może spowodować wyciek 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.");
    }
}

Następne kroki

  • Ostatnia aktualizacja o