Outlook-Add-In-APIs

Um APIs in Ihrem Outlook-Add-In zu verwenden, müssen Sie den Speicherort der Office.js-Bibliothek, den Anforderungssatz, das Schema und die Berechtigungen angeben.

Office.js-Bibliothek

Um mit der Outlook-Add-In-API zu interagieren, müssen Sie die JavaScript-APIs in Office.js verwenden. Das CDN für die Bibliothek ist https://appsforoffice.microsoft.com/lib/1/hosted/Office.js. Add-Ins, die an den Office Store übermittelt werden, müssen anhand dieses CDN auf „Office.js“ verweisen, sie können keinen lokalen Verweis verwenden.

Deklarieren Sie das CDN im head-Tag der Webseite (HTML-, ASPX- oder PHP-Datei), die die Benutzeroberfläche Ihres Add-Ins implementiert, im src-Attribut des script-Tags:

<script src="https://appsforoffice.microsoft.com/lib/1/hosted/Office.js" type="text/javascript"></script>

Beim Hinzufügen neuer APIs bleibt die URL zuOffice.js gleich. Die Version in der URL wird nur geändert, wenn eines bestehendes API-Verhalten unterbrochen werden soll.

Wichtig: Wenn Sie ein Add-In für eine beliebige Office-Host-Anwendung entwickeln, verweisen Sie von innerhalb des Abschnitts <head> der Seite auf die JavaScript-API für Office. Dadurch wird sichergestellt, dass die API vor Elementen des Textkörpers vollständig initialisiert wird. Office-Hosts erfordern, dass Add-Ins innerhalb von 5 Sekunden nach Aktivierung initialisiert werden. Bei Überschreitung dieses Grenzwerts wird das Add-In als reaktionsunfähig deklariert und dem Benutzer eine Fehlermeldung angezeigt.

Anforderungssätze

Alle Outlook-APIs gehören zu dem Postfachanforderungssatz. Der Postfachanforderungssatz weist Versionen auf, und jeder neue Satz von APIs, der veröffentlicht wird, gehört zu einer höheren Version des Satzes. Nicht alle Outlook-Clients unterstützen den neuesten Satz von APIs, wenn diese freigegeben werden, aber wenn ein Outlook-Client Unterstützung für einen Anforderungssatz deklariert, unterstützt er alle APIs in diesem Anforderungssatz.

Um zu steuern, in welchem Outlook-Client das Add-In angezeigt wird, legen Sie eine Mindestanforderungssatzversion im Manifest fest. Wenn Sie z. B. Anforderungssatzversion 1.3 angeben, wird das Add-In nicht in einem Outlook-Client angezeigt, der nicht mindestens Version 1.3 unterstützt.

Die Angabe eines Anforderungssatzes beschränkt das Add-In nicht auf die APIs in dieser Version. Gibt das Add-In den Anforderungssatz v1.1 an, wird aber in einem Outlook-Client ausgeführt, der v1.3 unterstützt, dann kann es trotzdem APIs der Version 1.3 verwenden. Der Anforderungssatz steuert nur, in welchen Outlook-Clients das Add-In angezeigt wird.

Um die Verfügbarkeit von APIs aus einem Anforderungssatz zu überprüfen, der höher als der im Manifest angegebene ist, können Sie standardmäßiges JavaScript verwenden:

if (item.somePropertyOrFunction) {
   item.somePropertyOrFunction...  
}

Hinweis: Für APIs, die sich in der im Manifest angegebenen Version des Anforderungssatzes befinden, sind solche Überprüfungen nicht erforderlich.

Geben Sie den minimalen Anforderungssatz an, der den kritischen Satz von APIs für Ihr Szenario unterstützt, ohne den die Features des Add-Ins nicht funktionieren. Der Anforderungssatz im Manifest wird in den Elementen Requirements, Sets und Set angegeben. Weitere Informationen finden Sie unter Outlook-Add-In-Manifeste und Grundlegendes zu Outlook-API-Anforderungssätzen.

Das Element Methods gilt nicht für Outlook-Add-Ins. Deshalb können Sie keine Unterstützung für bestimme Methoden deklarieren.

Berechtigungen

Ihr Add-In benötigt die entsprechenden Berechtigungen, damit die erforderlichen APIs verwendet werden können. Es gibt vier Stufen von Berechtigungen. Weitere Einzelheiten finden Sie unter Angeben von Berechtigungen für den Outlook-Add-In-Zugriff auf die Benutzerpostfächer.

Berechtigungsstufe Beschreibung
Eingeschränkt Ermöglicht die Verwendung von Entitäten, jedoch nicht von regulären Ausdrücken.
Element lesen Verleiht zusätzlich zu den von Restricted zugelassenen die folgenden Berechtigungen:
  • Reguläre Ausdrücke
  • Lesezugriff auf Outlook-Add-in-API
  • Abrufen der Elementeigenschaften und des Rückruftokens
Lese-/Schreibzugriff Verleiht zusätzlich zu den von Read item zugelassenen die folgenden Berechtigungen:
  • voller Zugriff auf Outlook-Add-In-API mit Ausnahme von makeEwsRequestAsync
  • Festlegen der Elementeigenschaften
Postfach lesen/schreiben Verleiht zusätzlich zu den von Read/write zugelassenen die folgenden Berechtigungen:
  • Erstellen, Lesen und Schreiben von Elementen und Ordnern
  • Senden von Elementen
  • Aufrufen von makeEwsRequestAsync

Im Allgemeinen sollten Sie die niedrigste Berechtigungsstufe angeben, die für Ihr Add-In erforderlich ist. Berechtigungen werden im Permissions-Element im Manifest deklariert. Weitere Informationen finden Sie unter Outlook-Add-In-Manifeste. Informationen zu Sicherheitsproblemen finden Sie unter Datenschutz, Berechtigungen und Sicherheit für Office-Add-Ins.

Zusätzliche Ressourcen