Microsoft Information Protection SDK - concepten van bestandshandlers

In de MIP-bestands-SDK biedt mip::FileHandler de bewerkingen voor het lezen en schrijven van labels of beveiliging voor bestandstypen die ingebouwd worden ondersteund.

Ondersteunde bestandstypen

  • Office-bestandsindelingen op basis van OPC (Office 2010 en hoger)
  • Verouderde Office-bestandsindelingen (Office 2007)
  • PDF
  • Algemene PFILE-ondersteuning
  • Bestanden die Adobe XMP ondersteunen

Bestandsbeheerfuncties

mip::FileHandler biedt methoden voor het lezen, schrijven en verwijderen van zowel labels als beveiligingsinformatie. Raadpleeg de API-verwijzing voor de volledige lijst.

In dit artikel worden de volgende methoden behandeld:

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

Vereisten

Als u een FileHandler bestand wilt maken om te werken met een specifiek bestand, geeft u het volgende op:

  • Een FileProfile
  • Een FileEngine toegevoegd aan de FileProfile
  • Een klasse die wordt overgenomen mip::FileHandler::Observer

Een bestandshandler maken

De eerste stap bij het beheren van bestanden in de File SDK is het maken van een FileHandler object. Deze klasse bevat de functionaliteit die nodig is voor het ophalen, instellen, bijwerken, verwijderen en doorvoeren van labelwijzigingen in bestanden.

Maak de FileHandler door de functie CreateFileHandlerAsync van FileEngine aan te roepen met behulp van het promise/future-patroon.

CreateFileHandlerAsync accepteert de volgende parameters: het pad naar het bestand dat moet worden gelezen of gewijzigd, het pad dat moet worden gebruikt voor controlerapportage, een vlag die controledetectie mogelijk maakt, de mip::FileHandler::Observer voor asynchrone gebeurtenismeldingen en de belofte voor de FileHandler.

Note

Implementeer de mip::FileHandler::Observer klasse in een afgeleide klasse omdat CreateFileHandler het Observer object is vereist.

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

Nadat u het FileHandler object hebt gemaakt, kunt u bestandsbewerkingen uitvoeren (get/set/delete/commit).

Een label lezen

Vereisten voor metagegevens

Het lezen van metagegevens uit een bestand en het vertalen ervan in iets dat toepassingen kunnen gebruiken, heeft een aantal vereisten.

  • Het label dat wordt gelezen, moet nog steeds bestaan in de Microsoft 365-service. Als iemand het label heeft verwijderd, kan de SDK geen informatie over dat label ophalen en wordt er een fout geretourneerd.
  • De metagegevens van het bestand moeten intact zijn. Deze metagegevens omvatten:
    • Kenmerk1
    • Kenmerk2

GetLabel()

Nadat u de handler hebt gemaakt die verwijst naar een specifiek bestand, leest u het label synchroon door het aan te roepen fileHandler->GetLabel(). De methode retourneert een mip::ContentLabel object dat alle informatie over het toegepaste label bevat.

auto label = fileHandler->GetLabel();

U kunt labelgegevens van het label object lezen en doorgeven aan elk ander onderdeel of elke andere functionaliteit in de toepassing.

Een label instellen

Het instellen van een label is een tweedelige procedure. Nadat u een handler hebt gemaakt die verwijst naar het betreffende bestand, stelt u het label in door een aantal parameters aan te roepen FileHandler->SetLabel() : mip::Label, mip::LabelingOptionsen mip::ProtectionOptions. Los eerst de label-id om naar een label en definieer vervolgens de labelopties.

Label-id oplossen om te mip::Label

De eerste parameter van de functie SetLabel is een mip::Label. Vaak werkt de toepassing met label-id's in plaats van labels. Los de label-id mip::Label op door GetLabelById aan te roepen op het bestand of de beleidsengine:

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

Labelopties

De tweede parameter die is vereist om het label in te stellen, is mip::LabelingOptions.

