Guida introduttiva: Impostare e ottenere un'etichetta di riservatezza (C++)

Articolo
01/30/2024

Questa guida introduttiva illustra come usare più SDK di file MIP. Usando una delle etichette di riservatezza elencate nella guida introduttiva precedente, si usa un gestore file per impostare/ottenere l'etichetta in un file. La classe gestore file espone varie operazioni per l'impostazione/recupero di etichette o la protezione per i tipi di file supportati.

Prerequisiti

Se non è già stato fatto, assicurarsi di completare i prerequisiti seguenti prima di continuare:

Completare la guida introduttiva: Elencare prima le etichette di riservatezza (C++), che compila una soluzione Visual Studio iniziale per elencare le etichette di riservatezza di un'organizzazione. Questa guida introduttiva "Impostare e ottenere un'etichetta di riservatezza" si basa su quella precedente.
Facoltativamente: esaminare i gestori di file nei concetti di MIP SDK .

Implementare una classe observer per monitorare l'oggetto Gestore file

Analogamente all'osservatore implementato (per il profilo file e il motore) nella guida introduttiva all'inizializzazione dell'applicazione, ora si implementa una classe observer per un oggetto gestore file.

Creare un'implementazione di base per un osservatore del gestore file estendendo la classe dell'SDK mip::FileHandler::Observer . L'osservatore viene creata un'istanza e usata in un secondo momento per monitorare le operazioni del gestore file.

Aprire la soluzione di Visual Studio in uso nell'articolo precedente "Guida introduttiva: Elencare le etichette di riservatezza (C++)".
Aggiungere una nuova classe al progetto, che genera automaticamente i file header/.h e implementation/.cpp:
- Nel Esplora soluzioni fare di nuovo clic con il pulsante destro del mouse sul nodo del progetto, selezionare Aggiungi e quindi selezionare Classe.
- Nella finestra di dialogo Aggiungi classe :
  - Nel campo Nome classe immettere "filehandler_observer". Si noti che i campi del file con estensione h e cpp vengono popolati automaticamente in base al nome immesso.
  - Al termine, fare clic sul pulsante OK .

Dopo aver generato i file con estensione h e cpp per la classe , entrambi i file vengono aperti nelle schede Gruppo editor. Aggiornare ora ogni file per implementare la nuova classe observer:

