Gérer les étiquettes de confidentialité dans les compléments Office

La collaboration en milieu de travail s’étend souvent au-delà d’une organisation à des partenaires externes. Le partage d’informations en dehors du réseau d’une organization nécessite des mesures pour empêcher la perte de données et appliquer des stratégies de conformité. La protection des données Microsoft Purview fournit des solutions de classification et de protection des informations sensibles. Les étiquettes de confidentialité appliquent cette protection aux données dans Excel, Outlook, PowerPoint et Word.

Utilisez l’API JavaScript d’Office pour implémenter des solutions d’étiquettes de confidentialité dans vos projets de compléments Office et prendre en charge les scénarios suivants.

  • Appliquez des étiquettes de confidentialité à des documents, des messages ou des rendez-vous pour vous conformer aux stratégies professionnelles et juridiques.
  • Limitez les actions supplémentaires si une certaine étiquette de confidentialité est appliquée, par exemple en empêchant les utilisateurs d’ajouter des destinataires externes à un message.
  • Classifiez les données en fonction de leur étiquette de confidentialité pour prendre en charge les audits et la création de rapports.

Remarque

Dans Excel, PowerPoint et Word, les API d’étiquette de confidentialité sont en préversion. Dans Outlook, la prise en charge de la fonctionnalité d’étiquette de confidentialité a été introduite dans l’ensemble de conditions requises 1.13. Pour plus d’informations sur le support client, consultez Clients et plateformes pris en charge.

Configuration requise

La fonctionnalité d’étiquette de confidentialité nécessite un abonnement Microsoft 365 E5. Vérifiez si vous êtes éligible à un abonnement développeur Microsoft 365 E5 via le programme Microsoft 365 Developer dans le FAQ du programme. Sinon, démarrez un essai gratuit d’un mois ou achetez un plan Microsoft 365.

Clients et plateformes pris en charge

Étiquette de confidentialité La prise en charge de l’API varie selon l’application et la plateforme Office. La prise en charge de Outlook nécessite Exchange Online. Le tableau suivant répertorie les combinaisons prises en charge.

Application Web Windows Mac
Excel Aperçu Aperçu Aperçu
Outlook Pris en charge Pris en charge
(nouveau et classique (version 2304 (Build 16327.20248) ou ultérieure))		 Pris en charge
(Version 16.77 (23081600) ou ultérieure)
PowerPoint Aperçu Aperçu Aperçu
Word Aperçu Aperçu Aperçu

Configurer la prise en charge des étiquettes de confidentialité

Remarque

Les API en préversion sont susceptibles d’être modifiées et ne sont pas destinées à être utilisées dans un environnement de production. Nous vous recommandons de les tester uniquement dans les environnements de test et de développement. N’utilisez pas d’API de prévisualisation dans un environnement de production ou dans des documents critiques pour l’entreprise.

Pour utiliser les API disponibles en préversion :

Les API d’étiquette de confidentialité Excel, PowerPoint et Word suivent un modèle de programmation similaire. Dans chaque hôte, le contexte de demande permet d’accéder au catalogue d’étiquettes de confidentialité, tandis que l’objet fichier spécifique à l’hôte fournit des méthodes pour obtenir ou mettre à jour son étiquette.

Le tableau suivant répertorie les membres d’API utilisés pour accéder au catalogue d’étiquettes de confidentialité et l’étiquette appliquée à un fichier dans chaque application hôte Office.

Application Catalogue d’étiquettes de confidentialité Étiquette de sensibilité sur le fichier
Excel context.sensitivityLabelsCatalog context.workbook.sensitivityLabel
PowerPoint context.sensitivityLabelsCatalog context.presentation.sensitivityLabel
Word context.sensitivityLabelsCatalog context.document.sensitivityLabel

Les exemples des sections suivantes utilisent Word. Pour utiliser Excel ou PowerPoint, remplacez l’espace de noms d’hôte correspondant et l’objet d’étiquette de confidentialité au niveau fichier.

Vérifier que l’étiquetage de sensibilité est disponible

Les étiquettes de confidentialité et les stratégies sont configurées par l’administrateur d’une organisation via le portail de conformité Microsoft Purview. Pour obtenir des instructions sur la configuration des étiquettes de confidentialité dans votre client, consultez Créer et configurer des étiquettes de confidentialité et leurs stratégies.

Pour déterminer si l’étiquetage de confidentialité est disponible pour l’utilisateur actuel, chargez getLabelingCapability (Excel, PowerPoint, Word) à partir du catalogue d’étiquettes de confidentialité.

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

Identifier les étiquettes de confidentialité disponibles

Pour récupérer les étiquettes publiées pour l’utilisateur actuel, appelez getLabels() (Excel, PowerPoint, Word) dans le catalogue.

Cette méthode renvoie une collection dont les éléments et les propriétés ne sont pas disponibles tant que vous ne les chargez pas explicitement et que vous n’appelez context.sync()pas . Pour obtenir des conseils, voir Charger à partir d’une collection. Chargez items et les propriétés d’étiquette dont votre complément a besoin. Les propriétés disponibles sont différentes selon l’hôte. Pour la liste complète, voir 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"}`);
    });
});

Obtenir l’étiquette de confidentialité

Pour récupérer l’étiquette actuelle, le cas échéant, appelez getCurrentOrNullObject() (Excel, PowerPoint, Word) sur l’objet étiquette de confidentialité du fichier.

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

Définir l’étiquette de confidentialité

Avant d’appliquer une étiquette, appelez getLabels() (Excel, PowerPoint, Word) et sélectionnez une étiquette ou une sous-étiquette activée dans la collection retournée. La tryToUpdate() méthode (Excel, PowerPoint, Word) nécessite l’ID de l’étiquette sélectionnée comme paramètre. Appeler getLabels() en premier vous permet de récupérer cet ID requis et de vérifier que l’étiquette est disponible pour l’utilisateur actuel. Vérifiez la valeur renvoyée SensitivityLabelUpdateResult (Excel, PowerPoint, Word) pour déterminer si la mise à jour a réussi.

Remarque

Une étiquette parente contenant des sous-étiquettes ne peut pas être appliquée directement. Sélectionnez plutôt l’une de ses sous-étiquettes activées.

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

Détecter les modifications d’étiquettes de confidentialité avec l’événement OnSensitivityLabelChanged

Remarque

L’événement OnSensitivityLabelChanged est disponible uniquement dans Outlook.

Utilisez l’événement pour exécuter la OnSensitivityLabelChanged logique de complément lorsque l’étiquette de confidentialité change dans un message ou un rendez-vous. Par exemple, empêchez les utilisateurs de rétrograder l’étiquette d’un élément de courrier qui contient certaines pièces jointes.

L’événement OnSensitivityLabelChanged utilise l’activation basée sur les événements. Pour obtenir des instructions sur la configuration, le débogage et le déploiement, consultez Activer des compléments à l’aide d’événements.

Voir aussi

  • Last updated on