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

In diesem Artikel werden die verschiedenen Berechtigungsstufen beschrieben, die Sie im Manifest Ihres Add-Ins deklarieren, um die Ebene des JavaScript-API-Zugriffs anzugeben, den Ihr Add-In für seine Features benötigt.

Wichtig

Dieser Artikel gilt nur für Nicht-Outlook-Add-Ins. Informationen zu Berechtigungsstufen für Outlook-Add-Ins finden Sie unter Grundlegendes zu Outlook-Add-In-Berechtigungen.

Berechtigungsmodell

Ein fünfstufiges JavaScript-API-Zugriffsberechtigungsmodell bietet die Grundlage für Datenschutz und Sicherheit für Benutzer Ihrer Add-Ins. Die folgende Abbildung zeigt die fünf Ebenen von API-Berechtigungen, die Sie im Manifest Ihres Add-Ins deklarieren können.

Berechtigungsebenen für Add-Ins.

Diese Berechtigungen geben die Teilmenge der API an, die die Add-In-Runtime ihrem Add-In ermöglicht, wenn ein Benutzer einfügt, und dann Ihr Add-In aktiviert (vertrauenswürdig). Um die Berechtigungsstufe zu deklarieren, die Ihr Add-In benötigt, geben Sie einen der Berechtigungswerte im Manifest an. Das Markup variiert je nach Art des Manifests.

Kanonischer Name der Berechtigung Manifestname nur für Add-Ins Einheitlicher Manifestname
Beschränkt Restricted Document.Restricted.User
Dokument lesen ReadDocument Document.Read.User
Alle Dokumente lesen ReadAllDocument Document.ReadAll.User
Dokument schreiben WriteDocument Document.Write.User
Dokument lesen/schreiben ReadWriteDocument Document.ReadWrite.User

Wichtig

Wenn Ihr Add-In die anwendungsspezifischen APIs verwendet, deklarieren Sie die Lese-/Schreibberechtigung für Dokumente im Manifest. Diese Anforderung gilt auch, wenn Ihr Code nur Daten liest.

Beispiele für Manifestdeklarationen

  • Einheitliches Manifest für Microsoft 365: Verwenden Sie die "authorization.permissions.resourceSpecific" -Eigenschaft. Im folgenden Beispiel wird die Lese-/Schreibberechtigung für Dokumente angefordert.

    "authorization": {
    "permissions": {
      "resourceSpecific": [
        ...
        {
          "name": "Document.ReadWrite.User",
          "type": "Delegated"
        },
      ]
    }  
},

  • Nur Add-In-Manifest: Verwenden Sie das Permissions-Element des Manifests. Im folgenden Beispiel wird die Lese-/Schreibberechtigung für Dokumente angefordert.

    <Permissions>ReadWriteDocument</Permissions>

Berechtigungsstufen

In der folgenden Tabelle werden die Teilmengen der allgemeinen JavaScript-APIs beschrieben, die jede Berechtigungsstufe aktiviert. Die anwendungsspezifischen APIs werden nicht von dieser Tabelle gesteuert. Sie benötigen immer die Berechtigung zum Lesen/Schreiben von Dokumenten , auch wenn Ihr Add-In nur Daten liest.

Kanonischer Name der Berechtigung Manifestname nur für Add-Ins Einheitlicher Manifestname Aktivierte Teilmenge der allgemeinen APIs
Beschränkt Restricted Document.Restricted.User Die Methoden des Settings-Objekts und die Document.getActiveViewAsync-Methode. Dies ist die Mindestberechtigungsstufe, die ein Add-In anfordern kann.
Dokument lesen ReadDocument Document.Read.User Zusätzlich zu den APIs, die durch die eingeschränkte Berechtigung zulässig sind, fügt diese Ebene Zugriff auf die APIs hinzu, um das Dokument zu lesen und Bindungen zu verwalten. Dieser Zugriff umfasst die Verwendung von:
Alle Dokumente lesen ReadAllDocument Document.ReadAll.User Zusätzlich zu den APIs, die durch die eingeschränkten Und Leseberechtigungen für Dokumente zulässig sind, ermöglicht diese Ebene die Methoden Document.getSelectedDataAsync und Document.getFileAsync . Diese APIs greifen auf den zugrunde liegenden OOXML-Code des Dokuments zu..
Dokument schreiben WriteDocument Document.Write.User Zusätzlich zu den APIs, die durch die eingeschränkte Berechtigung zulässig sind, fügt diese Ebene Zugriff auf die Document.setSelectedDataAsync-Methode hinzu. Diese Methode schreibt die Auswahl des Benutzers in das Dokument.
Dokument lesen/schreiben ReadWriteDocument Document.ReadWrite.User Zusätzlich zu der API, die durch die Berechtigungen eingeschränktesDokument, Lesen aller Dokumente und Schreiben von Dokumenten zulässig ist, umfasst diese Ebene den Zugriff auf alle verbleibenden APIs, die von Add-Ins unterstützt werden, einschließlich Methoden zum Abonnieren von Ereignissen. Sie müssen die Lese-/Schreibberechtigung für Dokumente deklarieren, um auf diese zusätzlichen APIs zugreifen zu können:

Siehe auch

  • Last updated on