Administrar etiquetas de confidencialidad en complementos de Office

La colaboración en el lugar de trabajo a menudo se extiende más allá de una organización a asociados externos. Compartir información fuera de la red de una organización requiere medidas para evitar la pérdida de datos y aplicar las directivas de cumplimiento. Microsoft Purview Information Protection proporciona soluciones para clasificar y proteger información confidencial. Las etiquetas de confidencialidad aplican esta protección a los datos de Excel, Outlook, PowerPoint y Word.

Use la API de JavaScript de Office para implementar soluciones de etiquetas de confidencialidad en los proyectos de complementos de Office y admitir los siguientes escenarios.

Aplique etiquetas de confidencialidad a documentos, mensajes o citas para cumplir con las directivas empresariales y legales.
Restrinja las acciones adicionales si se aplica una determinada etiqueta de confidencialidad, como impedir que los usuarios agreguen destinatarios externos a un mensaje.
Clasifique los datos en función de su etiqueta de confidencialidad para admitir auditorías e informes.

Nota:

En Excel, PowerPoint y Word, las API de etiquetas de confidencialidad están en versión preliminar. En Outlook, la compatibilidad con la característica de etiqueta de confidencialidad se introdujo en el conjunto de requisitos 1.13. Para obtener información sobre la compatibilidad con clientes, consulte Clientes y plataformas compatibles.

Requisitos previos

La característica de etiqueta de confidencialidad requiere una suscripción a Microsoft 365 E5. Compruebe si cumple los requisitos para obtener una suscripción para desarrolladores de Microsoft 365 E5 a través del Programa para desarrolladores de Microsoft 365 en las preguntas más frecuentes del programa. De lo contrario, inicie una prueba gratuita de 1 mes o compre un plan de Microsoft 365.

Plataformas y clientes admitidos

La compatibilidad de la API con etiquetas de confidencialidad varía según la aplicación y la plataforma de Office. El soporte técnico de Outlook requiere Exchange Online. En la tabla siguiente se enumeran las combinaciones admitidas.

Aplicación	Web	Windows	Mac
Excel	Preview	Vista previa	Preview
Outlook	Compatible	Compatible (nuevo y clásico (versión 2304 (compilación 16327.20248) o posterior))	Compatible (Versión 16.77 (23081600) o posterior)
PowerPoint	Preview	Vista previa	Preview
Word	Preview	Vista previa	Preview

Configurar la compatibilidad con etiquetas de confidencialidad

Excel, PowerPoint y Word
Outlook

Nota:

Las API de versión preliminar están sujetas a cambios y no están diseñadas para usarse en un entorno de producción. Le recomendamos que solo las pruebe en entornos de desarrollo y pruebas. No use las API de versión preliminar en un entorno de producción ni en documentos críticos para la empresa.

Usar las API en versión preliminar:

Debe usar la versión preliminar de la biblioteca de API de JavaScript de Office de la red de entrega de contenido (CDN) deOffice.js. El tipo de archivo de definición para la compilación TypeScript e IntelliSense se encuentra en la CDN y DefinitelyTyped. Puede instalar estos tipos con npm install --save-dev @types/office-js-preview.
Es posible que deba unirse al programa Microsoft 365 Insider para obtener acceso a las compilaciones de Office más recientes.

Las API de etiquetas de confidencialidad de Excel, PowerPoint y Word siguen un patrón de programación similar. En cada host, el contexto de solicitud proporciona acceso al catálogo de etiquetas de confidencialidad, mientras que el objeto de archivo específico del host proporciona métodos para obtener o actualizar su etiqueta.

En la tabla siguiente se enumeran los miembros de API usados para acceder al catálogo de etiquetas de confidencialidad y la etiqueta aplicada a un archivo en cada aplicación host de Office.

Aplicación	Catálogo de etiquetas de confidencialidad	Etiqueta de confidencialidad en el archivo
Excel	`context.sensitivityLabelsCatalog`	`context.workbook.sensitivityLabel`
PowerPoint	`context.sensitivityLabelsCatalog`	`context.presentation.sensitivityLabel`
Word	`context.sensitivityLabelsCatalog`	`context.document.sensitivityLabel`

En los ejemplos de las secciones siguientes se utiliza Word. Para usar Excel o PowerPoint, sustituya el espacio de nombres de host correspondiente y el objeto de etiqueta de confidencialidad de nivel de archivo.

Para usar la característica de etiquetas de confidencialidad en un complemento de Outlook, debe configurar el permiso de elemento de lectura y escritura en el manifiesto de su complemento.

Manifiesto unificado para Microsoft 365: En la "authorization.permissions.resourceSpecific" matriz, establezca la "name" propiedad de un objeto en "MailboxItem.ReadWrite.User".
Manifiesto de solo complemento: establezca el <elemento Permisos> en ReadWriteItem.

Nota:

