Outlook-Add-In-APIs

  • Artikel

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. Sie verwenden hauptsächlich die Office-JavaScript-APIs, die über das Mailbox-Objekt verfügbar gemacht werden.

Office.js-Bibliothek

Für die Interaktion mit der Outlook-Add-In-API müssen Sie die JavaScript-APIs in Office.js verwenden. Das Content Delivery Network (CDN) für die Bibliothek ist https://appsforoffice.microsoft.com/lib/1/hosted/Office.js. An AppSource übermittelte Add-Ins müssen anhand dieses CDNs auf „Office.js“ verweisen; sie können keinen lokalen Verweis verwenden.

Verweisen Sie auf das CDN im <script>-Tag im <head>-Tag der Webseite (HTML-, ASPX- oder PHP-Datei), die die Benutzeroberfläche Ihres Add-Ins implementiert.

<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-Clientanwendung entwickeln, verweisen Sie im Abschnitt der Seite auf die <head> Office JavaScript-API. Dadurch wird sichergestellt, dass die API vor Elementen des Textkörpers vollständig initialisiert wird.

Anforderungssätze

Alle Outlook-APIs gehören zum Anforderungssatz Postfach. Der Mailbox-Anforderungssatz verfügt über Versionen, und jeder neuen Satz von APIs, den wir veröffentlichen, gehört zu einer höheren Version des Satzes. Nicht alle Outlook-Clients unterstützen den neuesten Satz von APIs, wenn sie veröffentlicht 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 welchen Outlook-Clients das Add-In angezeigt wird, geben Sie eine Mindestanforderungssatzversion im Manifest an. Wenn Sie beispielsweise die Anforderungssatzversion 1.3 angeben, wird das Add-In in keinem Outlook-Client angezeigt, der keine Mindestversion von 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 Features Ihres Add-Ins nicht funktionieren. Sie geben den Anforderungssatz im Manifest an. Das Markup variiert je nach verwendetem Manifest.

  • XML-Manifest: Verwenden Sie das <Requirements-Element> . Beachten Sie, dass das <untergeordnete Methods-Element> von <Requirements> in Outlook-Add-Ins nicht unterstützt wird, sodass Sie keine Unterstützung für bestimmte Methoden deklarieren können.
  • Einheitliches Manifest für Microsoft 365 (Vorschau): Verwenden Sie die Eigenschaft "extensions.capabilities".

Weitere Informationen finden Sie unter Office-Add-In-Manifeste und Grundlegendes zu Outlook-API-Anforderungssätzen.

Berechtigungen

Ihr Add-In benötigt die entsprechenden Berechtigungen, damit die erforderlichen APIs verwendet werden können. Im Allgemeinen sollten Sie die niedrigste Berechtigungsstufe angeben, die für Ihr Add-In erforderlich ist.

Es gibt vier Berechtigungsebenen; eingeschränkt, Element lesen, Element lesen/schreiben Element und Lese-/Schreibpostfach. Weitere Informationen finden Sie hier. Weitere Einzelheiten finden Sie unter Angeben von Berechtigungen für den Outlook-Add-In-Zugriff auf die Benutzerpostfächer.

Objekt „Postfach“

Outlook-Add-Ins verwenden hauptsächlich eine Untergruppe der API, die über das Mailbox-Objekt zur Verfügung gestellt wird. Um auf die Objekte und Elemente zuzugreifen, die speziell für die Verwendung in Outlook-Add-Ins wie dem Item-Objekt verwendet werden, verwenden Sie die mailbox-Eigenschaft des Context-Objekts , um auf das Mailbox-Objekt zuzugreifen, wie in der folgenden Codezeile gezeigt.

// Access the Item object.
const item = Office.context.mailbox.item;

Darüber hinaus können Outlook-Add-Ins die folgenden Objekte verwenden.

  • Office-Objekt: zur Initialisierung.

  • Context-Objekt: für Zugriff auf die Inhalts- und Anzeigespracheneigenschaften.

  • RoamingSettings-Objekt: zum Speichern von Outlook-Add-In-spezifischen benutzerdefinierten Einstellungen für das Postfach des Benutzers, in dem das Add-In installiert ist.

Informationen zum Verwenden von JavaScript in Mail-Apps für Outlook finden Sie unter Outlook-Add-Ins.

Siehe auch