LabelingOptions geeft meer informatie over het label, zoals de AssignmentMethod en reden voor een actie.

  • mip::AssignmentMethod is een enumerator met drie waarden: STANDARD, PRIVILEGEDof AUTO. Bekijk de mip::AssignmentMethod verwijzing voor meer informatie.
  • Geef alleen een reden op als het servicebeleid dit vereist en wanneer u de bestaande gevoeligheid van een bestand verlaagt.

Dit codefragment laat zien hoe u het mip::LabelingOptions object maakt en een downgrade-reden en -bericht instelt.

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

Beveiligingsinstellingen

Sommige toepassingen moeten mogelijk bewerkingen uitvoeren namens een gedelegeerde gebruikersidentiteit. Met mip::ProtectionSettings de klasse kan de toepassing de gedelegeerde identiteit per handler definiëren. Voorheen hebben de engineklassen de overdracht uitgevoerd. Dat ontwerp had aanzienlijke nadelen op het gebied van toepassingsoverhead en roundtrips naar services. Het verplaatsen van de gedelegeerde gebruikersinstellingen naar mip::ProtectionSettings en het maken van een deel van de handlerklasse elimineert deze overhead, waardoor de prestaties voor toepassingen die veel bewerkingen uitvoeren namens diverse sets gebruikersidentiteiten, worden verbeterd.

Als u geen delegatie nodig hebt, geeft u door aan de functie mip::ProtectionSettings(). Als u delegatie nodig hebt, maakt u een mip::ProtectionSettings object en stelt u het gedelegeerde e-mailadres in:

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

Het label instellen

Nadat u mip::Label met behulp van de ID hebt opgehaald, de labelopties hebt ingesteld en eventueel de beveiligingsinstellingen hebt ingesteld, kunt u het label voor de handler instellen.

Als u geen beveiligingsinstellingen hebt ingesteld, stelt u het label in door de handler aan te roepen SetLabel :

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

Als u beveiligingsinstellingen nodig hebt om een gedelegeerde bewerking uit te voeren, gebruikt u:

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

Nadat u het label hebt ingesteld op het bestand waarnaar de handler verwijst, voert u de wijziging door en schrijft u een bestand naar de schijf of maakt u een uitvoerstroom.

Wijzigingen doorvoeren

De laatste stap bij het doorvoeren van wijzigingen in een bestand in de MIP SDK is het doorvoeren van de wijziging. Gebruik de FileHandler->CommitAsync() functie.

Als u de toezeggingsfunctie wilt implementeren, keert u terug naar promise/future en maakt u een belofte voor een bool. De functie CommitAsync() geeft true terug als de bewerking is geslaagd, of false als deze om welke reden dan ook is mislukt.

Nadat u de promise en future hebt gemaakt, roept u CommitAsync() aan, waarbij u twee parameters opgeeft: het pad naar het uitvoerbestand (std::string) en de promise. Haal ten slotte het resultaat op door de waarde van het future object op te halen.

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

Belangrijk

Bestaande FileHandler bestanden worden niet bijgewerkt of overschreven. U moet vervanging implementeren voor het bestand dat u labelt.

Als u een label naar FileA.docxschrijft, CommitAsync() maakt u een kopie van het bestand, FileB.docx, met het label toegepast. Schrijf code om FileA.docx te verwijderen of de naam ervan te wijzigen en de naam vanFileB.docxte wijzigen.

Een label verwijderen

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

Beveiliging verwijderen

Controleer of de gebruiker rechten heeft om de beveiliging te verwijderen van het bestand dat wordt geopend. Voer een toegangscontrole uit voordat u de beveiliging verwijdert.

De RemoveProtection() functie gedraagt zich op dezelfde manier als SetLabel() of DeleteLabel(). Roep de methode voor het bestaande FileHandler object aan en voer vervolgens de wijziging door.

Belangrijk

Als ontwikkelaar van de toepassing is het uw verantwoordelijkheid om deze toegangscontrole uit te voeren. Als u de toegangscontrole niet goed uitvoert, kan dit leiden tot gegevenslekken.

C++-voorbeeld:

// 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-voorbeeld:

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

Volgende stappen 

  • Last updated on