Verwalten von Vertraulichkeitsbezeichnungen in Office-Add-Ins

Die Zusammenarbeit am Arbeitsplatz erstreckt sich häufig über eine Organisation hinaus auf externe Partner. Das Teilen von Informationen außerhalb des Netzwerks einer Organization erfordert Maßnahmen zur Verhinderung von Datenverlust und zur Durchsetzung von Compliancerichtlinien. Microsoft Purview Information Protection bietet Lösungen zum Klassifizieren und Schützen vertraulicher Informationen. Vertraulichkeitsbezeichnungen wenden diesen Schutz auf Daten in Excel, Outlook, PowerPoint und Word an.

Verwenden Sie die Office JavaScript-API, um Lösungen für Vertraulichkeitsbezeichnungen in Ihren Office-Add-In-Projekten zu implementieren und die folgenden Szenarien zu unterstützen.

  • Versehen Sie Dokumente, Nachrichten oder Termine mit Vertraulichkeitsbezeichnungen, um geschäftliche und rechtliche Richtlinien einzuhalten.
  • Beschränken Sie zusätzliche Aktionen, wenn eine bestimmte Vertraulichkeitsbezeichnung angewendet wird, z. B. um zu verhindern, dass Benutzer einer Nachricht externe Empfänger hinzufügen.
  • Klassifizieren Sie Daten basierend auf ihrer Vertraulichkeitsbezeichnung, um Überwachung und Berichterstellung zu unterstützen.

Hinweis

In Excel, PowerPoint und Word befinden sich die Vertraulichkeitsbezeichnungs-APIs in der Vorschauphase. In Outlook wurde die Unterstützung für das Feature für Vertraulichkeitsbezeichnungen in Anforderungssatz 1.13 eingeführt. Informationen zur Clientunterstützung finden Sie unter Unterstützte Clients und Plattformen.

Voraussetzungen

Für das Feature für Vertraulichkeitsbezeichnungen ist ein Microsoft 365 E5-Abonnement erforderlich. Überprüfen Sie in den häufig gestellten Fragen, ob Sie über das Microsoft 365 Developer Program für ein Microsoft 365 E5 Entwicklerabonnement berechtigt sind. Starten Sie andernfalls eine 1-monatige kostenlose Testversion, oder erwerben Sie einen Microsoft 365-Plan.

Unterstützte Clients und Plattformen

Die Unterstützung für die Vertraulichkeitsbezeichnungs-API variiert je nach Office-Anwendung und -Plattform. Für die Outlook-Unterstützung ist Exchange Online erforderlich. In der folgenden Tabelle sind die unterstützten Kombinationen aufgeführt.

Application Web Windows Mac
Excel Vorschau Vorschau Vorschau
Outlook Unterstützt Unterstützt
(neu und klassisch (Version 2304 (Build 16327.20248) oder höher))		 Unterstützt
(Version 16.77 (23081600) oder höher)
PowerPoint Vorschau Vorschau Vorschau
Word Vorschau Vorschau Vorschau

Unterstützung für Vertraulichkeitsbezeichnungen konfigurieren

Hinweis

Vorschau-APIs können sich ändern und sind nicht für die Verwendung in einer Produktionsumgebung vorgesehen. Wir empfehlen, sie nur in Test- und Entwicklungsumgebungen auszuprobieren. Verwenden Sie keine Vorschau-APIs in einer Produktionsumgebung oder in geschäftskritischen Dokumenten.

So verwenden Sie Vorschau-APIs:

Die Excel-, PowerPoint- und Word-APIs für Vertraulichkeitsbezeichnungen folgen einem ähnlichen Programmiermuster. Auf jedem Host bietet der Anforderungskontext Zugriff auf den Katalog für Vertraulichkeitsbezeichnungen, während das hostspezifische Dateiobjekt Methoden zum Abrufen oder Aktualisieren seiner Bezeichnung bereitstellt.

In der folgenden Tabelle sind die API-Mitglieder aufgeführt, die für den Zugriff auf den Katalog für Vertraulichkeitsbezeichnungen verwendet werden, und die Bezeichnung, die auf eine Datei in jeder Office-Hostanwendung angewendet wird.

