Microsoft Information Protection SDK – filhanterarbegrepp
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)
- 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()
Behov
För att skapa en FileHandler för att arbeta med en specifik fil krävs följande:
- En
FileProfile - En
FileEnginesom har lagts till iFileProfile - 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,PRIVILEGEDellerAUTO. Mer information finns i referensenmip::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 CommitAsync()futureanropas 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.");
}
}
Feedback
Kommer snart: Under hela 2024 kommer vi att fasa ut GitHub-problem som feedbackmekanism för innehåll och ersätta det med ett nytt feedbacksystem. Mer information finns i: https://aka.ms/ContentUserFeedback.
Skicka och visa feedback för