Microsoft Information Protection SDK – Konzepte der Dateihandler

Im MIP File SDK stellt mip::FileHandler alle verschiedenen Vorgänge zur Verfügung, die zum Lesen und Schreiben von Kennzeichnungen oder zum Schutz über eine Reihe von Dateitypen verwendet werden können, für die eine Unterstützung eingebaut ist.

Unterstützte Dateitypen

• Office-Dateiformate basierend auf OPC (Office 2010 und höher)
• Ältere Office-Dateiformate (Office 2007)
• PDF
• Generische PFILE-Unterstützung
• Dateien, die Adobe XMP unterstützen

Dateihandlerfunktionen

mip::FileHandler stellt Methoden zum Lesen, Schreiben und Entfernen von Etiketten und Schutzinformationen bereit. Die vollständige Liste finden Sie in der API-Referenz.

In diesem Artikel werden die folgenden Methoden behandelt:

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

Anforderungen

Zum Erstellen einer FileHandler für die Arbeit mit einer bestimmten Datei ist Folgendes erforderlich:

• Einen FileProfile
• Ein FileEngine zu dem FileProfile hinzugefügt
• Eine Klasse, die mip::FileHandler::Observer erbt

Erstellen eines Dateihandlers

Der erste Schritt, der für die Verwaltung von Dateien im File SDK erforderlich ist, besteht darin, ein FileHandler-Objekt zu erstellen. Diese Klasse implementiert alle Funktionen, die zum Abrufen, Festlegen, Aktualisieren, Löschen und committen von Bezeichnungsänderungen an Dateien erforderlich sind.

Das Erstellen von FileHandler ist genauso einfach wie das Verwenden der FileEngine-Funktion von CreateFileHandlerAsync im Promise/Future-Muster.

CreateFileHandlerAsync akzeptiert drei Parameter: Der Pfad zu der Datei, die gelesen oder geändert werden soll, der mip::FileHandler::Observer für asynchrone Ereignisbenachrichtigungen und die Zusage für die FileHandler.

Hinweis: Die mip::FileHandler::Observer-Klasse muss in einer abgeleiteten Klasse implementiert werden, da für CreateFileHandler das Observer-Objekt erforderlich ist.

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

Nach dem erfolgreichen Erstellen des FileHandler-Objekts können Dateivorgänge (get/set/delete/commit) ausgeführt werden.

Lesen einer Bezeichnung

Erforderliche Metadaten

Es gibt einige Anforderungen, um Metadaten aus einer Datei erfolgreich zu lesen und in etwas zu übersetzen, das in Anwendungen verwendet werden kann.

• Das zu lesende Etikett muss noch im Microsoft 365-Dienst vorhanden sein. Wenn sie vollständig gelöscht wurde, kann das SDK keine Informationen zu dieser Bezeichnung abrufen und gibt einen Fehler zurück.
• Die Dateimetadaten müssen intakt sein. Diese Metadaten umfassen:
  • Attribute1
  • Attribute2

GetLabelAsync()

Nachdem wir den Handler erstellt haben, um auf eine bestimmte Datei zu verweisen, kehren wir zum Zusage-/zukünftigen Muster zurück, um die Bezeichnung asynchron zu lesen. Die Zusage ist für ein mip::ContentLabel-Objekt vorgesehen, das alle Informationen zur angewendeten Bezeichnung enthält.

Nach dem Instanziieren der promise- und future-Objekte lesen wir die Bezeichnung durch Aufrufen von fileHandler->GetLabelAsync() und Bereitstellen des promise als einzigen Parameter. Schließlich kann die Bezeichnung in einem mip::ContentLabel-Objekt gespeichert werden, das wir aus der future abrufen.

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

Bezeichnungsdaten können aus dem label-Objekt gelesen und an jede andere Komponente oder Funktionalität in der Anwendung übergeben werden.

Festlegen einer Bezeichnung

Das Festlegen einer Bezeichnung ist ein zweiteiliger Prozess. Nachdem ein Handler erstellt wurde, der auf die betreffende Datei verweist, kann das Etikett durch den Aufruf von FileHandler->SetLabel() mit einigen Parametern gesetzt werden: mip::Label, mip::LabelingOptions, und mip::ProtectionOptions. Zunächst müssen wir die Bezeichnungs-ID in eine Bezeichnung auflösen und dann die Bezeichnungsoptionen definieren.

Bezeichnungs-ID auf mip::Label auflösen

Der erste Parameter der Funktion SetLabel ist ein mip::Label. Häufig arbeitet die Anwendung mit Bezeichnungsbezeichnern anstelle von Bezeichnungen. Der Etikett-Identifikator kann durch den Aufruf von GetLabelById in der Datei- oder Richtlinien-Engine in mip::Label aufgelöst werden:

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

