Microsoft Information Protection SDK - conceitos de gestor de ficheiros

No MIP File SDK, mip::FileHandler expõe as operações que leem e escrevem etiquetas ou proteção entre tipos de ficheiros com suporte incorporado.

Tipos de ficheiro suportados

• Formatos de ficheiros Office baseados em OPC (Office 2010 e posteriores)
• Formatos de ficheiro Office legados (Office 2007)
• PDF
• Suporte genérico a PFILE
• Arquivos compatíveis com o Adobe XMP

Funções do manipulador de arquivos

mip::FileHandler expõe métodos de leitura, escrita e remoção de rótulos e informações de proteção. Para obter a lista completa, consulte a referência da API.

Este artigo aborda os seguintes métodos:

• GetLabelAsync()
• SetLabel()
• DeleteLabel()
• RemoveProtection()
• CommitAsync()

Requisitos

Para criar um FileHandler para trabalhar com um ficheiro específico, forneça:

• Uma FileProfile
• O FileEngine adicionado ao FileProfile
• Uma classe que herda mip::FileHandler::Observer

Criar um manipulador de arquivos

O primeiro passo na gestão de ficheiros no File SDK é criar um FileHandler objeto. Esta classe inclui a funcionalidade necessária para obter, definir, atualizar, eliminar e confirmar alterações aos rótulos dos ficheiros.

Crie o FileHandler chamando a função CreateFileHandlerAsync de FileEngine, utilizando o padrão promise/future.

CreateFileHandlerAsync aceita três parâmetros: o caminho para o ficheiro para ler ou modificar, o mip::FileHandler::Observer para notificações de eventos assíncronos, e a promessa para o FileHandler.

Note

Implemente a mip::FileHandler::Observer classe numa classe derivada porque CreateFileHandler requer o Observer objeto.

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

Depois de criares o objeto FileHandler, podes realizar operações em ficheiros (get/set/delete/commit).

Ler uma etiqueta

Requisitos em matéria de metadados

Ler com sucesso metadados de um ficheiro e traduzi-los em algo que as aplicações possam usar tem alguns requisitos.

• O rótulo que está sendo lido ainda deve existir no serviço Microsoft 365. Se alguém apagou a etiqueta, o SDK não obtém informações sobre essa etiqueta e devolve um erro.
• Os metadados do arquivo devem estar intactos. Estes metadados incluem:
  • Atributo1
  • Atributo2

GetLabelAsync()

Depois de criares o processador que aponta para um ficheiro específico, volta a recorrer ao padrão promise/future para ler o rótulo de forma assíncrona. A promessa é para um mip::ContentLabel objeto que contém todas as informações sobre o rótulo aplicado.

Depois de instanciares os objetos promise e future, lê o rótulo chamando fileHandler->GetLabelAsync() e fornecendo promise como único parâmetro. Finalmente, armazene a etiqueta num mip::ContentLabel objeto que obtém do future.

auto loadPromise = std::make_shared<std::promise<std::shared_ptr<mip::ContentLabel>>>();
auto loadFuture = loadPromise->get_future();
fileHandler->GetLabelAsync(loadPromise);
auto label = loadFuture.get();

Pode ler dados de etiquetas do label objeto e passá-los para qualquer outro componente ou funcionalidade da aplicação.

---

Definir um rótulo

Definir um rótulo é um processo em duas partes. Depois de criar um handler que aponte para o ficheiro em questão, defina a etiqueta chamando FileHandler->SetLabel() com alguns parâmetros: mip::Label, mip::LabelingOptions, e mip::ProtectionOptions. Primeiro, converta o ID do rótulo num rótulo e, em seguida, defina as opções de rotulagem.

Resolver ID de etiqueta para mip::Label

O primeiro parâmetro da função SetLabel é um mip::Label. Muitas vezes, a aplicação funciona com identificadores de etiquetas em vez de etiquetas. Resolva o identificador do rótulo como mip::Label ao chamar GetLabelById no motor de ficheiros ou de políticas:

mip::Label label = mEngine->GetLabelById(labelId);

