Microsoft Information Protection SDK - Concetti relativi al motore di File SDK

  • Articolo

mip::FileEngine in MIP File SDK fornisce un'interfaccia a tutte le operazioni eseguite per conto di un'identità specificata. Verrà aggiunto un motore per ogni utente che accede all'applicazione e tutte le operazioni eseguite dal motore verranno eseguite nel contesto di tale identità.

Ha FileEngine due responsabilità principali: elencare le etichette per un utente autenticato e creare gestori di file per eseguire operazioni sui file per conto dell'utente.

  • mip::FileEngine
  • ListSensitivityLabels(): ottiene l'elenco di etichette per il motore caricato.
  • CreateFileHandler(): crea un oggetto per un file o un mip::FileHandler flusso specifico.

Aggiungere un motore di file

Come illustrato negli oggetti Profile e Engine, un motore può avere due stati : CREATED o LOADED. Se non è uno di questi due stati, non esiste. Per creare e caricare uno stato, è necessario eseguire una singola chiamata a FileProfile::LoadAsync. Se il motore esiste già nello stato memorizzato nella cache, sarà LOADED. Se non esiste, sarà CREATED e LOADED. CREATED implica che l'applicazione dispone di tutte le informazioni del servizio necessarie per caricare il motore. LOADED implica che tutte le strutture di dati necessarie per sfruttare il motore sono state create in memoria.

Creare Impostazioni del motore di file

Analogamente a un profilo, il motore richiede anche un oggetto impostazioni, mip::FileEngine::Settings. Questo oggetto archivia l'identificatore univoco del motore, l'implementazione mip::AuthDelegate , i dati client personalizzabili che possono essere usati per il debug o la telemetria e, facoltativamente, le impostazioni locali.

In questo caso viene creato un FileEngine::Settings oggetto denominato motore Impostazioni usando l'identità dell'utente dell'applicazione.

FileEngine::Settings engineSettings(
  mip::Identity(mUsername), // mip::Identity.
  authDelegateImpl,         // auth delegate object
  "",                       // Client data. Customizable by developer, stored with engine.
  "en-US",                  // Locale.
  false);                   // Load sensitive information types for driving classification.

Quando si crea il motore Impostazioni in questo modo, è importante impostare in modo esplicito anche un engineId univoco tramite:

engineSettings.SetEngineId(engineId);

L'uso del nome utente o del messaggio di posta elettronica consente di assicurarsi che lo stesso motore venga caricato ogni volta che l'utente usa il servizio o l'applicazione.

È anche valido fornire un ID motore personalizzato:

FileEngine::Settings engineSettings(
  "myEngineId",     // string
  authDelegateImpl, // auth delegate object
  "",               // Client data in string format. Customizable by developer, stored with engine.
  "en-US",          // Locale. Default is en-US
  false);           // Load sensitive information types for driving classification. Default is false.

Come procedura consigliata, il primo parametro, id, deve essere qualcosa che consente al motore di essere facilmente connesso all'utente associato. Un elemento simile all'indirizzo di posta elettronica, all'UPN o al GUID dell'oggetto AAD garantisce che l'ID sia univoco e possa essere caricato dallo stato locale senza chiamare il servizio.

Aggiungere il motore di file

Per aggiungere il motore, si tornerà al modello promise/future usato per caricare il profilo. Anziché creare la promessa per mip::FileProfile, viene creata usando mip::FileEngine.

  //auto profile will be std::shared_ptr<mip::FileProfile>
  auto profile = profileFuture.get();

  // Instantiate the AuthDelegate implementation.
  auto authDelegateImpl = std::make_shared<sample::auth::AuthDelegateImpl>(appInfo, userName, password);

  //Create the FileEngine::Settings object
  FileEngine::Settings engineSettings("UniqueID", authDelegateImpl, "");

  //Create a promise for std::shared_ptr<mip::FileEngine>
  auto enginePromise = std::make_shared<std::promise<std::shared_ptr<mip::FileEngine>>>();

  //Instantiate the future from the promise
  auto engineFuture = enginePromise->get_future();

  //Add the engine using AddEngineAsync, passing in the engine settings and the promise
  profile->AddEngineAsync(engineSettings, enginePromise);

  //get the future value and store in std::shared_ptr<mip::FileEngine>
  auto engine = engineFuture.get();

Il risultato finale del codice precedente è che il motore per l'utente autenticato verrà aggiunto al profilo.

Elencare le etichette di riservatezza

Usando il motore aggiunto, è ora possibile elencare tutte le etichette di riservatezza disponibili per l'utente autenticato chiamando engine->ListSensitivityLabels().

ListSensitivityLabels() recupererà l'elenco di etichette e attributi di tali etichette per un utente specifico dal servizio. Il risultato viene archiviato in un vettore di std::shared_ptr<mip::Label>.

Altre informazioni sono disponibili qui su mip::Label.

ListSensitivityLabels()

std::vector<shared_ptr<mip::Label>> labels = engine->ListSensitivityLabels();

In alternativa, semplificato:

auto labels = engine->ListSensitivityLabels();

La stampa dei nomi è un modo semplice per mostrare che i criteri sono stati estratti correttamente dal servizio e sono stati in grado di ottenere le etichette. Per applicare l'etichetta, è necessario l'identificatore dell'etichetta. Il codice seguente scorre tutte le etichette, visualizzando name e id per ogni etichetta padre e figlio.

//Iterate through all labels in the vector
for (const auto& label : labels) {
  //Print label name and GUID
  cout << label->GetName() << " : " << label->GetId() << endl;

  //Print child label name and GUID
  for (const auto& child : label->GetChildren()) {
    cout << "->  " << child->GetName() <<  " : " << child->GetId() << endl;
  }
}

La raccolta di mip::Label restituiti da GetSensitivityLabels() può essere utilizzata per visualizzare tutte le etichette disponibili per l'utente e quindi, se selezionato, usare l'ID per applicare etichette a un file.

Passaggi successivi

Ora che il profilo viene caricato, il motore è stato aggiunto e sono disponibili etichette, è possibile aggiungere un gestore per iniziare a leggere, scrivere o rimuovere etichette dai file. Vedere Gestori di file in MIP SDK.