Microsoft Information Protection SDK - Concetti relativi al gestore file

In MIP File SDK mip::FileHandler espone tutte le varie operazioni che possono essere usate per leggere e scrivere etichette o protezione in un set di tipi di file per cui è integrato il supporto.

Tipi di file supportati

• Formati di file di Office basati su OPC (Office 2010 e versioni successive)
• Formati di file precedenti di Office (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.

In questo articolo verranno trattati i metodi seguenti:

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

Requisiti

La creazione di un FileHandler per lavorare con un file specifico richiede:

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

Creare un gestore di file

Il primo passaggio necessario per gestire tutti i file in File SDK consiste nel creare un FileHandler oggetto . Questa classe implementa tutte le funzionalità necessarie per ottenere, impostare, aggiornare, eliminare ed eseguire il commit delle modifiche delle etichette ai file.

Creare FileHandler è semplice quanto chiamare la funzione CreateFileHandlerAsync di FileEngine usando il pattern promise/future.

CreateFileHandlerAsync accetta tre parametri: il percorso del file che deve essere letto o modificato, il mip::FileHandler::Observer per le notifiche di eventi asincroni e la promessa per il FileHandler.

Nota: la mip::FileHandler::Observer classe deve essere implementata in una classe derivata perché CreateFileHandler richiede l'oggetto Observer .

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

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

Leggere un'etichetta

Requisiti dei metadati

Esistono alcuni requisiti per leggere correttamente i metadati da un file e tradurlo in un elemento che può essere usato nelle applicazioni.

• L'etichetta da leggere deve essere ancora presente nel servizio Microsoft 365. Se è stata eliminata completamente, l'SDK non otterrà informazioni su tale etichetta e restituirà un errore.
• I metadati del file devono essere intatti. Questi metadati includono:
  • Attribute1
  • Attribute2

GetLabelAsync()

Dopo aver creato il gestore per puntare a un file specifico, si torna al modello promise/future per leggere in modo asincrono l'etichetta. La promessa è relativa a un mip::ContentLabel oggetto che contiene tutte le informazioni sull'etichetta applicata.

Dopo aver istanziato gli oggetti promise e future, leggiamo l'etichetta chiamando fileHandler->GetLabelAsync() e passando promise come unico parametro. Infine, l'etichetta può essere archiviata in un mip::ContentLabel oggetto che otterremo da 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();

I dati etichetta possono essere letti dall'oggetto label e passati a qualsiasi altro componente o funzionalità nell'applicazione.

Impostare un'etichetta

L'impostazione di un'etichetta è un processo in due parti. Prima di tutto, dopo aver creato un gestore che punta al file in questione, l'etichetta può essere impostata chiamando FileHandler->SetLabel() con alcuni parametri: mip::Label, mip::LabelingOptionse mip::ProtectionOptions. Innanzitutto, dobbiamo ricavare l'etichetta a partire dal relativo ID 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 usa identificatori di etichetta anziché etichette. L'identificatore dell'etichetta può essere ricondotto a mip::Label chiamando GetLabelById nel motore file o criteri:

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

Opzioni di etichettatura

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

LabelingOptions specifica informazioni aggiuntive 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.
• La giustificazione è necessaria solo se i criteri di servizio lo richiedono e quando si riduce la sensibilità esistente di un file.

Questo frammento di codice illustra la creazione dell'oggetto mip::LabelingOptions e l'impostazione della giustificazione e del messaggio per il downgrade.

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, la delega era gestita dalle classi del motore. Ciò comportava svantaggi significativi in termini di overhead dell'applicazione e di round trip del servizio. Spostando le impostazioni utente delegate in mip::ProtectionSettings e rendendo tale parte della classe del gestore, si elimina questo sovraccarico, con conseguente miglioramento delle prestazioni per le applicazioni che eseguono molte operazioni per conto di diversi set di identità utente.

Se la delega non è richiesta, passare mip::ProtectionSettings() alla funzione SetLabel. Se è necessaria la delega, può essere ottenuta creando un mip::ProtectionSettings oggetto e impostando l'indirizzo di posta delegato:

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

Impostare l'etichetta

Dopo aver recuperato il mip::Label usando l'ID, aver impostato le opzioni di etichettatura e, facoltativamente, aver impostato le impostazioni di protezione, è ora 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 state necessarie impostazioni di protezione per eseguire un'operazione delegata, eseguire le operazioni seguenti:

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

Dopo aver impostato l'etichetta nel file a cui fa riferimento il gestore, esiste ancora un altro passaggio per 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. Questa operazione viene eseguita usando la FileHandler->CommitAsync() funzione .

Per implementare la funzione di commitment, ritorniamo a promise/future, creando una promise per un bool. La CommitAsync() funzione restituirà true se l'operazione ha avuto esito positivo o false se ha avuto esito negativo per qualsiasi motivo.

Dopo aver creato il promise e il future, CommitAsync() viene chiamato e vengono forniti due parametri: il percorso del file di output (std::string) e la Promise. Infine, il risultato viene ottenuto 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();

Importante:FileHandler non aggiornerà o sovrascriverà i file esistenti. Spetta allo sviluppatore implementare la sostituzione del file etichettato.

Se si scrive un'etichetta in FileA.docx, verrà creata una copia del file FileB.docx con l'etichetta applicata. Il codice deve essere scritto per rimuovere o rinominare FileA.docx e rinominare FileB.docx.

Eliminare un'etichetta

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

Rimuovere la protezione

L'applicazione MIP File SDK deve verificare che l'utente disponga dei diritti per rimuovere la protezione dal file a cui si accede. A tale scopo, è possibile eseguire un controllo di accesso prima di rimuovere la protezione.

La RemoveProtection() funzione si comporta in modo simile a SetLabel() o DeleteLabel(). Il metodo viene chiamato sull'oggetto esistente FileHandler , quindi è necessario 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.");
    }
}