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

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:

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.

Pruebe las API en Script Lab

Obtenga el complemento Script Lab y pruebe la muestra Administrar etiquetas de confidencialidad para la aplicación de Office.

Los ejemplos muestran cómo comprobar las capacidades de etiquetado, enumerar etiquetas y subetiquetas, recuperar atributos ABAC, obtener la etiqueta actual y aplicar una etiqueta con o sin atributos ABAC.

Para más información sobre Script Lab, consulte Explorar las API de JavaScript de Office con Script Lab.

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.

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.

El estado es un LabelingCapability valor (Excel, PowerPoint, Word), como labelingEnabled, labelingDisabled, labelingPolicyNotFoundo noLicense. Para comprobar si hay funcionalidades adicionales, cargue la getLabelingCapabilities matriz (Excel, PowerPoint, Word). Por ejemplo, compruebe attributeBasedAccessControlEnabled los atributos de control de acceso basado en atributos (ABAC) antes de recuperarlos.

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,getLabelingCapabilities");
    await context.sync();

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

Identificación de etiquetas de confidencialidad disponibles

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. El SensitivityLabelDetails objeto (Excel, PowerPoint, Word) proporciona la siguiente información.

  • El identificador de la etiqueta, el nombre, la descripción (tooltip), el color, el pedido y el identificador de inquilino (siteId).
  • Si la etiqueta está habilitada (isEnabled) y su tipo de protección (protectionType).
  • Subetiquetas de la children colección. Cargue explícitamente las propiedades de subetiquetas que necesita el complemento.
  • Si la etiqueta admite ABAC (isAbacEnabled) y requiere selecciones de atributo (isAbacAttributesRequired).
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,items/isAbacEnabled,items/isAbacAttributesRequired," +
        "items/children/items/id,items/children/items/name,items/children/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"}`);
        console.log(`ABAC enabled: ${label.isAbacEnabled}; attributes required: ${label.isAbacAttributesRequired}`);
        if (label.children) {
            label.children.items.forEach((sublabel) => {
                console.log(`  ${sublabel.name} (${sublabel.id}) - ${sublabel.isEnabled ? "Enabled" : "Disabled"}`);
            });
        }
    });
});

Obtener la etiqueta de confidencialidad

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.
    const currentLabel = documentLabel.getCurrentOrNullObject();
    currentLabel.load("id,name,isAbacEnabled");
    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})`);
        if (currentLabel.isAbacEnabled) {
            currentLabel.load("abacAttributeValues");
            await context.sync();
            console.log("Applied ABAC attribute values:", currentLabel.abacAttributeValues);
        }
    }
});

Establecer la etiqueta de confidencialidad

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 ID de la etiqueta seleccionada como primer parámetro y acepta un objeto opcional SensitivityLabelTryUpdateOptions (Excel, PowerPoint, Word) para las selecciones de atributos ABAC. Llamar getLabels() primero le permite recuperar el identificador requerido y comprobar que la etiqueta está disponible para el usuario actual.

Después de llamar context.sync(), lea updateResult.value.status del objeto devuelto SensitivityLabelUpdateResult (Excel, PowerPoint, Word). Compárela con SensitivityLabelUpdateStatus.success (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, options?: Word.SensitivityLabelTryUpdateOptions) {
    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, options);
        await context.sync();

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

Aplicar una etiqueta con atributos ABAC

Para las etiquetas habilitadas para ABAC, recupere los atributos disponibles a través de SensitivityLabelsCatalog.getAttributes() (Excel, PowerPoint, Word). En primer lugar, cargue getLabelingCapabilities y compruebe que incluya LabelingCapability.attributeBasedAccessControlEnabled. El método devuelve cuya ClientResultvalue propiedad contiene una matriz de SensitivityLabelAbacAttribute objetos (Excel, PowerPoint, Word). Llame antes de context.sync() leer esta propiedad.

Cada atributo tiene un nombre para mostrar, un orden para mostrar, un tipo de datos, un estado activo, una isMultiValued marca y una values matriz.

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

    labelCatalog.load("getLabelingCapabilities");
    await context.sync();

    if (!labelCatalog.getLabelingCapabilities.includes(Word.LabelingCapability.attributeBasedAccessControlEnabled)) {
        console.warn("ABAC attributes aren't enabled or available for the current user.");
        return;
    }

    const catalogAttributes: OfficeExtension.ClientResult<Word.SensitivityLabelAbacAttribute[]> =
        labelCatalog.getAttributes();
    await context.sync();

    console.log("Available ABAC attributes:", catalogAttributes.value);
});

Para aplicar una etiqueta con atributos ABAC, utilice atributos del catálogo e incluya solo los valores seleccionados por el usuario en la matriz de values cada atributo. Use solo atributos activos y valores activos, y permita varios valores solo cuando isMultiValued sea true. Valide las selecciones con la directiva actual antes de aplicar la etiqueta.

Pase los atributos seleccionados a través de la abacAttributes propiedad del objeto de opciones proporcionado a tryToUpdate(). Se aplican las siguientes reglas.

  • Si isAbacEnabled es false, omita abacAttributes o pase una matriz vacía. De lo contrario, el estado de la actualización es abacAttributesNotAllowed.
  • Si isAbacEnabled y isAbacAttributesRequired son ambos true, proporcione selecciones de atributos. De lo contrario, el estado de la actualización es abacAttributesRequired.
  • Compruebe el estado de la actualización en busca de otros errores, como unsupportedAbac, , labelDisabledo insufficientPermission. Una operación completada context.sync() no significa por sí misma que se haya aplicado la etiqueta.

Para leer los valores ABAC aplicados actualmente a un archivo, cargue abacAttributeValues el objeto devuelto por getCurrentOrNullObject(), como se muestra en Obtener la etiqueta de confidencialidad. Compruebe isNullObject y isAbacEnabled antes de cargar los valores.

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

  • Se actualizó por última vez el