Application Katalog für Vertraulichkeitsbezeichnungen Vertraulichkeitsbezeichnung für die Datei
Excel context.sensitivityLabelsCatalog context.workbook.sensitivityLabel
PowerPoint context.sensitivityLabelsCatalog context.presentation.sensitivityLabel
Word context.sensitivityLabelsCatalog context.document.sensitivityLabel

In den Beispielen in den folgenden Abschnitten wird Word verwendet. Um Excel oder PowerPoint zu verwenden, ersetzen Sie den entsprechenden Hostnamespace und das entsprechende Objekt der Vertraulichkeitsbezeichnung auf Dateiebene.

Überprüfen, ob Vertraulichkeitsbezeichnungen verfügbar sind

Vertraulichkeitsbezeichnungen und Richtlinien werden vom Administrator einer Organisation über das Microsoft Purview-Complianceportal konfiguriert. Anleitungen zum Konfigurieren von Vertraulichkeitsbezeichnungen in Ihrem Mandanten finden Sie unter Erstellen und Konfigurieren von Vertraulichkeitsbezeichnungen und deren Richtlinien.

Um zu ermitteln, ob Vertraulichkeitsbezeichnungen für den aktuellen Benutzer verfügbar sind, laden Sie getLabelingCapability (Excel, PowerPoint, Word) aus dem Katalog für Vertraulichkeitsbezeichnungen.

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

Identifizieren verfügbarer Vertraulichkeitsbezeichnungen

Um die für den aktuellen Benutzer veröffentlichten Bezeichnungen abzurufen, rufen Sie (Excel, PowerPoint, Word) im Katalog auf getLabels() .

Die Methode gibt eine Auflistung zurück, deren Elemente und Eigenschaften erst verfügbar sind, wenn Sie sie explizit laden und aufrufen context.sync(). Anleitungen finden Sie unter Laden aus einer Sammlung. Laden items und die Bezeichnungseigenschaften, die Ihr Add-In benötigt. Die verfügbaren Eigenschaften unterscheiden sich je nach Host. Eine vollständige Liste finden Sie unter 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"}`);
    });
});

Abrufen der Vertraulichkeitsbezeichnung

Wenn eine Bezeichnung angewendet wird, rufen getCurrentOrNullObject() Sie (Excel, PowerPoint, Word) für das Vertraulichkeitsbezeichnungsobjekt der Datei auf.

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

Festlegen der Vertraulichkeitsbezeichnung

Rufen getLabels() Sie vor dem Anwenden einer Bezeichnung (Excel, PowerPoint, Word) auf, und wählen Sie eine aktivierte Bezeichnung oder Unterbezeichnung aus der zurückgegebenen Sammlung aus. Für die tryToUpdate() Methode (Excel, PowerPoint, Word) wird die ID der ausgewählten Bezeichnung als Parameter benötigt. Wenn Sie zuerst anrufen getLabels() , können Sie diese erforderliche ID abrufen und überprüfen, ob die Bezeichnung für den aktuellen Benutzer verfügbar ist. Überprüfen Sie den zurückgegebenen SensitivityLabelUpdateResult Wert (Excel, PowerPoint, Word), um zu ermitteln, ob das Update erfolgreich war.

Hinweis

Eine übergeordnete Bezeichnung mit untergeordneten Bezeichnungen kann nicht direkt angewendet werden. Wählen Sie stattdessen eine der aktivierten Unterbezeichnungen aus.

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

Erkennen von Änderungen von Vertraulichkeitsbezeichnungen mit dem Ereignis OnSensitivityLabelChanged

Hinweis

Das OnSensitivityLabelChanged Ereignis ist nur in Outlook verfügbar.

Verwenden Sie das Ereignis zum Ausführen der OnSensitivityLabelChanged Add-In-Logik, wenn sich die Vertraulichkeitsbezeichnung für eine Nachricht oder einen Termin ändert. So hindern Sie beispielsweise Benutzer daran, die Bezeichnung eines E-Mail-Elements, das bestimmte Anlagen enthält, herabzustufen.

Das OnSensitivityLabelChanged Ereignis verwendet eine ereignisbasierte Aktivierung. Hinweise zur Konfiguration, zum Debuggen und zur Bereitstellung finden Sie unter Aktivieren von Add-Ins mit Ereignissen.

Siehe auch

  • Zuletzt aktualisiert um