Bezeichnungsoptionen

Der zweite Parameter, der zum Setzen des Etiketts erforderlich ist, ist mip::LabelingOptions.

LabelingOptions gibt zusätzliche Informationen zu der Bezeichnung an, z. B. die AssignmentMethod und die Begründung für eine Aktion.

• mip::AssignmentMethod ist ein Enumerator mit drei Werten: STANDARD, PRIVILEGED oder AUTO. Weitere Informationen erhalten Sie in der mip::AssignmentMethod-Referenz.
• Eine Begründung ist nur erforderlich, wenn die Dienstrichtlinie sie erfordert und die vorhandene Vertraulichkeit einer Datei verringert.

Dieser Ausschnitt veranschaulicht die Erstellung des mip::LabelingOptions-Objekts und die Einstellung von Downgrade-Rechtfertigung und Meldung.

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

Schutzeinstellungen

Einige Anwendungen müssen möglicherweise Vorgänge im Namen einer delegierten Benutzeridentität ausführen. Die Klasse mip::ProtectionSettings ermöglicht es der Anwendung, die delegierte Identität pro Handler zu definieren. Zuvor wurde die Delegierung von den Modulklassen durchgeführt. Dies hatte erhebliche Nachteile bei Anwendungsaufwand und Service-Roundtrips. Indem wir die delegierten Benutzereinstellungen nach mip::ProtectionSettings verschieben und zum Bestandteil der Handler-Klasse machen, eliminieren wir diesen Overhead, was zu einer besseren Leistung für Anwendungen führt, die viele Vorgänge im Namen verschiedener Gruppen von Benutzeridentitäten durchführen.

Wenn keine Delegation erforderlich ist, übergeben Sie mip::ProtectionSettings() an die Funktion SetLabel. Wenn eine Delegation erforderlich ist, kann dies durch die Erstellung eines mip::ProtectionSettings-Objekts und die Festlegung der delegierten Mailadresse erreicht werden:

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

Legen Sie die Bezeichnung fest

Nachdem das mip::Label mithilfe der ID abgerufen wurde, und nachdem die Etikettierungsoptionen und optional die Schutzeinstellungen festgelegt wurden, kann nun das Etikett am Handler gesetzt werden.

Wenn Sie keine Schutzeinstellungen vorgenommen haben, setzen Sie das Etikett durch Aufruf von SetLabel im Handler:

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

Wenn Sie Schutzeinstellungen benötigen, um einen delegierten Vorgang auszuführen, dann:

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

Nachdem Sie nun die Bezeichnung für die Datei festgelegt haben, auf die vom Handler verwiesen wird, gibt es noch einen weiteren Schritt, um die Änderung zu übernehmen und eine Datei auf den Datenträger zu schreiben oder einen Ausgabestream zu erstellen.

Committen von Änderungen

Der letzte Schritt beim Commit einer Änderung an einer Datei im MIP SDK besteht darin, die Änderung zu comitten. Dazu wird die FileHandler->CommitAsync()-Funktion verwendet.

Um die Verpflichtungsfunktion zu implementieren, kehren wir zu Zusage/Zukunft zurück und erschaffen eine Zusage für ein bool. Die CommitAsync()-Funktion wird als „true“ zurückgegeben, wenn der Vorgang erfolgreich war oder als „false“, wenn er aus irgendeinem Grund fehlgeschlagen ist.

Nach dem Erstellen von promise und future, wird CommitAsync() aufgerufen und zwei Parameter bereitgestellt: Der Ausgabedateipfad (std::string) und die Zusage. Schließlich wird das Ergebnis durch Abrufen des Werts des future-Objekts abgerufen.

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

Wichtig:FileHandler wird keine bereits bestehenden Dateien aktualisieren oder überschreiben. Es liegt an dem Entwickler, das Ersetzen der Datei zu implementieren, die gerade bezeichnet wird.

Wenn Sie eine Bezeichnung in FileA.docx schreiben, wird eine Kopie der Datei, FileB.docx, mit der angewendeten Bezeichnung erstellt. Code muss geschrieben werden, um FileA.docx zu entfernen/umzubenennen und um FileB.docx umzubenennen.

Löschen einer Bezeichnung

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

Schutz entfernen

Ihre MIP File SDK-Anwendung muss überprüfen, ob der Benutzer über Rechte zum Entfernen des Schutzes der Datei verfügt, auf die zugegriffen wird. Dies kann durch Ausführen einer Zugriffsprüfung vor dem Entfernen des Schutzes erreicht werden.

Die RemoveProtection()-Funktion verhält sich ähnlich wie SetLabel() oder DeleteLabel(). Die Methode wird für das vorhandene FileHandler Objekt aufgerufen, dann muss die Änderung übertragen werden.

Beispiel für 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-Beispiel:

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