Microsoft Information Protection SDK - Concepts relatifs au gestionnaire de fichiers

Dans le SDK de fichiers MIP, mip::FileHandler expose des opérations permettant de lire et d’écrire des étiquettes ou des paramètres de protection pour différents types de fichiers avec prise en charge intégrée.

Types de fichiers pris en charge

  • Formats de fichiers Office basés sur OPC (Office 2010 et versions ultérieures)
  • Formats de fichiers Office hérités (Office 2007)
  • PDF
  • Prise en charge générique de PFILE
  • Fichiers qui prennent en charge Adobe XMP

Fonctions du gestionnaire de fichiers

mip::FileHandler expose les méthodes de lecture, écriture et suppression des étiquettes et des informations de protection. Pour obtenir la liste complète, consultez la référence de l’API.

Cet article décrit les méthodes suivantes :

  • GetLabel()
  • SetLabel()
  • DeleteLabel()
  • RemoveProtection()
  • CommitAsync()

Spécifications

Pour créer un FileHandler afin de travailler avec un fichier spécifique, fournissez :

  • Un FileProfile
  • Un FileEngine ajouté à l’élément FileProfile
  • Une classe qui hérite de mip::FileHandler::Observer

Créer un descripteur de fichier

La première étape de la gestion des fichiers dans le Kit de développement logiciel (SDK) file consiste à créer un FileHandler objet. Cette classe inclut les fonctionnalités requises pour obtenir, définir, mettre à jour, supprimer et valider les modifications apportées aux fichiers.

Créez FileHandler en appelant la fonction CreateFileHandlerAsync de FileEngine à l’aide du modèle promesse/futur.

CreateFileHandlerAsync accepte les paramètres suivants : le chemin d’accès au fichier à lire ou à modifier, le chemin d’accès à utiliser pour la génération de rapports d’audit, un indicateur qui active la détection d’audit, le mip::FileHandler::Observer pour les notifications d’événements asynchrones, et la promesse du FileHandler.

Note

Implémentez la mip::FileHandler::Observer classe dans une classe dérivée, car CreateFileHandler nécessite l’objet Observer .

auto createFileHandlerPromise = std::make_shared<std::promise<std::shared_ptr<mip::FileHandler>>>();
auto createFileHandlerFuture = createFileHandlerPromise->get_future();
fileEngine->CreateFileHandlerAsync(filePath, filePath, true, std::make_shared<FileHandlerObserver>(), createFileHandlerPromise);
auto fileHandler = createFileHandlerFuture.get();

Après avoir créé l’objet FileHandler , vous pouvez effectuer des opérations de fichier (get/set/delete/commit).

Lire une étiquette

Exigences de métadonnées

La lecture des métadonnées à partir d’un fichier et sa traduction en quelque chose que les applications peuvent utiliser ont quelques exigences.

  • L’étiquette en cours de lecture doit toujours exister dans le service Microsoft 365. Si quelqu’un a supprimé l’étiquette, le Kit de développement logiciel (SDK) ne parvient pas à obtenir des informations sur cette étiquette et retourne une erreur.
  • Les métadonnées du fichier doivent être intactes. Ces métadonnées incluent :
    • Attribut 1
    • Attribut 2

GetLabel()

Après avoir créé le gestionnaire qui pointe vers un fichier spécifique, lisez l’étiquette de façon synchrone en appelant fileHandler->GetLabel(). La méthode retourne un mip::ContentLabel objet qui contient toutes les informations relatives à l’étiquette appliquée.

auto label = fileHandler->GetLabel();

Vous pouvez lire les données d’étiquette à partir de l’objet label et les transmettre à n’importe quel autre composant ou fonctionnalité dans l’application.

Définissez une étiquette

La définition d’une étiquette est un processus en deux parties. Après avoir créé un gestionnaire qui pointe vers le fichier en question, définissez l’étiquette en appelant FileHandler->SetLabel() avec certains paramètres : mip::Label, mip::LabelingOptionset mip::ProtectionOptions. Tout d’abord, convertissez l’ID d’étiquette en étiquette, puis définissez les options d’étiquetage.

Résoudre l’ID d’étiquette en mip::Label

Le premier paramètre de la fonction SetLabel est une mip::Label. Souvent, l’application fonctionne avec des identificateurs d’étiquette plutôt que des étiquettes. Résolvez l’identificateur d’étiquette en mip::Label en appelant GetLabelById sur le moteur de fichier ou de stratégie :

std::shared_ptr<mip::Label> label = engine->GetLabelById(labelId);

Options d’étiquetage

Le deuxième paramètre requis pour définir l’étiquette est mip::LabelingOptions.

LabelingOptions fournit davantage d’informations sur l’étiquette, telles que le AssignmentMethod et la justification d’une action.

  • mip::AssignmentMethod est un énumérateur qui a trois valeurs : STANDARD, PRIVILEGED ou AUTO. Pour plus d’informations, consultez la référence mip::AssignmentMethod.
  • Fournissez une justification uniquement si la stratégie de service l’exige et lorsque vous réduisez la sensibilité existante d’un fichier.

Cet extrait de code montre comment créer l’objet mip::LabelingOptions et définir la justification et le message de rétrogradation.

auto labelingOptions = mip::LabelingOptions(mip::AssignmentMethod::STANDARD);
labelingOptions.SetDowngradeJustification(true, "Because I made an educated decision based upon the contents of this file.");

Paramètres de protection

