Gerenciar rótulos de confidencialidade em Suplementos do Office

A colaboração no local de trabalho geralmente se estende além de uma organização para parceiros externos. O compartilhamento de informações fora da rede de uma organização requer medidas para evitar a perda de dados e impor políticas de conformidade. A Proteção de Informações do Microsoft Purview fornece soluções para classificar e proteger informações confidenciais. Os rótulos de confidencialidade aplicam essa proteção a dados no Excel, no Outlook, no PowerPoint e no Word.

Use a API JavaScript do Office para implementar soluções de rótulo de confidencialidade em seus projetos de Suplemento do Office e dar suporte aos cenários a seguir.

  • Aplique rótulos de confidencialidade a documentos, mensagens ou compromissos para cumprir políticas comerciais e jurídicas.
  • Restrinja ações adicionais se um determinado rótulo de confidencialidade for aplicado, como impedir que os usuários adicionem destinatários externos a uma mensagem.
  • Classifique dados com base em seu rótulo de confidencialidade para dar suporte a auditoria e relatórios.

Observação

No Excel, no PowerPoint e no Word, as APIs de rótulo de confidencialidade estão em versão prévia. No Outlook, o suporte para o recurso de rótulo de confidencialidade foi introduzido no conjunto de requisitos 1.13. Para obter informações sobre suporte ao cliente, consulte Plataformas e clientes com suporte.

Pré-requisitos

O recurso de rótulo de confidencialidade requer uma assinatura do Microsoft 365 E5. Verifique se você se qualifica para uma assinatura de desenvolvedor do Microsoft 365 E5 por meio do Programa de Desenvolvedor do Microsoft 365 nas perguntas frequentes do programa. Caso contrário, inicie uma avaliação gratuita de 1 mês ou adquira um plano do Microsoft 365.

Clientes e plataformas com suporte

O suporte à API do rótulo de confidencialidade varia de acordo com o aplicativo e a plataforma do Office. O suporte do Outlook requer o Exchange Online. A tabela a seguir lista as combinações com suporte.

Application Web Windows Mac
Excel Visualização Versão prévia Visualização
Outlook Com suporte Com suporte
(novo e clássico (Versão 2304 (Build 16327.20248) ou posterior))		 Com suporte
(Versão 16.77 (23081600) ou posterior)
PowerPoint Visualização Versão prévia Visualização
Word Visualização Versão prévia Visualização

Configurar o suporte ao rótulo de confidencialidade

Observação

As APIs de visualização estão sujeitas a alterações e não se destinam ao uso em um ambiente de produção. Recomendamos que você experimente apenas em ambiente de teste e desenvolvimento. Não use APIs de visualização em um ambiente de produção ou em documentos comercialmente críticos.

Para usar APIs de visualização:

As APIs de rótulo de confidencialidade do Excel, PowerPoint e Word seguem um padrão de programação semelhante. Em cada host, o contexto de solicitação fornece acesso ao catálogo de rótulos de confidencialidade, enquanto o objeto de arquivo específico do host fornece métodos para obter ou atualizar seu rótulo.

A tabela a seguir lista os membros da API usados para acessar o catálogo de rótulos de confidencialidade e o rótulo aplicado a um arquivo em cada aplicativo host do Office.

Application Catálogo de rótulos de confidencialidade Rótulo de confidencialidade no arquivo
Excel context.sensitivityLabelsCatalog context.workbook.sensitivityLabel
PowerPoint context.sensitivityLabelsCatalog context.presentation.sensitivityLabel
Word context.sensitivityLabelsCatalog context.document.sensitivityLabel

Os exemplos nas seções a seguir usam o Word. Para usar o Excel ou o PowerPoint, substitua o namespace do host correspondente e o objeto de rótulo de confidencialidade no nível do arquivo.

Verifique se a rotulagem de confidencialidade está disponível

Os rótulos e as políticas de confidencialidade são configurados pelo administrador de uma organização por meio do portal de conformidade do Microsoft Purview. Para obter orientações sobre como configurar rótulos de confidencialidade no seu locatário, consulte Criar e configurar rótulos de confidencialidade e suas políticas.

Para determinar se o rótulo de confidencialidade está disponível para o usuário atual, carregue getLabelingCapability (Excel, PowerPoint, Word) do catálogo de rótulos de confidencialidade.