Aggiornare "filehandler_observer.h" selezionando/eliminando la classe generata filehandler_observer . Non rimuovere le direttive del preprocessore generate dal passaggio precedente (#pragma, #include). Copiare/incollare quindi l'origine seguente nel file, dopo eventuali direttive del preprocessore esistenti:

#include <memory>
#include "mip/file/file_engine.h"
#include "mip/file/file_handler.h"

class FileHandlerObserver final : public mip::FileHandler::Observer {
public:
   FileHandlerObserver() { }
   // Observer implementation
   void OnCreateFileHandlerSuccess(const std::shared_ptr<mip::FileHandler>& fileHandler, const std::shared_ptr<void>& context) override;
   void OnCreateFileHandlerFailure(const std::exception_ptr& error, const std::shared_ptr<void>& context) override;
   void OnCommitSuccess(bool committed, const std::shared_ptr<void>& context) override;
   void OnCommitFailure(const std::exception_ptr& error, const std::shared_ptr<void>& context) override;		
};

Aggiornare "filehandler_observer.cpp" selezionando/eliminando l'implementazione della classe generata filehandler_observer . Non rimuovere le direttive del preprocessore generate dal passaggio precedente (#pragma, #include). Copiare/incollare quindi l'origine seguente nel file, dopo eventuali direttive del preprocessore esistenti:

void FileHandlerObserver::OnCreateFileHandlerSuccess(const std::shared_ptr<mip::FileHandler>& fileHandler, const std::shared_ptr<void>& context) {
   auto promise = std::static_pointer_cast<std::promise<std::shared_ptr<mip::FileHandler>>>(context);
   promise->set_value(fileHandler);
}

void FileHandlerObserver::OnCreateFileHandlerFailure(const std::exception_ptr & error, const std::shared_ptr<void>& context) {
   auto promise = std::static_pointer_cast<std::promise<std::shared_ptr<mip::FileHandler>>>(context);
   promise->set_exception(error);
}

void FileHandlerObserver::OnCommitSuccess(bool committed, const std::shared_ptr<void>& context) {
   auto promise = std::static_pointer_cast<std::promise<bool>>(context);
   promise->set_value(committed);
}

void FileHandlerObserver::OnCommitFailure(const std::exception_ptr & error, const std::shared_ptr<void>& context) {
   auto promise = std::static_pointer_cast<std::promise<bool>>(context);
   promise->set_exception(error);
}

Facoltativamente, usare F6 (Compila soluzione) per eseguire una compilazione/collegamento di test della soluzione, per assicurarsi che venga compilata correttamente prima di continuare.

Aggiungere la logica per impostare e ottenere un'etichetta di riservatezza

Aggiungere la logica per impostare e ottenere un'etichetta di riservatezza in un file usando l'oggetto Motore file.

Usando Esplora soluzioni, aprire il file con estensione cpp nel progetto che contiene l'implementazione del main() metodo . Per impostazione predefinita, il nome del progetto che lo contiene è stato specificato durante la creazione del progetto.
Aggiungere le direttive e using seguenti#include, sotto le direttive esistenti corrispondenti, all'inizio del file:
```
#include "filehandler_observer.h" 
#include "mip/file/file_handler.h" 

using mip::FileHandler;
```

Verso la fine del main() corpo, sotto system("pause"); e sopra return 0; (dove è stata interrotta la guida introduttiva precedente), inserire il codice seguente:

// Set up async FileHandler for input file operations
string inputFilePath = "<input-file-path>";
string actualFilePath = "<content-identifier>";
std::shared_ptr<FileHandler> handler;
try
{
     auto handlerPromise = std::make_shared<std::promise<std::shared_ptr<FileHandler>>>();
     auto handlerFuture = handlerPromise->get_future();
     engine->CreateFileHandlerAsync(
          inputFilePath,
          actualFilePath,                       
          true, 
          std::make_shared<FileHandlerObserver>(), 
          handlerPromise);
     handler = handlerFuture.get();
}
catch (const std::exception& e)
{
     cout << "An exception occurred... did you specify a valid input file path?\n\n" << e.what() << "'\n";
     system("pause");
     return 1;
}

// Set a label on input file
try
{
     string labelId = "<label-id>";
     cout << "\nApplying Label ID " << labelId << " to " << filePathIn << endl;
     mip::LabelingOptions labelingOptions(mip::AssignmentMethod::PRIVILEGED);
     handler->SetLabel(engine->GetLabelById(labelId), labelingOptions, new ProtectionSettings());
}
catch (const std::exception& e)
{
     cout << "An exception occurred... did you specify a valid label ID?\n\n" << e.what() << "'\n";
     system("pause");
     return 1; 
}

// Commit changes, save as a different/output file
string filePathOut = "<output-file-path>";
try
{
 	cout << "Committing changes" << endl;
     auto commitPromise = std::make_shared<std::promise<bool>>();
     auto commitFuture = commitPromise->get_future();
     handler->CommitAsync(filePathOut, commitPromise);
 	if (commitFuture.get()) {
 		cout << "\nLabel committed to file: " << filePathOut << endl;
 	}
 	else {
 		cout << "Failed to label: " + filePathOut << endl;
 		return 1;
 	}
}
catch (const std::exception& e)
{
     cout << "An exception occurred... did you specify a valid commit file path?\n\n" << e.what() << "'\n";
     system("pause");
     return 1;
}
system("pause");

// Set up async FileHandler for output file operations
actualFilePath = "<content-identifier>";
try
{
     auto handlerPromise = std::make_shared<std::promise<std::shared_ptr<FileHandler>>>();
     auto handlerFuture = handlerPromise->get_future();
     engine->CreateFileHandlerAsync(
          filePathOut,
          actualFilePath,
          true,
          std::make_shared<FileHandlerObserver>(),
          handlerPromise);

     handler = handlerFuture.get();
}
catch (const std::exception& e)
{
     cout << "An exception occurred... did you specify a valid output file path?\n\n" << e.what() << "'\n";
     system("pause");
     return 1;
}

// Get the label from output file
try
{
     cout << "\nGetting the label committed to file: " << filePathOut << endl;
     auto label = handler->GetLabel();
     cout << "Name: " + label->GetLabel()->GetName() << endl;
     cout << "Id: " + label->GetLabel()->GetId() << endl;
}
catch (const std::exception& e)
{
     cout << "An exception occurred... did you specify a valid label ID?\n\n" << e.what() << "'\n";
     system("pause");
     return 1;
}
system("pause");

Verso la fine del blocco di arresto dell'applicazione main() creato nella prima guida introduttiva e rimuovere il commento dalla riga del gestore:

// Application shutdown. Null out profile and engine, call ReleaseAllResources();
// Application may crash at shutdown if resources aren't properly released.
profile = nullptr;
engine = nullptr;
handler = nullptr;
mipContext = nullptr;

Sostituire i valori segnaposto nel codice sorgente come indicato di seguito, usando costanti stringa:

Segnaposto	Valore
<input-file-path>	Percorso completo di un file di input di test, ad esempio : `"c:\\Test\\Test.docx"`.
<content-identifier>	Identificatore leggibile per il contenuto. Ad esempio: per un file, prendere in considerazione path\filename: `"c:\Test\Test.docx"` per un messaggio di posta elettronica, considerare subject:sender: `"RE: Audit design:user1@contoso.com"`
<label-id>	ID etichetta di riservatezza, copiato dall'output della console nell'argomento di avvio rapido precedente, ad esempio: `"f42a3342-8706-4288-bd31-ebb85995028z"`.
<output-file-path>	Percorso completo del file di output, che sarà una copia etichettata del file di input, ad esempio : `"c:\\Test\\Test_labeled.docx"`.

Compilare e testare l'applicazione

Compilare e testare l'applicazione client.

Usare F6 (Compila soluzione) per compilare l'applicazione client. Se non sono presenti errori di compilazione, usare F5 (Avvia debug) per eseguire l'applicazione.

Se il progetto viene compilato ed eseguito correttamente, l'applicazione richiede un token di accesso, ogni volta che l'SDK chiama il AcquireOAuth2Token() metodo. Come in precedenza nella guida introduttiva "Elencare le etichette di riservatezza", eseguire lo script di PowerShell per acquisire ogni volta il token, usando i valori forniti per $authority e $resourceUrl.

Run the PowerShell script to generate an access token using the following values, then copy/paste it below:

Sensitivity labels for your organization:
Non-Business : 87ba5c36-17cf-14793-bbc2-bd5b3a9f95cz
Public : 83867195-f2b8-2ac2-b0b6-6bb73cb33afz
General : f42a3342-8706-4288-bd31-ebb85995028z
Confidential : 074e457c-5848-4542-9a6f-34a182080e7z
Highly Confidential : f55c2dea-db0f-47cd-8520-a52e1590fb6z
Press any key to continue . . .

Applying Label ID 074e457c-5848-4542-9a6f-34a182080e7z to c:\Test\Test.docx
Committing changes

Label committed to file: c:\Test\Test_labeled.docx
Press any key to continue . . .

Getting the label committed to file: c:\Test\Test_labeled.docx
Name: Confidential
Id: 074e457c-5848-4542-9a6f-34a182080e7z
Press any key to continue . . .

È possibile verificare l'applicazione dell'etichetta aprendo il file di output e controllando visivamente le impostazioni di protezione delle informazioni del documento.

Nota

Se si assegna un'etichetta a un documento di Office, ma non si è connessi usando un account dal tenant di Microsoft Entra in cui è stato ottenuto il token di accesso (e vengono configurate le etichette di riservatezza), potrebbe essere richiesto di accedere prima di poter aprire il documento etichettato.