Kit de développement logiciel (SDK) Microsoft Information Protection - File des concepts de moteur du kit de développement logiciel (SDK)

Article
01/30/2024

Le mip::FileEngine dans le SDK File MIP fournit une interface pour toutes les opérations effectuées au nom d’une identité spécifiée. Un moteur sera ajouté pour chaque utilisateur qui se connecte à l’application et toutes les opérations effectuées par le moteur seront effectuées dans le contexte de cette identité.

Le FileEngine possède deux principales responsabilités : répertorier les étiquettes d’un utilisateur authentifié et créer des gestionnaires de fichiers pour effectuer des opérations de fichier pour le compte de l’utilisateur.

mip::FileEngine
ListSensitivityLabels() : obtient la liste des étiquettes pour le moteur chargé.
CreateFileHandler() : crée un mip::FileHandler pour un fichier ou un flux spécifique.

Ajouter un moteur de fichiers

Comme décrit dans objets Profile et Engine, un moteur peut avoir deux états - CREATED ou LOADED. Si ce n’est pas l’un de ces deux états, il n’existe pas. Pour créer et charger un état, un seul appel à FileProfile::LoadAsync est nécessaire. Si le moteur existe déjà dans l’état mis en cache, il sera LOADED. Si la valeur n’existe pas, elle est CREATED et LOADED. CREATED implique que l’application dispose de toutes les informations du service nécessaires pour charger le moteur. LOADED implique que toutes les structures de données nécessaires pour tirer parti du moteur aient été créées en mémoire.

Créer les paramètres du moteur de fichiers

Comme pour un profil, le moteur nécessite également un objet de paramètres, mip::FileEngine::Settings. Cet objet stocke l’identificateur de moteur unique, l’implémentation de mip::AuthDelegate, des données client personnalisables qui peuvent être utilisées pour le débogage ou la télémétrie, et, éventuellement, la locale.

Ici, nous créons un objet FileEngine::Settings appelé engineSettings à l’aide de l’identité de l’utilisateur de l’application.

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.

Lors de la création des engineSettings de cette façon, il est important de définir explicitement un engineId unique via :

engineSettings.SetEngineId(engineId);

L’utilisation du nom d’utilisateur ou de l’e-mail permet de s’assurer que le même moteur est chargé chaque fois que l’utilisateur utilise le service ou l’application.

Il est également possible de fournir un ID de moteur personnalisé :

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.

En guise de meilleure pratique, le premier paramètre, id, doit être quelque chose qui permet au moteur d’être facilement connecté à l’utilisateur associé. Quelque chose comme l’adresse e-mail, l’UPN ou le GUID d’objet AAD doit garantir que l’ID est unique et peut être chargé à partir de l’état local sans appeler le service.

Ajouter le moteur de fichiers

Pour ajouter le moteur, nous allons revenir au modèle promesse/avenir utilisé pour charger le profil. Plutôt que de créer la promesse pour mip::FileProfile, elle est créée à l’aide de 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();

Le résultat final du code ci-dessus est que le moteur de l’utilisateur authentifié sera ajouté au profil.

Répertorier les étiquettes de confidentialité

À l’aide du moteur ajouté, il est désormais possible de répertorier toutes les étiquettes de confidentialité disponibles pour l’utilisateur authentifié en appelant engine->ListSensitivityLabels().

ListSensitivityLabels() récupère la liste des étiquettes et des attributs de ces étiquettes pour un utilisateur spécifique du service. Le résultat est stocké dans un vecteur de std::shared_ptr<mip::Label>.

En savoir plus sur mip::Label ici.

ListSensitivityLabels()

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

Ou, en simplifiant :

auto labels = engine->ListSensitivityLabels();

Imprimer les étiquettes et les ID

L’impression des noms est un moyen simple de montrer que nous avons bien récupéré la stratégie depuis le service et que nous avons pu obtenir les étiquettes. L’identificateur d’étiquette est requis pour appliquer l’étiquette. Le code ci-dessous effectue une itération dans toutes les étiquettes, affichant le name et le id pour chaque étiquette parente et enfant.

//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 collection de mip::Label renvoyée par GetSensitivityLabels() peut être utilisée pour afficher toutes les étiquettes disponibles pour l’utilisateur, puis, quand elle est sélectionnée, utilisez l’ID pour appliquer des étiquettes à un fichier.

Étapes suivantes

Maintenant que le profil est chargé, que le moteur a été ajouté et que nous avons des étiquettes, nous pouvons ajouter un gestionnaire pour commencer à lire, écrire ou supprimer les étiquettes des fichiers. Consultez Gestionnaires de fichiers dans le kit de développement logiciel (SDK) MIP.

Partager via