Microsoft Proteção de Informações SDK – conceitos do manipulador de arquivos

No SDK de Arquivos do MIP, mip::FileHandler expõe as operações que leem e gravam rótulos ou proteção em tipos de arquivo com suporte interno.

Tipos de arquivo compatíveis

  • Formatos de arquivo do Office com base no OPC (Office 2010 e posterior)
  • Formatos de arquivo herdados do Office (Office 2007)
  • PDF
  • Suporte a PFILE genérico
  • Arquivos compatíveis com Adobe XMP

Funções do manipulador de arquivos

mip::FileHandler expõe métodos para ler, gravar e remover rótulos e informações de proteção. Para obter a lista completa, consulte a Referência de API.

Este artigo aborda os seguintes métodos:

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

Requisitos

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

Criar um manipulador de arquivo

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

Crie a FileHandler chamando a função CreateFileHandlerAsync de FileEngine usando o padrão promessa/futuro.

CreateFileHandlerAsync aceita os seguintes parâmetros: o caminho para o arquivo a ser lido ou modificado, o caminho a ser usado para a geração de relatórios de auditoria, um sinalizador que habilita a descoberta de auditoria, o mip::FileHandler::Observer para notificações de eventos assíncronas e a promise para o FileHandler.

Note

Implemente a mip::FileHandler::Observer classe em uma 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, filePath, true, std::make_shared<FileHandlerObserver>(), createFileHandlerPromise);
auto fileHandler = createFileHandlerFuture.get();

Depois de criar o FileHandler objeto, você pode executar operações de arquivo (get/set/delete/commit).

Ler um rótulo

Requisitos de metadados

Ler metadados com êxito de um arquivo e traduzi-los para algo que os aplicativos podem usar tem alguns requisitos.

  • O rótulo que está sendo lido ainda deve existir no serviço do Microsoft 365. Se alguém excluiu o rótulo, o SDK não obtém informações sobre esse rótulo e retorna um erro.
  • Os metadados do arquivo devem estar intactos. Esses metadados incluem:
    • Atributo1
    • Attribute2

GetLabel()

Depois de criar o manipulador que aponta para um arquivo específico, leia o rótulo de forma síncrona chamando fileHandler->GetLabel(). O método retorna um mip::ContentLabel objeto que contém todas as informações sobre o rótulo aplicado.

auto label = fileHandler->GetLabel();

Você pode ler dados de rótulo do label objeto e passá-los para qualquer outro componente ou funcionalidade no aplicativo.

Definir um rótulo

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

Resolver ID do rótulo para mip::Label

O primeiro parâmetro da função SetLabel é um mip::Label. Geralmente, o aplicativo funciona com identificadores de rótulo em vez de rótulos. Resolva o identificador do rótulo no mip::Label chamando GetLabelById no mecanismo de arquivo ou política:

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

Opções de rotulagem

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

LabelingOptions especifica mais informações sobre o rótulo, como AssignmentMethod e a justificativa para uma ação.

  • mip::AssignmentMethod é um enumerador que tem três valores: STANDARD, PRIVILEGED ou AUTO. Revise a referência mip::AssignmentMethod para obter mais detalhes.
  • Forneça justificativa somente se a política de serviço exigir e ao reduzir a sensibilidade existente de um arquivo.

Este snippet demonstra como criar o mip::LabelingOptions objeto e definir a justificativa 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

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, as classes do mecanismo realizavam a delegação. Esse design teve desvantagens significativas na sobrecarga do aplicativo e nas viagens de ida e volta do serviço. Mover as configurações de usuário delegadas para mip::ProtectionSettings e torná-las parte da classe de manipulador elimina essa sobrecarga, o que melhora o desempenho de aplicativos que executam muitas operações em nome de diversos conjuntos de identidades de usuário.

Se você não precisar de delegação, passe mip::ProtectionSettings() para a função SetLabel. Se você 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 buscar mip::Label usando a ID, defina as opções de rotulagem e, opcionalmente, defina as configurações de proteção, você pode definir o rótulo no manipulador.

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

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

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

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

Depois de definir o rótulo no arquivo que o manipulador faz referência, confirme a alteração e escreva um arquivo no disco ou crie um fluxo de saída.

Cometer alterações

A etapa final para confirmar uma alteração em um arquivo no SDK da PIM é confirmar a alteração. Usando a função FileHandler->CommitAsync().

Para implementar a função de confirmação, volte à promessa/futuro, criando uma promessa para um bool. A CommitAsync() função retornará true se a operação tiver sido bem-sucedida ou falsa se tiver falhado por algum motivo.

Depois de criar o promise e o future, chame CommitAsync() e forneça dois parâmetros: o caminho do arquivo de saída (std::string) e a promessa. Por fim, obtenha o resultado 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

Os FileHandler arquivos existentes não serão atualizados ou substituídos. Você deve implementar a substituição no arquivo que está rotulando.

Se você escrever um rótulo paraFileA.docx, CommitAsync() criará uma cópia do arquivo, FileB.docx, com o rótulo aplicado. Escreva o código para remover ou renomear FileA.docx e renomear FileB.docx.

Excluir um rótulo

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

Remover proteção

Valide se o usuário tem direitos para remover a proteção do arquivo que está sendo acessado. Execute uma verificação de acesso antes de remover a proteção.

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

Importante

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

Próximas Etapas 

  • Last updated on