Los complementos que usan el manifiesto unificado para Microsoft 365 no son compatibles con Outlook en Mac. Estamos trabajando arduamente para brindar ese apoyo. Mientras tanto, si su base de clientes incluye usuarios en Mac, debe crear una versión de su complemento que use el manifiesto de solo complemento y que sea compatible con ambos. Para obtener más información, consulte Compatibilidad con complementos con el manifiesto unificado para Microsoft 365.

Los complementos que controlan el OnSensitivityLabelChanged evento requieren una configuración de manifiesto adicional para la activación basada en eventos. Para obtener más información, consulte Detectar cambios en la etiqueta de confidencialidad con el evento OnSensitivityLabelChanged.

Comprobar que el etiquetado de confidencialidad está disponible

El administrador de una organización configura las etiquetas y directivas de confidencialidad a través del portal de cumplimiento de Microsoft Purview. Para obtener instrucciones sobre cómo configurar etiquetas de confidencialidad en el inquilino, consulte Creación y configuración de etiquetas de confidencialidad y sus directivas.

Excel, PowerPoint y Word
Outlook

Para determinar si el etiquetado de confidencialidad está disponible para el usuario actual, cargue getLabelingCapability (Excel, PowerPoint, Word) desde el catálogo de etiquetas de confidencialidad.

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 obtener o establecer la etiqueta de confidencialidad en un mensaje o cita, compruebe que el catálogo de etiquetas de confidencialidad está habilitado en el buzón donde está instalado el complemento. Llame a context.sensitivityLabelsCatalog.getIsEnabledAsync en modo de redacción.

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

Identificación de etiquetas de confidencialidad disponibles

Excel, PowerPoint y Word
Outlook

Para recuperar las etiquetas publicadas para el usuario actual, llame getLabels() (Excel, PowerPoint, Word) al catálogo.

El método devuelve una colección cuyos elementos y propiedades no están disponibles hasta que los carga explícitamente y llama a context.sync(). Para obtener instrucciones, consulte Cargar desde una colección. y items las propiedades de etiqueta que necesita el complemento. Las propiedades disponibles difieren según el host. Para obtener una 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 las etiquetas de confidencialidad disponibles para su uso en un mensaje o una cita en modo de redacción, use context.sensitivityLabelsCatalog.getAsync. Las etiquetas disponibles se devuelven en forma de objetos SensitivityLabelDetails , que proporcionan los siguientes detalles.

El nombre de la etiqueta.
El identificador único (GUID) de la etiqueta.
Una descripción de la etiqueta.
El color asignado a la etiqueta.
Las subetiquetas configuradas, si las hay.

En el ejemplo siguiente se muestra cómo identificar las etiquetas de confidencialidad disponibles en el 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 la etiqueta actual, si se aplica una, llame getCurrentOrNullObject() (Excel, PowerPoint, Word) al objeto de etiqueta de confidencialidad del archivo.

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 obtener la etiqueta de confidencialidad aplicada actualmente a un mensaje o cita en modo de redacción, llame a item.sensitivityLabel.getAsync como se muestra en el ejemplo siguiente. Devuelve el GUID de la etiqueta de confidencialidad.

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

Establecer la etiqueta de confidencialidad

Excel, PowerPoint y Word
Outlook

Antes de aplicar una etiqueta, llame getLabels() (Excel, PowerPoint, Word) y seleccione una etiqueta o subetiqueta habilitada de la colección devuelta. El tryToUpdate() método (Excel, PowerPoint, Word) requiere el identificador de la etiqueta seleccionada como parámetro. Llamar getLabels() primero le permite recuperar este identificador necesario y comprobar que la etiqueta está disponible para el usuario actual. Compruebe el valor devuelto SensitivityLabelUpdateResult (Excel, PowerPoint, Word) para determinar si la actualización se ha realizado correctamente.

Nota:

Una etiqueta principal que tiene subetiquetas no se puede aplicar directamente. En su lugar, seleccione uno de sus subsellos 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}`);
        }
    });
}

Outlook admite una etiqueta de confidencialidad en un mensaje o cita en el modo de redacción. Antes de establecer la etiqueta, llame a context.sensitivityLabelsCatalog.getAsync para comprobar que la etiqueta está disponible y recuperar su GUID. A continuación, pase el GUID a item.sensitivityLabel.setAsync, como se muestra en el ejemplo siguiente.

// 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, pase el objeto SensitivityLabelDetails devuelto por la llamada al catálogo, como se muestra en el ejemplo siguiente.

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

Detectar cambios en la etiqueta de confidencialidad con el evento OnSensitivityLabelChanged

Nota:

El OnSensitivityLabelChanged evento solo está disponible en Outlook.

Use el evento para ejecutar la OnSensitivityLabelChanged lógica del complemento cuando cambie la etiqueta de confidencialidad de un mensaje o cita. Por ejemplo, impedir que los usuarios degraden la etiqueta de un elemento de correo que contenga determinados datos adjuntos.

El OnSensitivityLabelChanged evento utiliza la activación basada en eventos. Para obtener instrucciones de configuración, depuración e implementación, consulte Activación de complementos con eventos.

Recursos adicionales

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2026-09-25