Microsoft Information Protection SDK – Dateihandlerkonzepte

Im MIP File SDK stellt mip::FileHandler die Vorgänge zum Lesen und Schreiben von Bezeichnungen oder Schutz für Dateitypen mit integrierter Unterstützung bereit.

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:

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

Anforderungen

Um eine FileHandler Datei für die Arbeit mit einer bestimmten Datei zu erstellen, geben Sie Folgendes an:

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

Erstellen eines Dateihandlers

Der erste Schritt beim Verwalten von Dateien im File SDK besteht darin, ein FileHandler Objekt zu erstellen. Diese Klasse enthält die Funktionalität, die zum Abrufen, Festlegen, Aktualisieren, Löschen und Übernehmen von Bezeichnungsänderungen an Dateien erforderlich ist.

Erstellen Sie das FileHandler, indem Sie die Funktion CreateFileHandlerAsync von FileEngine mithilfe des Promise/Future-Musters aufrufen.

CreateFileHandlerAsync akzeptiert die folgenden Parameter: den Pfad zu der Datei, die gelesen oder geändert werden soll, den Pfad für die Audit-Berichterstattung, ein Flag, das die Audit-Erkennung aktiviert, das mip::FileHandler::Observer für asynchrone Ereignisbenachrichtigungen und das Promise für das FileHandler.

Note

Implementieren Sie die Klasse mip::FileHandler::Observer in einer abgeleiteten Klasse, da CreateFileHandler das Objekt Observer erfordert.

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

Nachdem Sie das FileHandler Objekt erstellt haben, können Sie Dateivorgänge ausführen (get/set/delete/commit).

Lesen einer Bezeichnung

Erforderliche Metadaten

Das erfolgreiche Lesen von Metadaten aus einer Datei und das Übersetzen in etwas, das von Anwendungen verwendet werden kann, hat einige Anforderungen.

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

GetLabel()

Nachdem Sie den Handler erstellt haben, der auf eine bestimmte Datei verweist, lesen Sie die Beschriftung synchron, indem Sie fileHandler->GetLabel() aufrufen. Die Methode gibt ein mip::ContentLabel Objekt zurück, das alle Informationen zur angewendeten Bezeichnung enthält.

auto label = fileHandler->GetLabel();

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

Festlegen einer Bezeichnung

Das Festlegen einer Bezeichnung ist ein zweiteiliger Prozess. Nachdem Sie einen Handler erstellt haben, der auf die betreffende Datei verweist, legen Sie die Bezeichnung fest, indem Sie FileHandler->SetLabel() mit einigen Parametern aufrufen: mip::Label, mip::LabelingOptions und mip::ProtectionOptions. Lösen Sie zunächst die Label-ID zu einem Label auf und definieren Sie anschließend die Beschriftungsoptionen.

Bezeichnungs-ID auf mip::Label auflösen

Der erste Parameter der Funktion SetLabel ist ein mip::Label. Häufig arbeitet die Anwendung mit Label-IDs anstelle von Beschriftungen. Lösen Sie den Etikett-Identifikator mip::Label durch den Aufruf von GetLabelById in der Datei- oder Richtlinien-Engine auf:

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

Bezeichnungsoptionen

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

LabelingOptions gibt weitere Informationen zur 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.
  • Geben Sie nur dann eine Begründung an, wenn die Dienstrichtlinie dies erfordert und wenn Sie die bestehende Sensibilität einer Datei herabsetzen.

Dieser Codeausschnitt veranschaulicht, wie das mip::LabelingOptions-Objekt erstellt und die Downgrade-Begründung und -Nachricht festgelegt werden.

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 Auftrag einer delegierten Benutzeridentität ausführen. Mit mip::ProtectionSettings der Klasse kann die Anwendung die delegierte Identität pro Handler definieren. Zuvor übernahmen die Engine-Klassen die Delegierung. Dieses Design hatte erhebliche Nachteile beim Anwendungsmehraufwand und bei Roundtrips zum Dienst. Durch das Verschieben der delegierten Benutzereinstellungen in mip::ProtectionSettings die Handlerklasse wird dieser Aufwand beseitigt, wodurch die Leistung für Anwendungen verbessert wird, die viele Vorgänge im Auftrag verschiedener Benutzeridentitäten ausführen.

Wenn Sie keine Delegation benötigen, übergeben Sie mip::ProtectionSettings() an die Funktion SetLabel. Wenn Sie eine Delegierung benötigen, erstellen Sie ein mip::ProtectionSettings Objekt, und legen Sie die delegierte E-Mail-Adresse fest:

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

Legen Sie die Bezeichnung fest

Nachdem Sie mip::Label anhand der ID abgerufen, die Bezeichnungsoptionen festgelegt und optional die Schutzeinstellungen konfiguriert haben, können Sie die Bezeichnung auf dem Handler festlegen.

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 zum Ausführen eines delegierten Vorgangs benötigen, verwenden Sie Folgendes:

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

Nachdem Sie die Bezeichnung für die Datei festgelegt haben, auf die der Handler verweist, übernehmen Sie die Änderung, und schreiben Sie eine Datei auf den Datenträger, oder erstellen Sie einen Ausgabedatenstrom.

Committen von Änderungen

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

Um die Commit-Funktion zu implementieren, wechseln Sie zurück zu Promise/Future und erstellen ein Promise für ein bool. Die CommitAsync() Funktion gibt true zurück, wenn der Vorgang erfolgreich war oder falsch, wenn der Vorgang aus irgendeinem Grund fehlgeschlagen ist.

Nachdem Sie promise und std::string erstellt haben, rufen Sie future auf und übergeben Sie zwei Parameter: den Ausgabedateipfad (CommitAsync()) und das Promise. Rufen Sie abschließend das Ergebnis ab, indem Sie den Wert des future Objekts abrufen.

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

Wichtig

Vorhandene FileHandler Dateien werden nicht aktualisiert oder überschrieben. Sie müssen den Ersatz für die Datei implementieren, die Sie bezeichnen.

Wenn Sie FileA.docx eine Bezeichnung zuweisen, erstellt CommitAsync() eine Kopie der Datei, FileB.docx, auf die die Bezeichnung angewendet wurde. Schreiben Sie Code, um FileA.docx zu entfernen oder umzubenennen und FileB.docxumzubenennen.

Löschen einer Bezeichnung

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

Schutz entfernen

Überprüfen Sie, ob der Benutzer über Rechte zum Entfernen des Schutzes der Datei verfügt, auf die zugegriffen wird. Führen Sie vor dem Entfernen des Schutzes eine Zugriffsüberprüfung durch .

Die RemoveProtection() Funktion verhält sich ähnlich wie SetLabel() oder DeleteLabel(). Rufen Sie die Methode für das vorhandene FileHandler-Objekt auf und committen Sie anschließend die Änderung.

Wichtig

Als Anwendungsentwickler liegt es in Ihrer Verantwortung, diese Zugriffsüberprüfung durchzuführen. Fehler beim ordnungsgemäßen Ausführen der Zugriffsüberprüfung können zu Datenlecks führen.

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

Nächste Schritte

  • Last updated on