Microsoft Information Protection SDK - Konzepte der File SDK-Engine

Das mip::FileEngine im MIP File SDK stellt eine Schnittstelle zu allen Vorgängen bereit, die im Auftrag einer angegebenen Identität ausgeführt werden. Fügen Sie für jeden Benutzer, der sich in der Anwendung anmeldet, eine Engine hinzu. Die Engine führt alle Vorgänge im Kontext dieser Identität aus.

Das FileEngine hat zwei Hauptaufgaben: das Auflisten von Labels für einen authentifizierten Benutzer und das Erstellen von Datei-Handlern, um Dateivorgänge im Auftrag des Benutzers auszuführen.

  • mip::FileEngine
  • ListSensitivityLabels(): Ruft die Liste der Bezeichnungen für die geladene Engine ab.
  • CreateFileHandler(): Erstellt eine mip::FileHandler für eine bestimmte Datei oder einen bestimmten Datenstrom.

Datei-Engine hinzufügen

Wie in Profile- und Modulobjekten behandelt, kann ein Modul zwei Zustände aufweisen – CREATED oder LOADED. Wenn es sich nicht um einen dieser beiden Zustände handelt, ist sie nicht vorhanden. Um einen Zustand zu erstellen und zu laden, führen Sie einen einzelnen Aufruf durch FileProfile::LoadAsync. Wenn die Engine bereits im Cache vorhanden ist, ist sie LOADED. Wenn es nicht existiert, ist es CREATED und LOADED. CREATED bedeutet, dass die Anwendung über alle Informationen aus dem Dienst verfügt, die zum Laden der Engine erforderlich sind. LOADED bedeutet, dass alle Datenstrukturen, die für die Verwendung des Moduls erforderlich sind, im Arbeitsspeicher vorhanden sind.

Datei-Engine-Einstellungen erstellen

Ähnlich wie bei einem Profil erfordert die Engine auch ein Einstellungsobjekt, mip::FileEngine::Settings. Dieses Objekt speichert den eindeutigen Modulbezeichner, die mip::AuthDelegate Implementierung, anpassbare Clientdaten für das Debuggen oder Telemetrie sowie optional das Gebietsschema.

Hier erstellen wir ein FileEngine::Settings Objekt namens engineSettings unter Verwendung der Identität des Anwendungsbenutzers.

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.

Wenn Sie engineSettings auf diese Weise erstellen, legen Sie auch explizit eine eindeutige engineId fest:

engineSettings.SetEngineId(engineId);

Durch die Verwendung des Benutzernamens oder der E-Mail wird sichergestellt, dass dasselbe Modul jedes Mal geladen wird, wenn der Benutzer den Dienst oder die Anwendung verwendet.

Auch gültig ist die Bereitstellung einer benutzerdefinierten Modul-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.

Verwenden Sie als bewährte Methode einen ersten Parameter, idder das Modul mit dem zugehörigen Benutzer verbindet. Eine E-Mail-Adresse, ein UPN oder Microsoft Entra Objekt-GUID stellt sicher, dass die ID eindeutig ist und vom lokalen Zustand geladen werden kann, ohne den Dienst aufzurufen.

Datei-Engine hinzufügen

Um die Engine hinzuzufügen, greifen Sie wieder auf das Promise/Future-Muster zurück, das zum Laden des Profils verwendet wird. Anstatt das Promise für mip::FileProfile zu erstellen, erstellen Sie es mit 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();

Der Code fügt dem Profil die Engine für den authentifizierten Benutzer hinzu.

Sensibilitätsbezeichnungen auflisten

Mithilfe des hinzugefügten Moduls können Sie alle Vertraulichkeitsbezeichnungen auflisten, die dem authentifizierten Benutzer durch Aufrufen engine->ListSensitivityLabels()zur Verfügung stehen.

ListSensitivityLabels() Ruft die Liste der Bezeichnungen und Attribute dieser Bezeichnungen für einen bestimmten Benutzer aus dem Dienst ab. Das Ergebnis wird in einem Vektor von std::shared_ptr<mip::Label> gespeichert.

Weitere Informationen finden Sie in der mip::Label Klassenreferenz.

ListSensitivityLabels()

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

Oder, vereinfacht:

auto labels = engine->ListSensitivityLabels();

Das Drucken der Namen zeigt, dass die Anwendung die Richtlinie erfolgreich aus dem Dienst abgerufen und die Bezeichnungen erhalten hat. Um das Label anzuwenden, benötigen Sie die Labelkennung. Der folgende Code durchläuft alle Beschriftungen und zeigt für jede über- und untergeordnete Beschriftung die name und die id an.

//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;
  }
}

Sie können die von GetSensitivityLabels() zurückgegebene Sammlung von mip::Label verwenden, um alle dem Benutzer zur Verfügung stehenden Bezeichnungen anzuzeigen und dann nach der Auswahl die ID zu verwenden, um Bezeichnungen auf eine Datei anzuwenden.

Nächste Schritte

Nachdem das Profil geladen ist, die Engine hinzugefügt wurde und Bezeichnungen verfügbar sind, können Sie einen Handler hinzufügen, um Bezeichnungen aus Dateien zu lesen, in Dateien zu schreiben oder aus Dateien zu entfernen. Weitere Informationen finden Sie unter Dateihandler im MIP SDK.

  • Last updated on