Microsoft Information Protection SDK – filhanterarbegrepp

I MIP File SDK:t tillhandahåller mip::FileHandler de åtgärder som används för att läsa och skriva etiketter eller skydd för filtyper med inbyggt stöd.

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.

Den här artikeln beskriver följande metoder:

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

Krav

Om du vill skapa en FileHandler för att arbeta med en specifik fil anger du:

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

Skapa en filhanterare

Det första steget i att hantera filer i File SDK är att skapa ett FileHandler objekt. Den här klassen innehåller den funktionalitet som krävs för att hämta, ställa in, uppdatera, ta bort och spara ändringar av etiketter för filer.

Skapa FileHandler genom att anropa CreateFileHandlerAsync-funktionen för FileEngine med hjälp av promise/future-mönstret.

CreateFileHandlerAsync accepterar följande parametrar: sökvägen till filen för att läsa eller ändra, sökvägen som ska användas för granskningsrapportering, en flagga som aktiverar granskningsidentifiering, mip::FileHandler::Observer för asynkrona händelsemeddelanden och löftet för FileHandler.

Note

mip::FileHandler::Observer Implementera klassen i en härledd klass eftersom CreateFileHandler objektet Observer krävs.

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

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

Läsa en etikett

Metadatakrav

Att läsa metadata från en fil och översätta dem till något som program kan använda har några krav.

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

GetLabel()

När du har skapat hanteraren som pekar på en specifik fil läser du etiketten synkront genom att anropa fileHandler->GetLabel(). Metoden returnerar ett mip::ContentLabel objekt som innehåller all information om den tillämpade etiketten.

auto label = fileHandler->GetLabel();

Du kan läsa etikettdata från label objektet och skicka dem till andra komponenter eller funktioner i programmet.

Ställ in en etikett

Att ange en etikett är en process i två delar. När du har skapat en hanterare som pekar på filen i fråga anger du etiketten genom att anropa FileHandler->SetLabel() med några parametrar: mip::Label, mip::LabelingOptionsoch mip::ProtectionOptions. Först översätter du etikett-ID:t till en etikett och anger sedan alternativen för etikettering.

Lös 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. Matcha etikettidentifieraren till mip::Label genom att anropa GetLabelById på filen eller principmotorn:

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

Etiketteringsalternativ

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

LabelingOptions anger mer 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 .
  • Ange endast motivering om tjänstprincipen kräver det och när du sänker den befintliga känsligheten för en fil.

Det här kodfragmentet 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örde motorklasserna delegeringen. Den designen hade betydande nackdelar med programomkostnader och tjänsteresor. Om du flyttar de delegerade användarinställningarna till och gör dem till mip::ProtectionSettings en del av hanteringsklassen eliminerar du den här kostnaden, vilket förbättrar prestandan för program som utför många åtgärder för olika uppsättningar med användaridentiteter.

Om du inte behöver delegering, skicka mip::ProtectionSettings() till funktionen SetLabel. Om du behöver delegering skapar du ett mip::ProtectionSettings objekt och anger den delegerade e-postadressen:

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

Ange etiketten

När du har hämtat mip::Label med hjälp av ID:t anger du etiketteringsalternativen och om du vill ange skyddsinställningarna kan du ange etiketten på hanteraren.

Om du inte har angett skyddsinställningar ska du ange etiketten genom att anropa SetLabel på hanteraren:

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

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

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

När du har angett etiketten för filen som hanteraren hänvisar till bekräftar du ändringen och sparar en fil på disk eller skapar 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. Använd FileHandler->CommitAsync() funktionen.

Om du vill implementera åtagandefunktionen återgår du 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 har skapat promise och futureanropar CommitAsync() och anger du två parametrar: sökvägen för utdatafilen (std::string) och löftet. Slutligen hämtar du resultatet genom att hämta objektets future värde.

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. Du måste implementera ersättning för den fil som du etiketterar.

Om du skriver en etikett till FileA.docxCommitAsync() skapar du en kopia av filen ,FileB.docx, med etiketten tillämpad. Skriv kod för att ta bort eller byta namn på FileA.docx och byta namn påFileB.docx.

Ta bort en etikett

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

Ta bort skydd

Kontrollera att användaren har behörighet att ta bort skyddet från filen som används. Utför en åtkomstkontroll innan du tar bort skyddet.

Funktionen RemoveProtection() beter sig på samma sätt som SetLabel() eller DeleteLabel(). Anropa metoden på det befintliga FileHandler-objektet och verkställ sedan ändringen.

Viktigt!

Som programutvecklare är det ditt ansvar att utföra den här åtkomstkontrollen. Om åtkomstkontrollen inte utförs korrekt kan det leda till 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.");
    }
}

Nästa steg

  • Uppdaterades senast