Microsoft Information Protection SDK - Concetti relativi al gestore file

  • Articolo

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 di Office legacy (Office 2007)
  • PDF
  • Supporto 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, vedere le informazioni di riferimento sulle API.

In questo articolo verranno trattati i metodi seguenti:

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

Requisiti

La creazione di un FileHandler oggetto per l'uso con un file specifico richiede:

  • Comando FileProfile
  • Oggetto FileEngine aggiunto all'oggetto 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.

FileHandler La creazione di è semplice come chiamare la FileEnginefunzione di CreateFileHandlerAsync usando il modello promise/future.

CreateFileHandlerAsyncaccetta tre parametri: percorso del file che deve essere letto o modificato, per mip::FileHandler::Observer le notifiche degli eventi asincroni e la promessa per .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 creato un'istanza degli promise oggetti e future , l'etichetta viene letta chiamando fileHandler->GetLabelAsync() e fornendo come promise parametro solitario. 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. Prima di tutto, è necessario risolvere l'ID etichetta in un'etichetta e quindi definire le opzioni di etichettatura.

Risolvere l'ID 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 risolto mip::Label in chiamando GetLabelById nel file o nel motore di 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, ad esempio e la AssignmentMethod giustificazione per un'azione.

  • mip::AssignmentMethod è un enumeratore con tre valori: STANDARD, PRIVILEGEDo AUTO. Per altri dettagli, vedere le mip::AssignmentMethod informazioni di riferimento.
  • La giustificazione è necessaria solo se i criteri di servizio lo richiedono e quando si riduce la sensibilità esistente di un file.

Questo snip illustra la creazione dell'oggetto e l'impostazione della mip::LabelingOptions giustificazione e del messaggio di 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 veniva eseguita dalle classi del motore. Ciò presentava svantaggi significativi nell'overhead dell'applicazione e nei 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 è necessaria, 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 usando l'ID mip::Label , impostare le opzioni di etichettatura e, facoltativamente, impostare le impostazioni di protezione, l'etichetta può ora essere impostata 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.

Eseguire il commit delle 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 impegno, si torna alla promessa/futuro, creando una promessa per un boologgetto . 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 e promisefuture, CommitAsync() viene chiamato e vengono forniti due parametri: il percorso del file di output (std::string) e la promessa. 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/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.

Importante

In qualità di sviluppatore di applicazioni, è la responsabilità di eseguire questo controllo di accesso. Se non si esegue correttamente il controllo di accesso, è possibile riutilizzare la perdita di dati.

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