Dela via

Microsoft Information Protection SDK – filhanterarbegrepp

  • Artikel

I MIP File SDK mip::FileHandler exponerar alla olika åtgärder som kan användas för att läsa och skriva etiketter, eller skydd, över en uppsättning filtyper för vilka stöd är inbyggt.

Filtyper som stöds

  • Office-filformat baserade på OPC (Office 2010 och senare)
  • Äldre Office-filformat (Office 2007)
  • PDF
  • Allmänt PFILE-stöd
  • Filer som stöder Adobe XMP

Filhanterarfunktioner

mip::FileHandler exponerar metoder för att läsa, skriva och ta bort både etiketter och skyddsinformation. Den fullständiga listan finns i API-referensen.

I den här artikeln beskrivs följande metoder:

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

Krav

För att skapa en FileHandler för att arbeta med en specifik fil krävs följande:

  • En FileProfile
  • En FileEngine som har lagts till i FileProfile
  • En klass som ärver mip::FileHandler::Observer

Skapa en filhanterare

Det första steget som krävs för att hantera filer i File SDK är att skapa ett FileHandler objekt. Den här klassen implementerar alla funktioner som krävs för att hämta, ange, uppdatera, ta bort och checka in etikettändringar i filer.

FileHandler Att skapa är lika enkelt som att anropa FileEnginefunktionen 's CreateFileHandlerAsync med hjälp av promise/future-mönstret.

CreateFileHandlerAsync accepterar tre parametrar: Sökvägen till filen som ska läsas eller ändras, mip::FileHandler::Observer för asynkrona händelsemeddelanden och löftet för FileHandler.

Obs! Klassen mip::FileHandler::Observer måste implementeras i en härledd klass som CreateFileHandler kräver objektetObserver.

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

När objektet har skapats FileHandler kan filåtgärder (get/set/delete/commit) utföras.

Läsa en etikett

Metadatakrav

Det finns några krav för att kunna läsa metadata från en fil och översätta till något som kan användas i program.

  • Etiketten som läss måste fortfarande finnas i Microsoft 365-tjänsten. Om den har tagits bort helt kan SDK:et inte hämta information om etiketten och returnerar ett fel.
  • Filmetadata måste vara intakta. Dessa metadata omfattar:
    • Attribut1
    • Attribut 2

GetLabelAsync()

När vi har skapat hanteraren för att peka på en specifik fil återgår vi till promise/future-mönstret för att asynkront läsa etiketten. Löftet gäller för ett mip::ContentLabel objekt som innehåller all information om den tillämpade etiketten.

När vi har instansierat objekten promise och future läser vi etiketten genom att anropa fileHandler->GetLabelAsync() och ange promise som ensam parameter. Slutligen kan etiketten lagras i ett mip::ContentLabel objekt som vi får från 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();

Etikettdata kan läsas från label objektet och skickas till andra komponenter eller funktioner i programmet.

Ange en etikett

Att ange en etikett är en process i två delar. Först när du har skapat en hanterare som pekar på filen i fråga kan etiketten anges genom att anropa FileHandler->SetLabel() med några parametrar: mip::Label, mip::LabelingOptionsoch mip::ProtectionOptions. Först måste vi matcha etikett-ID:t till en etikett och sedan definiera etiketteringsalternativen.

Matcha etikett-ID till mip::Label

SetLabel-funktionens första parameter är en mip::Label. Ofta fungerar programmet med etikettidentifierare i stället för etiketter. Etikettidentifieraren kan matchas med genom att mip::Label anropa GetLabelById på filen eller principmotorn:

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

Etiketteringsalternativ

Den andra parametern som krävs för att ange etiketten är mip::LabelingOptions.

LabelingOptions anger ytterligare information om etiketten, till exempel motiveringen AssignmentMethod för en åtgärd.

  • mip::AssignmentMethod är en uppräknare som har tre värden: STANDARD, PRIVILEGEDeller AUTO. Mer information finns i referensen mip::AssignmentMethod .
  • Motivering krävs endast om tjänstprincipen kräver det och när du sänker den befintliga känsligheten för en fil.

Det här kodavsnittet visar hur du skapar mip::LabelingOptions objektet och anger nedgraderingsmotiveringen och meddelandet.

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

Skyddsinställningar

Vissa program kan behöva utföra åtgärder för en delegerad användaridentitet. Med mip::ProtectionSettings klassen kan programmet definiera den delegerade identiteten per hanterare. Tidigare utfördes delegeringen av motorklasserna. Detta hade betydande nackdelar med programomkostnader och tjänsteresor. Genom att flytta de delegerade användarinställningarna till mip::ProtectionSettings och göra den delen av hanteringsklassen eliminerar vi den här kostnaden, vilket ger bättre prestanda för program som utför många åtgärder för olika uppsättningar med användaridentiteter.

Om delegering inte krävs skickar du mip::ProtectionSettings() till funktionen SetLabel . Om delegering krävs kan det uppnås genom att skapa ett mip::ProtectionSettings objekt och ange den delegerade e-postadressen:

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

Ange etiketten

Efter att ha hämtat mip::Label med hjälp av ID:t, ställt in etiketteringsalternativen och, om du vill, ange skyddsinställningarna, kan etiketten nu ställas in på hanteraren.

Om du inte har angett skyddsinställningar anger du etiketten genom att anropa SetLabel hanteraren:

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

Om du behövde skyddsinställningar för att utföra en delegerad åtgärd:

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

När du nu har angett etiketten på filen som refereras av hanteraren finns det fortfarande ett steg till för att genomföra ändringen och skriva en fil till disken eller skapa en utdataström.

Genomför ändringar

Det sista steget i att genomföra ändringar i en fil i MIP SDK är att genomföra ändringen. Detta görs med hjälp FileHandler->CommitAsync() av funktionen .

För att implementera åtagandefunktionen återgår vi till promise/future och skapar ett löfte för en bool. Funktionen CommitAsync() returnerar sant om åtgärden lyckades eller falskt om den misslyckades av någon anledning.

När du promise har skapat och futureCommitAsync()anropas och två parametrar har angetts: Sökvägen till utdatafilen (std::string) och löftet. Slutligen erhålls resultatet genom att objektets värde hämtas future .

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

Viktigt: Kommer FileHandler inte att uppdatera eller skriva över befintliga filer. Det är upp till utvecklaren att implementera ersättning av filen som är märkt.

Om du skriver en etikett till FileA.docx skapas en kopia av filen, FileB.docx, med etiketten tillämpad. Koden måste skrivas för att ta bort/byta namn på FileA.docx och byta namn på FileB.docx.

Ta bort en etikett

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

Ta bort skydd

Ditt MIP File SDK-program måste verifiera att användaren har behörighet att ta bort skyddet från filen som används. Detta kan åstadkommas genom att utföra en åtkomstkontroll innan skyddet tas bort.

Funktionen RemoveProtection() beter sig på ett sätt som liknar SetLabel() eller DeleteLabel(). Metoden anropas för det befintliga FileHandler objektet. Ändringen måste sedan checkas in.

Viktigt!

Som programutvecklare är det din förtjänst att utföra den här åtkomstkontrollen. Om åtkomstkontrollen inte utförs korrekt kan det återanvändas i dataläckage.

C++-exempel:

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

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