await Word.run(async (context) => {
    // Access the sensitivity label catalog for the current user.
    const labelCatalog = context.sensitivityLabelsCatalog;
    if (!labelCatalog) {
        console.warn("The sensitivity label catalog isn't available.");
        return;
    }

    // Load the labeling capability status before reading it.
    labelCatalog.load("getLabelingCapability");
    await context.sync();

    // Display whether sensitivity labeling is enabled and available.
    console.log(`Sensitivity labeling capability: ${labelCatalog.getLabelingCapability}`);
});

Identificar os rótulos de confidencialidade disponíveis

Para recuperar os rótulos publicados para o usuário atual, chame getLabels() (Excel, PowerPoint, Word) no catálogo.

O método retorna uma coleção cujos itens e propriedades não estão disponíveis até que você os carregue explicitamente e chame context.sync(). Para obter orientação, consulte Carregar de uma coleção. Carga items e as propriedades do rótulo de que seu suplemento precisa. As propriedades disponíveis diferem por host. Para obter uma lista completa, consulte SensitivityLabelDetails (Excel, PowerPoint, Word).

await Word.run(async (context) => {
    // Access the sensitivity label catalog for the current user.
    const labelCatalog = context.sensitivityLabelsCatalog;
    if (!labelCatalog) {
        console.warn("The sensitivity label catalog isn't available.");
        return;
    }

    // Get the available labels and load the properties used by the add-in.
    const availableLabels = labelCatalog.getLabels();
    availableLabels.load("items/id,items/name,items/isEnabled");
    await context.sync();

    // Display the available labels.
    console.log("Available sensitivity labels:");
    availableLabels.items.forEach((label) => {
        console.log(`${label.name} (${label.id}) - ${label.isEnabled ? "Enabled" : "Disabled"}`);
    });
});

Obter o rótulo de confidencialidade

Para recuperar o rótulo atual, se um for aplicado, chame getCurrentOrNullObject() (Excel, PowerPoint, Word) no objeto de rótulo de confidencialidade do arquivo.

await Word.run(async (context) => {
    // Access the sensitivity label applied to the current document.
    const documentLabel = context.document.sensitivityLabel;

    // Get the current label, if one is applied, and load its ID and name.
    const currentLabel = documentLabel.getCurrentOrNullObject();
    currentLabel.load("id,name");
    await context.sync();

    // Display the current label or report that the document isn't labeled.
    if (currentLabel.isNullObject) {
        console.log("The document doesn't have a sensitivity label.");
    } else {
        console.log(`Current label: ${currentLabel.name} (${currentLabel.id})`);
    }
});

Definir o rótulo de confidencialidade

Antes de aplicar um rótulo, chame getLabels() (Excel, PowerPoint, Word) e selecione um rótulo ou sub-rótulo ativado da coleção retornada. O tryToUpdate() método (Excel, PowerPoint, Word) requer a ID do rótulo selecionado como parâmetro. Ligar getLabels() primeiro permite recuperar essa ID necessária e verificar se o rótulo está disponível para o usuário atual. Verifique o valor retornado SensitivityLabelUpdateResult (Excel, PowerPoint, Word) para determinar se a atualização foi bem-sucedida.

Observação

Um rótulo pai com sub-rótulos não pode ser aplicado diretamente. Em vez disso, selecione um de seus sub-rótulos habilitados.

async function setDocumentSensitivityLabel(labelId: string) {
    await Word.run(async (context) => {
        // Access the sensitivity label applied to the current document.
        const documentLabel = context.document.sensitivityLabel;

        // Apply the selected label.
        const updateResult = documentLabel.tryToUpdate(labelId);
        await context.sync();

        // Check whether the label update succeeded.
        if (updateResult.value === Word.SensitivityLabelUpdateResult.success) {
            console.log("Applied the sensitivity label to the document.");
        } else {
            console.error(`The sensitivity label wasn't applied. Result: ${updateResult.value}`);
        }
    });
}

Detectar alterações no rótulo de confidencialidade com o evento OnSensitivityLabelChanged

Observação

O OnSensitivityLabelChanged evento só está disponível no Outlook.

Use o evento para executar a OnSensitivityLabelChanged lógica do suplemento quando o rótulo de confidencialidade for alterado em uma mensagem ou compromisso. Por exemplo, impedir que os usuários façam o downgrade do rótulo de um item de email que contém determinados anexos.

O OnSensitivityLabelChanged evento usa ativação baseada em eventos. Para obter diretrizes de configuração, depuração e implantação, consulte Ativar suplementos com eventos.

Confira também

  • Última atualização em