Opções de rotulagem

O segundo parâmetro necessário para definir o rótulo é mip::LabelingOptions.

LabelingOptions fornece mais informações sobre o rótulo, como a AssignmentMethod e a justificação de uma ação.

• mip::AssignmentMethod é um enumerador que tem três valores: STANDARD, PRIVILEGED, ou AUTO. Analise a mip::AssignmentMethod referência para obter mais detalhes.
• Fornecer justificação apenas se a política de serviço assim o exigir e ao reduzir a sensibilidade existente de um ficheiro.

Este excerto demonstra como criar o mip::LabelingOptions objeto e definir a justificação e a mensagem de downgrade.

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

Configurações de proteção

Algumas aplicações podem precisar de realizar operações em nome de uma identidade de utilizador delegada. A mip::ProtectionSettings classe permite que a aplicação defina a identidade delegada por handler. Anteriormente, as classes de locomotivas realizavam a delegação. Esse design apresentava desvantagens significativas em termos de sobrecarga da aplicação e de idas e voltas ao serviço. Mover as definições de utilizador delegadas para mip::ProtectionSettings e torná-las parte da classe handler elimina esta sobrecarga, o que melhora o desempenho para aplicações que realizam muitas operações em nome de conjuntos diversos de identidades de utilizador.

Se não precisares de delegar, passa mip::ProtectionSettings() para a função SetLabel . Se precisar de delegação, crie um mip::ProtectionSettings objeto e defina o endereço de email delegado:

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

Definir o rótulo

Depois de buscares mip::Label usando o ID, definires as opções de rotulagem e, opcionalmente, definires as definições de proteção, podes definir a etiqueta no handler.

Caso não tenhas definido as definições de proteção, define a etiqueta chamando SetLabel no manipulador.

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

Se precisar de definições de proteção para realizar uma operação delegada, utilize:

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

Depois de definires o rótulo no ficheiro ao qual o manipulador faz referência, confirma a alteração e escreve um ficheiro em disco ou cria um fluxo de saída.

Confirmar alterações

A etapa final para confirmar qualquer alteração em um arquivo no MIP SDK é confirmar a alteração. Use a função FileHandler->CommitAsync().

Para implementar a função de compromisso, regresse à promessa/futuro, criando uma promessa para um bool. A CommitAsync() função responde verdadeira se a operação teve sucesso ou falsa se falhou por qualquer motivo.

Depois de criar o promise e future, chamar CommitAsync() e fornecer dois parâmetros: o caminho do ficheiro de saída (std::string) e a promessa. Por fim, obtenha o resultado ao obter o valor do future objeto.

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

Importante

O FileHandler não atualizará nem substituirá ficheiros existentes. Tens de implementar a substituição do ficheiro que estás a rotular.

Se escrever uma etiqueta para FileA.docx, CommitAsync() cria uma cópia do ficheiro, FileB.docx, com a etiqueta aplicada. Escreva código para remover ou mudar o nome de FileA.docx e mudar o nome de FileB.docx.

---

Eliminar uma etiqueta

auto fileHandler = mEngine->CreateFileHandler(filePath, std::make_shared<FileHandlerObserverImpl>());
fileHandler->DeleteLabel(mip::AssignmentMethod::PRIVILEGED, "Label unnecessary.");
auto commitPromise = std::make_shared<std::promise<bool>>();
auto commitFuture = commitPromise->get_future();
fileHandler->CommitAsync(outputFile, commitPromise);

Remover proteção

Valide que o utilizador tem direitos para remover a proteção do ficheiro acedido. Faça uma verificação de acesso antes de remover a proteção.

A RemoveProtection() função comporta-se de forma semelhante a SetLabel() ou DeleteLabel(). Chame o método no objeto FileHandler existente e, em seguida, confirme a alteração.

Importante

Como programador da aplicação, é sua responsabilidade realizar esta verificação de acesso. A falha em realizar corretamente a verificação de acesso pode resultar em fuga de dados.

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

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

Passos seguintes

• Explora o exemplo do MIP File SDK C++ no GitHub.