Anfordern von Berechtigungen für API-Verwendung in Add-Ins

In diesem Artikel werden die verschiedenen Berechtigungsstufen beschreiben, die Sie im Manifest Ihres Inhalts- oder Aufgabenbereich-Add-ins deklarieren können, um die Stufe von JavaScript-API-Zugriff festzulegen, die für den Zugriff auf die Add-in-Funktionen erforderlich ist.

Hinweis

Informationen zu Berechtigungsstufen für E-Mail-Add-Ins (Outlook) finden Sie unter Outlook-Berechtigungsmodell.

Berechtigungsmodell

Der Datenschutz und die Sicherheit für Benutzer Ihrer Inhalts- und Aufgabenbereich-Add-ins basieren auf einem 5-stufigen JavaScript-API-Zugriffsberechtigungsmodell. In Abbildung 1 werden die 5 Stufen von API-Berechtigungen gezeigt, die Sie im Manifest Ihres Add-ins deklarieren können.

Abbildung 1: Das fünfstufige Berechtigungsmodell für Inhalts- und Aufgabenbereich-Add-Ins

Diese Berechtigungen geben die Teilmenge der API an, die die Add-In-Runtime ihrem Inhalts- oder Aufgabenbereich-Add-In erlaubt, wenn ein Benutzer einfügt, und dann Ihr Add-In aktiviert (als vertrauenswürdig). Zum Deklarieren der erforderlichen Berechtigungsstufe für Ihr Inhalts- oder Aufgabenbereich-Add-in legen Sie im Element Permissions des Manifests Ihres Add-ins einen der Berechtigungstextwerte fest. Im folgenden Beispiel ist die WriteDocument-Berechtigung erforderlich, die nur solche Methoden zulässt, die in das Dokument schreiben (aber es nicht lesen) können.

<Permissions>WriteDocument</Permissions>

Als bewährte Methode sollten Sie Berechtigungen nach dem Prinzip der geringsten Rechte anfordern. Das heißt, die angeforderten Berechtigungen sollten Zugriff auf lediglich die minimale Teilmenge der API gewähren, die Ihr Add-in für eine ordnungsgemäße Funktion benötigt. Wenn Ihr Add-in zum Funktionieren beispielsweise nur Daten im Dokument eines Benutzers lesen muss, sollten Sie keine Berechtigung anfordern, die über ReadDocument hinausgeht.

In der folgenden Tabelle ist die von den einzelnen Berechtigungsstufen aktivierte Teilmenge der JavaScript-API beschrieben.

Berechtigung	Aktivierte Teilmenge der API
Restricted	Die Methoden des Settings-Objekts und die Document.getActiveViewAsync-Methode. Dies ist die minimale Berechtigung, die von einem Aufgabenbereich-Add-in angefordert werden kann.
ReadDocument	Zusätzlich zur von der Restricted-Berechtigung zugelassenen API fügt es Zugriff auf die zum Lesen des Dokuments und zum Verwalten von Bindungen notwendigen API-Mitglieder hinzu. Dies umfasst die Verwendung von Folgendem: Die Document.getSelectedDataAsync-Methode zum Abrufen des ausgewählten Textes, HTML (nur Word) oder Tabellendaten, aber kein zugrunde liegender Open Office XML (OOXML)-Code, bei dem sämtliche Daten im Dokument enthalten sind. Die Document.getFileAsync-Methode zum Abrufen sämtlichen Textes im Dokument, jedoch nicht die zugrunde liegende OOXML-Binärkopie des Dokuments. Die Binding.getDataAsync-Methode zum Lesen gebundener Daten im Dokument. Die addFromNamedItemAsync-, addFromPromptAsync-, addFromSelectionAsync-Methoden des Bindings-Objekts zum Erstellen von Bindungen im Dokument. Die getAllAsync-, getByIdAsync- und releaseByIdAsync-Methoden des Bindings-Objekts zum Zugreifen auf und Entfernen von Bindungen im Dokument. Die Document.getFilePropertiesAsync-Methode zum Zugreifen auf Dateieigenschaften des Dokuments, z. B. die URL des Dokuments. Die Document.goToByIdAsync-Methode zum Navigieren zu benannten Objekten und Speicherorten im Dokument. Bei Aufgabenbereich-Add-ins für ein Projekt, alle Abrufmethoden des Objekts ProjectDocument.
ReadAllDocument	Zusätzlich zu der API, die durch die Berechtigungen Restricted und ReadDocument zulässig ist, ermöglicht den folgenden zusätzlichen Zugriff auf Dokumentdaten. Die Document.getSelectedDataAsync- und Document.getFileAsync-Methoden können auf den zugrunde liegenden OOXML-Code des Dokumentes zugreifen (der zusätzlich zum Text Formatierungen, Verknüpfungen, eingebettete Grafik, Kommentare, Überarbeitungen usw. aufweisen kann).
WriteDocument	Zusätzlich zur API, die durch die Berechtigung Eingeschränkt zulässig ist, wird zugriff auf die folgenden API-Member hinzugefügt. Die Document.setSelectedDataAsync-Methode zum Schreiben der Auswahl des Benutzers in das Dokument.
ReadWriteDocument	Umfasst, zusätzlich zur durch die Berechtigungen Restricted-, ReadDocument, ReadAllDocument und WriteDocument zulässigen API, Zugriff auf alle verbleibenden, durch Inhalts- und Aufgabenbereich-Add-ins unterstützten APIs, einschließlich Methoden für das Abonnieren von Ereignissen. Für den Zugriff auf diese zusätzlichen API-Mitglieder müssen Sie die ReadWriteDocument-Berechtigung deklarieren: Die Binding.setDataAsync-Methode zum Schreiben in gebundene Bereiche des Dokuments. Die TableBinding.addRowsAsync-Methode zum Hinzufügen von Zeilen zu gebundenen Tabellen. Die TableBinding.addColumnsAsync-Methode zum Hinzufügen von Spalten zu gebundenen Tabellen. Die TableBinding.deleteAllDataValuesAsync-Methode zum Löschen sämtlicher Daten in einer gebundenen Tabelle. Die setFormatsAsync-, clearFormatsAsync- und setTableOptionsAsync-Methoden des TableBinding-Objekts zum Festlegen von Formatierungsoptionen für gebundene Tabellen. Alle Mitglieder der CustomXmlNode-, CustomXmlPart-, CustomXmlParts- und CustomXmlPrefixMappings-Objekte. Alle Methoden zum Abonnieren der von Inhalts- und Aufgabenbereich-Add-ins unterstützten Ereignisse, insbesondere die Methoden addHandlerAsync und removeHandlerAsync der Objekte Binding, CustomXmlPart, Document, ProjectDocument und Settings.

Siehe auch

• Datenschutz und Sicherheit für Office-Add-Ins