Partilhar via

SDK da Proteção de Informações da Microsoft - Conceitos de manipulador de arquivos

  • Artigo

No MIP File SDK, o expõe todas as várias operações que podem ser usadas para ler e gravar rótulos, ou proteção, em um conjunto de tipos de arquivo para os quais o mip::FileHandler suporte é interno.

Tipos de ficheiro suportados

  • Formatos de arquivo do Office baseados em OPC (Office 2010 e posterior)
  • Formatos de arquivo herdados do Office (Office 2007)
  • PDF
  • Suporte a PFILE genérico
  • 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.

Neste artigo, os seguintes métodos serão abordados:

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

Requisitos

Criar um FileHandler para trabalhar com um arquivo específico requer:

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

Criar um manipulador de arquivos

A primeira etapa necessária no gerenciamento de quaisquer arquivos no File SDK é criar um FileHandler objeto. Essa classe implementa toda a funcionalidade necessária para obter, definir, atualizar, excluir e confirmar alterações de rótulo em arquivos.

Criar o FileHandler é tão fácil quanto chamar a FileEnginefunção do usando o padrão promessa CreateFileHandlerAsync /futuro.

CreateFileHandlerAsync aceita três parâmetros: o caminho para o arquivo que deve ser lido ou modificado, o para notificações de eventos assíncronos mip::FileHandler::Observer e a promessa para o FileHandler.

Nota: A mip::FileHandler::Observer classe deve ser implementada em uma classe derivada conforme 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 criar o objeto com êxito, as FileHandler operações de arquivo (get/set/delete/commit) podem ser executadas.

Ler um rótulo

Requisitos em matéria de metadados

Existem alguns requisitos para ler com êxito metadados de um arquivo e traduzi-los em algo que possa ser usado em aplicativos.

  • O rótulo que está sendo lido ainda deve existir no serviço Microsoft 365. Se tiver sido totalmente excluído, o SDK não conseguirá obter informações sobre esse rótulo e retornará um erro.
  • Os metadados do arquivo devem estar intactos. Estes metadados incluem:
    • Atributo1
    • Atributo2

GetLabelAsync()

Depois de criar o manipulador para apontar para um arquivo específico, retornamos 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 instanciar os promise objetos e future , lemos o rótulo chamando fileHandler->GetLabelAsync() e fornecendo o promise parâmetro como o solitário. Finalmente, a etiqueta pode ser armazenada em um mip::ContentLabel objeto que obteremos 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();

Os dados do rótulo podem ser lidos do objeto e passados label para qualquer outro componente ou funcionalidade no aplicativo.

Definir um rótulo

A definição de um rótulo é um processo em duas partes. Primeiro, tendo criado um manipulador que aponta para o arquivo em questão, o rótulo pode ser definido chamando FileHandler->SetLabel() com alguns parâmetros: mip::Label, mip::LabelingOptions, e mip::ProtectionOptions. Primeiro, devemos resolver o ID do rótulo para um rótulo e, em seguida, definir as opções de rotulagem.

Resolver ID de rótulo para mip::Label

O primeiro parâmetro da função SetLabel é um mip::Labelarquivo . Muitas vezes, o aplicativo está trabalhando com identificadores de rótulo em vez de rótulos. O identificador de rótulo pode ser resolvido chamando mip::Label GetLabelById no mecanismo de arquivo ou política:

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

Opções de rotulagem

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

LabelingOptions especifica informações adicionais sobre o rótulo, como a e justificação AssignmentMethod 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.
  • A justificação só é necessária se a política de serviço o exigir e quando se reduz a sensibilidade existente de um ficheiro.

Este trecho demonstra a criação do objeto e a definição da justificativa e da mip::LabelingOptions 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

Alguns aplicativos podem precisar executar operações em nome de uma identidade de usuário delegada. A mip::ProtectionSettings classe permite que o aplicativo defina a identidade delegada por manipulador. Anteriormente, a delegação era realizada pelas classes de motores. Isso teve desvantagens significativas nas despesas gerais de aplicação e nas viagens de ida e volta de serviço. Ao mover as configurações de usuário delegado e mip::ProtectionSettings torná-las parte da classe do manipulador, eliminamos essa sobrecarga, resultando em melhor desempenho para aplicativos que estão executando muitas operações em nome de diversos conjuntos de identidades de usuário.

Se a delegação não for necessária, passe mip::ProtectionSettings() para a função SetLabel . Se a delegação for necessária, ela pode ser obtida criando um mip::ProtectionSettings objeto e definindo o endereço de email delegado:

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

Definir o rótulo

Depois de buscar o mip::Label usando o ID, definir as opções de rotulagem e, opcionalmente, definir as configurações de proteção, o rótulo agora pode ser definido no manipulador.

Se você não definiu as configurações de proteção, defina o rótulo chamando SetLabel o manipulador:

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

Se você precisou de configurações de proteção para executar uma operação delegada, então:

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

Tendo agora definido o rótulo no arquivo referenciado pelo manipulador, ainda há mais uma etapa para confirmar a alteração e gravar um arquivo no disco ou criar um fluxo de saída.

Consolidar alterações

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

Para implementar a função de compromisso, voltamos à promessa/futuro, criando uma promessa para um bool. A CommitAsync() função retornará true se a operação for bem-sucedida ou false se falhar por qualquer motivo.

Depois de criar o promise e future, CommitAsync() é chamado e dois parâmetros fornecidos: O caminho do arquivo de saída (std::string) e a promessa. Por fim, o resultado é obtido obtendo 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á ou substituirá arquivos existentes. Cabe ao desenvolvedor implementar a substituição do arquivo que está sendo rotulado.

Se escrever um rótulo para FileA.docx, uma cópia do arquivo, FileB.docx, será criada com o rótulo aplicado. O código deve ser escrito para remover/renomear FileA.docx e renomear 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

Seu aplicativo MIP File SDK deve validar que o usuário tem direitos para remover a proteção do arquivo que está sendo acessado. Isso pode ser feito executando uma verificação de acesso antes de remover a proteção.

A RemoveProtection() função se comporta de maneira semelhante a SetLabel() ou DeleteLabel(). O método é chamado no objeto existente FileHandler , então a alteração deve ser confirmada.

Importante

Como desenvolvedor de aplicativos, é sua responsabilidade executar essa verificação de acesso. A falha em executar corretamente a verificação de acesso pode reuslt em vazamento 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.");
    }
}