Microsoft Information Protection SDK - Concetti relativi al gestore di file

Nell'SDK di MIP File, mip::FileHandler espone le operazioni che leggono e scrivono etichette o la protezione nei vari tipi di file supportati nativamente.

Tipi di file supportati

• Formati di file di Office basati su OPC (Office 2010 e versioni successive)
• Formati di file di Office legacy (Office 2007)
• PDF
• Supporto per PFILE generico
• File che supportano Adobe XMP

Funzioni del gestore di file

mip::FileHandler espone metodi per la lettura, la scrittura e la rimozione di etichette e informazioni di protezione. Per l’elenco completo, consultare il riferimento API.

Questo articolo illustra i metodi seguenti:

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

Requisiti

Per creare un FileHandler oggetto per lavorare con un file specifico, specificare:

• Un FileProfile
• Un FileEngine aggiunto al FileProfile
• Classe che eredita mip::FileHandler::Observer

Creare un gestore di file

Il primo passaggio per la gestione dei file in File SDK consiste nel creare un FileHandler oggetto . Questa classe include le funzionalità necessarie per ottenere, impostare, aggiornare, eliminare ed eseguire il commit delle modifiche delle etichette ai file.

Creare FileHandler chiamando la funzione CreateFileHandlerAsync di FileEngine utilizzando il pattern promise/future.

CreateFileHandlerAsync accetta i seguenti parametri: il percorso del file da leggere o modificare, il percorso da utilizzare per i report di audit, un flag che abilita il rilevamento dell'audit, il mip::FileHandler::Observer per le notifiche asincrone degli eventi e la promessa per il FileHandler.

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

Dopo aver creato l'oggetto FileHandler , è possibile eseguire operazioni sui file (get/set/delete/commit).

Leggere un'etichetta

Requisiti dei metadati

La lettura dei metadati da un file e la conversione in un elemento che le applicazioni possono usare hanno alcuni requisiti.

• L'etichetta da leggere deve essere ancora presente nel servizio Microsoft 365. Se un utente ha eliminato l'etichetta, l'SDK non riesce a ottenere informazioni su tale etichetta e restituisce un errore.
• I metadati del file devono essere intatti. Questi metadati includono:
  • Attribute1
  • Attribute2

GetLabel()

Dopo aver creato il gestore che punta a un file specifico, leggere l'etichetta in modo sincrono chiamando fileHandler->GetLabel(). Il metodo restituisce un mip::ContentLabel oggetto che contiene tutte le informazioni sull'etichetta applicata.

auto label = fileHandler->GetLabel();

È possibile leggere i dati delle etichette dall'oggetto label e passarli a qualsiasi altro componente o funzionalità nell'applicazione.

Impostare un'etichetta

L'impostazione di un'etichetta è un processo in due parti. Dopo aver creato un gestore che punta al file in questione, impostare l'etichetta chiamando FileHandler->SetLabel() con alcuni parametri: mip::Label, mip::LabelingOptionse mip::ProtectionOptions. Prima di tutto, risolvere l'ID etichetta in un'etichetta e quindi definire le opzioni di etichettatura.

Risolvere l'ID dell'etichetta in mip::Label

Il primo parametro della funzione SetLabel è .mip::Label Spesso, l'applicazione funziona con identificatori di etichetta anziché etichette. Risolvere l'identificatore dell'etichetta in mip::Label chiamando GetLabelById nel motore file o dei criteri:

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

Opzioni di etichettatura

Il secondo parametro necessario per impostare l'etichetta è mip::LabelingOptions.

LabelingOptions specifica ulteriori informazioni sull'etichetta, come AssignmentMethod e la giustificazione di un'azione.

• mip::AssignmentMethod è un enumeratore con tre valori: STANDARD, PRIVILEGEDo AUTO. Consultare il riferimento mip::AssignmentMethod per ulteriori dettagli.
• Fornire una giustificazione solo se i criteri di servizio lo richiedono e quando si riduce la sensibilità esistente di un file.

Questo frammento di codice illustra come creare l'oggetto mip::LabelingOptions e impostare la giustificazione del downgrade e il relativo messaggio.

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

Impostazioni di protezione

Alcune applicazioni potrebbero dover eseguire operazioni per conto di un'identità utente delegata. La mip::ProtectionSettings classe consente all'applicazione di definire l'identità delegata per ogni gestore. In precedenza, le classi del motore eseguivano la delegazione. Tale progettazione presentava svantaggi significativi nell'overhead dell'applicazione e nei round trip del servizio. Lo spostamento delle impostazioni dell'utente delegato in mip::ProtectionSettings e la loro integrazione nella classe del gestore elimina questo sovraccarico, migliorando così le prestazioni delle applicazioni che eseguono molte operazioni per conto di diversi insiemi di identità utente.

Se non è necessaria alcuna delega, passare mip::ProtectionSettings() alla funzione SetLabel. Se è necessaria la delega, creare un mip::ProtectionSettings oggetto e impostare l'indirizzo di posta elettronica delegato:

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

Impostare l'etichetta

Dopo aver recuperato mip::Label usando l'ID, impostare le opzioni di etichettatura e, facoltativamente, impostare le impostazioni di protezione, è possibile impostare l'etichetta nel gestore.

Se non sono state impostate le impostazioni di protezione, impostare l'etichetta chiamando SetLabel sul gestore:

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

Se sono necessarie impostazioni di protezione per eseguire un'operazione delegata, usare:

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

Dopo aver impostato l'etichetta nel file a cui fa riferimento il gestore, eseguire il commit della modifica e scrivere un file su disco o creare un flusso di output.

Confermare le modifiche

Il passaggio finale nel commit di qualsiasi modifica in un file in MIP SDK consiste nel eseguire il commit della modifica. Usare la funzione FileHandler->CommitAsync().

Per implementare la funzione di impegno, tornare a promise/future, creando una promessa per un boologgetto . La CommitAsync() funzione restituisce true se l'operazione ha avuto esito positivo o false se ha avuto esito negativo per qualsiasi motivo.

Dopo aver creato promise e CommitAsync(), chiama std::string e fornisci due parametri: il percorso del file di output (future) e la Promise. Infine, ottenere il risultato ottenendo il valore dell'oggetto future .

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

Se si scrive un'etichetta in FileA.docx, CommitAsync() crea una copia del file ,FileB.docx, con l'etichetta applicata. Scrivere codice per rimuovere o rinominare FileA.docx e rinominare FileB.docx.

Eliminare un'etichetta

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

Rimuovere la protezione

Verificare che l'utente disponga dei diritti per rimuovere la protezione dal file a cui si accede. Eseguire un controllo di accesso prima di rimuovere la protezione.

La RemoveProtection() funzione si comporta in modo analogo a SetLabel() o DeleteLabel(). Chiamare il metodo sull'oggetto esistente FileHandler e quindi eseguire il commit della modifica.

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

Esempio .NET:

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

Passaggi successivi

• Esplorare l'esempio C++ di MIP File SDK in GitHub.