SDK de Microsoft Information Protection: conceptos del controlador de archivos

En el SDK de archivos MIP, mip::FileHandler expone las operaciones que leen y escriben etiquetas o protección en distintos tipos de archivo con soporte integrado.

Tipos de archivo compatibles

  • Formatos de archivo de Office basados en OPC (Office 2010 y versiones posteriores)
  • Formatos de archivo de Office heredados (Office 2007)
  • PDF
  • Soporte genérico de PFILE
  • Archivos que admiten Adobe XMP

Funciones del controlador de archivos

mip::FileHandler expone métodos para leer, escribir y eliminar tanto etiquetas como información de protección. Para obtener la lista completa, consulte la referencia de API.

En este artículo se describen los métodos siguientes:

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

Requisitos

Para crear un FileHandler para trabajar con un archivo específico, proporcione:

  • Una operación FileProfile
  • Un FileEngine añadido a FileProfile
  • Una clase que herede mip::FileHandler::Observer

Creación de un controlador de archivos

El primer paso para administrar archivos en el SDK de archivos es crear un FileHandler objeto . Esta clase incluye la funcionalidad necesaria para obtener, establecer, actualizar, eliminar y confirmar los cambios de etiqueta en los archivos.

Cree el FileHandler llamando a la función CreateFileHandlerAsync de FileEngine mediante el patrón promesa/futuro.

CreateFileHandlerAsync acepta los parámetros siguientes: la ruta de acceso al archivo que se va a leer o modificar, la ruta de acceso que se va a usar para los informes de auditoría, una marca que habilita la detección de auditorías, la mip::FileHandler::Observer para las notificaciones de eventos asincrónicas y la promesa de FileHandler.

Note

Implemente la mip::FileHandler::Observer clase en una clase derivada porque CreateFileHandler requiere el Observer objeto .

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();

Después de crear el FileHandler objeto, puede realizar operaciones de archivo (get/set/delete/commit).

Leer una etiqueta

Requisitos de metadatos

Leer correctamente los metadatos de un archivo y traducirlos en algo que las aplicaciones pueden usar tienen algunos requisitos.

  • La etiqueta que se lee debe seguir existiendo en el servicio de Microsoft 365. Si alguien eliminó la etiqueta, el SDK no puede obtener información sobre esa etiqueta y devuelve un error.
  • Los metadatos del archivo deben estar intactos. Los metadatos incluyen:
    • Atributo1
    • Attribute2

GetLabel()

Después de crear el controlador que apunta a un archivo específico, lea la etiqueta de forma sincrónica llamando a fileHandler->GetLabel(). El método devuelve un mip::ContentLabel objeto que contiene toda la información sobre la etiqueta aplicada.

auto label = fileHandler->GetLabel();

Puede leer los datos de etiqueta del label objeto y pasarlos a cualquier otro componente o funcionalidad de la aplicación.

Definición de una etiqueta

Establecer una etiqueta es un proceso de dos partes. Después de crear un controlador que apunte al archivo en cuestión, establezca la etiqueta llamando a FileHandler->SetLabel() con algunos parámetros: mip::Label, mip::LabelingOptionsy mip::ProtectionOptions. En primer lugar, resuelva el identificador de etiqueta en una etiqueta y, a continuación, defina las opciones de etiquetado.

Resolución del id. de etiqueta en mip::Label

El primer parámetro de la función SetLabel es mip::Label. A menudo, la aplicación funciona con identificadores de etiqueta en lugar de etiquetas. Resuelva el identificador de etiqueta a mip::Label llamando a GetLabelById en el motor de archivo o de directivas:

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

Opciones de etiquetado

El segundo parámetro necesario para definir la etiqueta es mip::LabelingOptions.

LabelingOptions proporciona más información sobre la etiqueta, como AssignmentMethod y la justificación de una acción.

  • mip::AssignmentMethod es un enumerador que tiene tres valores: STANDARD, PRIVILEGED o AUTO. Revise la referencia mip::AssignmentMethod para obtener más detalles.
  • Proporcione justificación solo si la directiva de servicio la requiere y al reducir la confidencialidad existente de un archivo.

En este fragmento de código se muestra cómo crear el mip::LabelingOptions objeto y establecer la justificación y el mensaje de degradación.

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

Configuración de la protección

Es posible que algunas aplicaciones necesiten realizar operaciones en nombre de una identidad de usuario delegada. La mip::ProtectionSettings clase permite a la aplicación definir la identidad delegada por controlador. Anteriormente, las clases del motor realizaban la delegación. Ese diseño tenía desventajas significativas en la sobrecarga de la aplicación y los recorridos de ida y vuelta de servicio. Mover la configuración del usuario delegado a mip::ProtectionSettings y convertirlos en parte de la clase de controlador elimina esta sobrecarga, lo que mejora el rendimiento de las aplicaciones que realizan muchas operaciones en nombre de diversos conjuntos de identidades de usuario.

Si no necesita delegación, pase mip::ProtectionSettings() a la función SetLabel. Si necesita delegación, cree un mip::ProtectionSettings objeto y establezca la dirección de correo delegada:

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

Configurar la etiqueta

Después de recuperar mip::Label mediante el identificador, establecer las opciones de etiquetado y, opcionalmente, configurar la protección, puede asignar la etiqueta al controlador.

Si no estableció la configuración de protección, establezca la etiqueta llamando SetLabel en el controlador:

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

Si necesita la configuración de protección para realizar una operación delegada, use:

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

Después de establecer la etiqueta en el archivo al que hace referencia el controlador, confirme el cambio y escriba un archivo en el disco o cree un flujo de salida.

Realizar cambios

El último paso para confirmar cualquier cambio en un archivo en el SDK de MIP es confirmar el cambio. Mediante la función FileHandler->CommitAsync().

Para implementar la función de compromiso, devuelva una promesa o un futuro, creando una promesa para un bool. La CommitAsync() función devuelve true si la operación se realizó correctamente o false si se produjo un error por algún motivo.

Después de crear promise y future, llama a CommitAsync() y proporciona dos parámetros: la ruta del archivo de salida (std::string) y la promesa. Por último, obtenga el resultado obteniendo el valor del future objeto .

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

Importante

El FileHandler no actualizará ni sobrescribirá los archivos existentes. Debe implementar un reemplazo para el archivo que está etiquetando.

Si escribe una etiqueta en FileA.docx, CommitAsync() crea una copia del archivo, FileB.docx, con la etiqueta aplicada. Escriba código para quitar o cambiar el nombre deFileA.docx y cambiar el nombre deFileB.docx.

Eliminación de una etiqueta

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);

Eliminación de la protección

Compruebe que el usuario tiene derechos para quitar la protección del archivo al que se accede. Realice una comprobación de acceso antes de quitar la protección.

La RemoveProtection() función se comporta de forma similar a SetLabel() o DeleteLabel(). Llame al método en el objeto existente FileHandler y confirme el cambio.

Importante

Como desarrollador de aplicaciones, es responsabilidad suya realizar esta comprobación de acceso. Si no se realiza correctamente la comprobación de acceso, se pueden producir pérdidas de datos.

Ejemplo de 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.");
    }
}

Ejemplo de .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.");
    }
}

Pasos siguientes

  • Last updated on