Gerenciar rótulos de confidencialidade em Suplementos do Office

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.

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.

Para usar o recurso de rótulo de confidencialidade em um suplemento do Outlook, você deve configurar a permissão de item de leitura/gravação no manifesto do seu suplemento.

• Manifesto unificado para o"authorization.permissions.resourceSpecific" Microsoft 365: na matriz, defina a "name" propriedade de um objeto como"MailboxItem.ReadWrite.User".
• Manifesto somente do suplemento: defina o <elemento Permissions> como ReadWriteItem.

Os suplementos que manipulam o evento exigem configuração de manifesto OnSensitivityLabelChanged adicional para ativação baseada em evento. Para obter detalhes, consulte Detectar alterações no rótulo de confidencialidade com o evento OnSensitivityLabelChanged.

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

Antes de obter ou definir o rótulo de confidencialidade em uma mensagem ou compromisso, verifique se o catálogo de rótulos de confidencialidade está habilitado na caixa de correio em que o suplemento está instalado. Chame context.sensitivityLabelsCatalog.getIsEnabledAsync no modo de redação.

// Check whether the catalog of sensitivity labels is enabled.
Office.context.sensitivityLabelsCatalog.getIsEnabledAsync((asyncResult) => {
    if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
        console.log(asyncResult.value);
    } else {
        console.log("Action failed with error: " + asyncResult.error.message);
    }
});

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

Para determinar os rótulos de confidencialidade disponíveis para uso em uma mensagem ou compromisso no modo de redação, use context.sensitivityLabelsCatalog.getAsync. Os rótulos disponíveis são retornados na forma de objetos SensitivityLabelDetails , que fornecem os detalhes a seguir.

• O nome do rótulo.
• O identificador exclusivo (GUID) do rótulo.
• Uma descrição do rótulo.
• A cor atribuída ao rótulo.
• Os sub-rótulos configurados, se houver.

O exemplo a seguir mostra como identificar os rótulos de confidencialidade disponíveis no catálogo.

// Check the sensitivity label catalog status before calling other label methods.
Office.context.sensitivityLabelsCatalog.getIsEnabledAsync((asyncResult) => {
    if (asyncResult.status === Office.AsyncResultStatus.Succeeded && asyncResult.value == true) {
        // Identify available sensitivity labels in the catalog.
        Office.context.sensitivityLabelsCatalog.getAsync((asyncResult) => {
            if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
                const catalog = asyncResult.value;
                console.log("Sensitivity Labels Catalog:");
                catalog.forEach((sensitivityLabel) => {
                    console.log(`Name: ${sensitivityLabel.name}`);
                    console.log(`ID: ${sensitivityLabel.id}`);
                    console.log(`Tooltip: ${sensitivityLabel.tooltip}`);
                    console.log(`Color: ${sensitivityLabel.color}`);
                    console.log(`Sublabels: ${JSON.stringify(sensitivityLabel.children)}`);
                });
            } else {
                console.log("Action failed with error: " + asyncResult.error.message);
            }
        });
    } else {
        console.log("Action failed with error: " + asyncResult.error.message);
    }
});

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

Para obter o rótulo de confidencialidade atualmente aplicado a uma mensagem ou compromisso no modo de redação, chame item.sensitivityLabel.getAsync conforme mostrado no exemplo a seguir. Isso retorna o GUID do rótulo de confidencialidade.

// Check the sensitivity label catalog status before calling other label methods.
Office.context.sensitivityLabelsCatalog.getIsEnabledAsync((asyncResult) => {
    if (asyncResult.status === Office.AsyncResultStatus.Succeeded && asyncResult.value == true) {
        // Get the current sensitivity label of a message or appointment.
        Office.context.mailbox.item.sensitivityLabel.getAsync((asyncResult) => {
            if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
                console.log(asyncResult.value);
            } else {
                console.log("Action failed with error: " + asyncResult.error.message);
            }
        });
    } else {
        console.log("Action failed with error: " + asyncResult.error.message);
    }
});

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.

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

O Outlook dá suporte a um rótulo de confidencialidade em uma mensagem ou compromisso no modo de redação. Antes de definir o rótulo, chame context.sensitivityLabelsCatalog.getAsync para verificar se o rótulo está disponível e recuperar seu GUID. Em seguida, passe o GUID para item.sensitivityLabel.setAsync, conforme mostrado no exemplo a seguir.

// Check the sensitivity label catalog status before calling other label methods.
Office.context.sensitivityLabelsCatalog.getIsEnabledAsync((asyncResult) => {
    if (asyncResult.status === Office.AsyncResultStatus.Succeeded && asyncResult.value == true) {
        // Identify available sensitivity labels in the catalog.
        Office.context.sensitivityLabelsCatalog.getAsync((asyncResult) => {
            if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
                const catalog = asyncResult.value;
                if (catalog.length > 0) {
                    // Get the GUID of the sensitivity label.
                    var id = catalog[0].id;
                    // Set the mail item's sensitivity label using the label's GUID.
                    Office.context.mailbox.item.sensitivityLabel.setAsync(id, (asyncResult) => {
                        if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
                            console.log(asyncResult.status);
                        } else {
                            console.log("Action failed with error: " + asyncResult.error.message);
                        }
                    });
                } else {
                    console.log("Catalog list is empty");
                }
            } else {
                console.log("Action failed with error: " + asyncResult.error.message);
            }
        });
    } else {
        console.log("Action failed with error: " + asyncResult.error.message);
    }
});

Como alternativa, passe o objeto SensitivityLabelDetails retornado pela chamada de catálogo, conforme mostrado no exemplo a seguir.

// Check the sensitivity label catalog status before calling other label methods.
Office.context.sensitivityLabelsCatalog.getIsEnabledAsync((asyncResult) => {
    if (asyncResult.status === Office.AsyncResultStatus.Succeeded && asyncResult.value == true) {
        // Identify available sensitivity labels in the catalog.
        Office.context.sensitivityLabelsCatalog.getAsync((asyncResult) => {
            if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
                const catalog = asyncResult.value;
                if (catalog.length > 0) {
                    // Set the mail item's sensitivity label using the SensitivityLabelDetails object.
                    Office.context.mailbox.item.sensitivityLabel.setAsync(catalog[0], (asyncResult) => {
                        if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
                            console.log(asyncResult.status);
                        } else {
                            console.log("Action failed with error: " + asyncResult.error.message);
                        }
                    });
                } else {
                    console.log("Catalog list is empty");
                }
            } else {
                console.log("Action failed with error: " + asyncResult.error.message);
            }
        });
    } else {
        console.log("Action failed with error: " + asyncResult.error.message);
    }
});