Certaines applications peuvent avoir besoin d’effectuer des opérations pour le compte d’une identité d’utilisateur déléguée. La mip::ProtectionSettings classe permet à l’application de définir l’identité déléguée par gestionnaire. Auparavant, les classes de moteur ont effectué la délégation. Cette conception présente des inconvénients significatifs dans la surcharge des applications et les allers-retours de service. Le déplacement des paramètres utilisateur délégués vers mip::ProtectionSettings et leur fait partie de la classe de gestionnaire élimine cette surcharge, ce qui améliore les performances des applications qui effectuent de nombreuses opérations pour le compte de divers ensembles d’identités utilisateur.

Si vous n’avez pas besoin de délégation, passez mip::ProtectionSettings() à la fonction SetLabel. Si vous avez besoin d’une délégation, créez un mip::ProtectionSettings objet et définissez l’adresse de messagerie déléguée :

mip::ProtectionSettings protectionSettings;
protectionSettings.SetDelegatedUserEmail("alice@contoso.com");

Définissez l’étiquette

Une fois que vous avez récupéré mip::Label à l’aide de l’ID, définissez les options d’étiquetage et définissez éventuellement les paramètres de protection, vous pouvez définir l’étiquette sur le gestionnaire.

Si vous n’avez pas défini les paramètres de protection, définissez l’étiquette en appelant SetLabel sur le gestionnaire :

fileHandler->SetLabel(label, labelingOptions, mip::ProtectionSettings());

Si vous avez besoin de paramètres de protection pour effectuer une opération déléguée, utilisez :

fileHandler->SetLabel(label, labelingOptions, protectionSettings);

Après avoir défini l’étiquette sur le fichier référencé par le gestionnaire, validez la modification et écrivez un fichier sur le disque ou créez un flux de sortie.

Enregistrer les modifications

La dernière étape de la validation de toute modification apportée à un fichier dans le kit de développement logiciel (SDK) MIP consiste à commiter la modification. Utiliser la fonction FileHandler->CommitAsync().

Pour mettre en œuvre la fonction d’engagement, revenir à la promesse/l’avenir, en créant une promesse pour un bool. La CommitAsync() fonction retourne true si l’opération a réussi ou false si elle a échoué pour une raison quelconque.

Après avoir créé le promise et le future, appelez CommitAsync() en fournissant deux paramètres : le chemin du fichier de sortie (std::string) et la promise. Enfin, obtenez le résultat en obtenant la valeur de l’objet future .

auto commitPromise = std::make_shared<std::promise<bool>>();
auto commitFuture = commitPromise->get_future();
fileHandler->CommitAsync(outputFile, commitPromise);
auto wasCommitted = commitFuture.get();

Important

Les FileHandler fichiers existants ne seront pas mis à jour ni remplacés. Vous devez mettre en place le remplacement pour le fichier que vous étiquetez.

Si vous écrivez une étiquette dans FileA.docx, CommitAsync() crée une copie du fichier, FileB.docx, avec l’étiquette appliquée. Écrire du code pour supprimer ou renommer FileA.docx et renommer FileB.docx.

Supprimer une étiquette

auto createFileHandlerPromise = std::make_shared<std::promise<std::shared_ptr<mip::FileHandler>>>();
auto createFileHandlerFuture = createFileHandlerPromise->get_future();
mEngine->CreateFileHandlerAsync(filePath, filePath, true, std::make_shared<FileHandlerObserver>(), createFileHandlerPromise);
auto fileHandler = createFileHandlerFuture.get();

mip::LabelingOptions labelingOptions(mip::AssignmentMethod::PRIVILEGED);
labelingOptions.SetDowngradeJustification(true, "Label unnecessary.");
fileHandler->DeleteLabel(labelingOptions);

auto commitPromise = std::make_shared<std::promise<bool>>();
auto commitFuture = commitPromise->get_future();
fileHandler->CommitAsync(outputFile, commitPromise);

Supprimer la protection

Vérifiez que l’utilisateur dispose des droits nécessaires pour supprimer la protection du fichier accessible. Effectuez une vérification d’accès avant de supprimer la protection.

La RemoveProtection() fonction se comporte de la même façon que SetLabel() ou DeleteLabel(). Appelez la méthode sur l’objet existant FileHandler , puis validez la modification.

Important

En tant que développeur d’applications, il vous incombe d’effectuer cette vérification d’accès. L’échec de l’exécution correcte de la vérification d’accès peut entraîner une fuite de données.

Exemple en code C++ :

// Validate that the file referred to by the FileHandler is protected.
if (fileHandler->GetProtection() != nullptr)
{
    // Validate that user is allowed to remove protection.
    if (fileHandler->GetProtection()->AccessCheck(mip::rights::Export()) || fileHandler->GetProtection()->AccessCheck(mip::rights::Owner()))
    {
        auto commitPromise = std::make_shared<std::promise<bool>>();
        auto commitFuture = commitPromise->get_future();
        // Remove protection and commit changes to file.
        fileHandler->RemoveProtection();
        fileHandler->CommitAsync(outputFile, commitPromise);
        result = commitFuture.get();
    }
    else
    {
        // Throw an exception if the user doesn't have rights to remove protection.
        throw std::runtime_error("User doesn't have EXPORT or OWNER right.");
    }
}

Exemple .NET :

if(handler.Protection != null)
{
    // Validate that user has rights to remove protection from the file.
    if(handler.Protection.AccessCheck(Rights.Export) || handler.Protection.AccessCheck(Rights.Owner))
    {
        // If user has Extract right, remove protection and commit the change. Otherwise, throw exception.
        handler.RemoveProtection();
        bool result = handler.CommitAsync(outputPath).GetAwaiter().GetResult();
        return result;
    }
    else
    {
        throw new Microsoft.InformationProtection.Exceptions.AccessDeniedException("User lacks EXPORT right.");
    }
}

Étapes suivantes

  • Last updated on