Freigeben über

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.

  • Einheitliches Manifest für Microsoft 365: Verwenden Sie die "authorization.permissions.resourceSpecific" -Eigenschaft. Im folgenden Beispiel wird die Berechtigung zum Schreiben von Dokumenten angefordert, die nur Methoden zulässt, die in das Dokument schreiben (aber nicht lesen) können.

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

    Hinweis

    Das einheitliche Manifest für Microsoft 365 kann in Outlook-Produktions-Add-Ins verwendet werden. Es ist nur als Vorschau für Excel-, PowerPoint- und Word-Add-Ins verfügbar.

  • Nur Add-In-Manifest: Verwenden Sie das Permissions-Element des Manifests. Im folgenden Beispiel wird die Berechtigung zum Schreiben von Dokumenten angefordert, die nur Methoden zulässt, die in das Dokument schreiben (aber 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 beispielsweise nur Daten im Dokument eines Benutzers für seine Features lesen muss, sollten Sie nicht mehr als die Berechtigung zum Lesen von Dokumenten anfordern.

In der folgenden Tabelle werden die Teilmengen der allgemeinen und anwendungsspezifischen JavaScript-APIs beschrieben, die von jeder Berechtigungsstufe aktiviert werden.

Kanonischer Name der Berechtigung Manifestname nur für Add-Ins Einheitlicher Manifestname Aktivierte Teilmenge der anwendungsspezifischen APIs Aktivierte Teilmenge der allgemeinen APIs
eingeschränkt Restricted Document.Restricted.User Keine Die Methoden des Settings-Objekts und die Document.getActiveViewAsync-Methode. Dies ist die Minimale Berechtigungsstufe, die von einem Add-In angefordert werden kann.
Dokument lesen ReadDocument Document.Read.User Alle und nur APIs, die das Dokument oder seine Eigenschaften lesen. Zusätzlich zur API, die durch die eingeschränkte Berechtigung zulässig ist, wird der Zugriff auf die API-Member hinzugefügt, die zum Lesen des Dokuments und zum Verwalten von Bindungen erforderlich sind. Dies umfasst die Verwendung von Folgendem:
Alle Dokumente lesen ReadAllDocument Document.ReadAll.User Identisch mit lesegeschütztem Dokument. Zusätzlich zu der API, die durch die eingeschränkten und leseberechtigungen für Dokumente 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).
Dokument schreiben WriteDocument Document.Write.User Alle und nur APIs, die in das Dokument oder seine Eigenschaften schreiben. Zusätzlich zur API, die durch die eingeschränkte Berechtigung zulässig ist, wird zugriff auf die folgenden API-Member hinzugefügt.
Dokument lesen/schreiben ReadWriteDocument Document.ReadWrite.User Alle anwendungsspezifischen APIs, einschließlich der APIs, die Ereignisse abonnieren. Zusätzlich zu der API, die durch die Berechtigungen "EingeschränktesDokument lesen", "Alle Dokumente lesen" und " Dokument schreiben " zulässig ist, umfasst der Zugriff auf alle verbleibenden von Add-Ins unterstützten API, einschließlich Methoden zum Abonnieren von Ereignissen. Sie müssen die Lese-/Schreibberechtigung für Dokumente deklarieren, um auf diese zusätzlichen API-Member zuzugreifen:

Siehe auch