Microsoft Information Protection SDK - Concetti relativi al motore dell'API FileMicrosoft Information Protection SDK - File API engine concepts

mip::FileEngine nell'API File di MIP SDK offre un'interfaccia per tutte le operazioni eseguite per conto di un'identità specificata.The mip::FileEngine in the MIP SDK File API provides an interface to all operations that are performed on behalf of a specified identity. Verrà aggiunto un motore per ogni utente che accede all'applicazione e tutte le operazioni del motore verranno eseguite nel contesto di tale identità.One engine will be added for each user that signs in to the application and all operations that engine performs will be performed in the context of that identity.

FileEngine ha due responsabilità principali: elencare le etichette per un utente autenticato e creare i gestori di file per eseguire operazioni sui file per conto dell'utente.The FileEngine has two primary responsibilities: Listing labels for an authenticated user and creating file handlers to perform file operations on behalf of the user.

  • mip::FileEngine
  • ListSensitivityLabels(): ottiene l'elenco di etichette per il motore caricato.ListSensitivityLabels(): Gets the list of labels for the loaded engine.
  • CreateFileHandler(): crea un mip::FileHandler per un flusso o un file specifico.CreateFileHandler(): Creates a mip::FileHandler for a specific file or stream.

Aggiungere un motore di fileAdd a File Engine

Come descritto in Oggetti profilo e motore, un motore può avere due stati: CREATED o LOADED.As covered in Profile and Engine objects, an engine can have two states - CREATED or LOADED. Se non è in uno di questi due stati, non esiste.If it's not one of those two states, it doesn't exist. Per creare e caricare uno stato, è necessario eseguire una singola chiamata a FileProfile::LoadAsync.To both create and load a state, it's only necessary to make a single call to FileProfile::LoadAsync. Se il motore esiste già nello stato memorizzato nella cache, sarà LOADED.If the engine already exists in the cached state, it will be LOADED. Se non esiste, sarà CREATED e LOADED.If it doesn't exist, it will be CREATED and LOADED. CREATED implica che l'applicazione ha tutte le informazioni dal servizio necessarie per caricare il motore.CREATED implies that the application has all of the information from the service needed to load the engine. LOADED implica che tutte le strutture di dati necessarie per sfruttare il motore sono state create in memoria.LOADED implies that all of the data structures necessary to leverage the engine have been created in memory.

Creare le impostazioni del motore di fileCreate File Engine Settings

Analogamente a un profilo, anche per il motore è necessario un oggetto impostazioni, mip::FileEngine::Settings.Similar to a profile, the engine also requires a settings object, mip::FileEngine::Settings. Questo oggetto archivia l'identificatore univoco del motore, mip::AuthDelegate il implemenatation, i dati client personalizzabili che possono essere usati per il debug o la telemetria e, facoltativamente, le impostazioni locali.This object stores the unique engine identifier, the mip::AuthDelegate implemenatation, customizable client data that can be used for debugging or telemetry, and, optionally, the locale.

Qui viene creato un FileEngine::Settings oggetto denominato engineSettings usando l'identità dell'utente dell'applicazione.Here we create a FileEngine::Settings object called engineSettings using the identity of the application user.

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.

Valido anche per fornire un ID del motore personalizzato:Also valid is providing a custom engine ID:

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 tale da consentire di collegare il motore con facilità all'utente associato.As a best practice, the first parameter, id, should be something that allows the engine to be easily connected to the associated user. Elementi come l'indirizzo di posta elettronica, il nome dell'entità utente o un GUID dell'oggetto AAD potrebbero garantire che l'ID sia univoco e possa essere caricato dallo stato locale senza chiamare il servizio.Something like email address, UPN, or AAD object GUID would ensure that the ID is both unique and can be loaded from local state without calling the service.

Aggiungere il motore di fileAdd the File Engine

Per aggiungere il motore, si tornerà al modello promise/future usato per caricare il profilo.To add the engine, we'll go back to the promise/future pattern used to load the profile. Invece di creare la promessa per mip::FileProfile, questa viene creata con mip::FileEngine.Rather than creating the promise for mip::FileProfile, it's created using 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 è l'aggiunta al profilo del motore per l'utente autenticato.The end result of the code above is that the engine for the authenticated user will be added to the profile.

Elencare le etichette di riservatezzaList Sensitivity Labels

Tramite il motore aggiunto è ora possibile elencare tutte le etichette di riservatezza disponibili per l'utente autenticato chiamando engine->ListSensitivityLabels().Using the added engine, it's now possible to list all of the sensitivity labels available to the authenticated user by calling engine->ListSensitivityLabels().

ListSensitivityLabels() recupererà l'elenco di etichette e degli attributi di tali etichette per un utente specifico dal servizio.ListSensitivityLabels() will fetch the list of labels and attributes of those labels for a specific user from the service. Il risultato viene archiviato in un vettore di std::shared_ptr<mip::Label>.The result is stored in a vector of std::shared_ptr<mip::Label>.

Qui sono disponibili altre informazioni su mip::Label.Read more here on mip::Label.

ListSensitivityLabels()ListSensitivityLabels()

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

Oppure, in forma semplificata:Or, simplified:

auto labels = engine->ListSensitivityLabels();

La stampa dei nomi è un modo semplice per mostrare che è stato eseguito correttamente il pull dei criteri dal servizio e si è riusciti a ottenere le etichette.Printing the names is an easy way to show that we successfully pulled policy from the service and were able to get the labels. Per applicare l'etichetta, è necessario l'identificatore dell'etichetta.To apply the label, the label identifier is required. Il codice seguente esegue l'iterazione di tutte le etichette, visualizzando name e id per ogni etichetta padre e figlio.The code below iterates through all labels, displaying the name and the id for each parent and child label.

//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 restituita da GetSensitivityLabels() può essere usata per visualizzare tutte le etichette disponibili per l'utente e quindi, se selezionata, per usare l'ID per applicare le etichette a un file.The collection of mip::Label returned by GetSensitivityLabels() can be used to display all labels available to the user and then, when selected, use the ID to apply labels to a file.

Passaggi successiviNext Steps

Ora che il profilo è caricato, il motore è stato aggiunto e sono disponibili etichette, è possibile aggiungere un gestore per iniziare a leggere, scrivere o rimuovere le etichette dai file.Now that the profile is loaded, the engine added, and we have labels, we can add a handler to begin to read, write, or remove labels from files. Vedere Gestori di file in MIP SDK.See File handlers in the MIP SDK.