Outlook-Add-In-APIsOutlook 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.To use APIs in your Outlook Add-in, you must specify the location of the Office.js library, the requirement set, the schema, and the permissions.

Office.js-BibliothekOffice.js library

Um mit der Outlook-Add-In-API zu interagieren, müssen Sie die JavaScript-APIs in Office.js verwenden.To interact with the Outlook Add-in API, you need to use the JavaScript APIs in Office.js. Das CDN für die Bibliothek ist https://appsforoffice.microsoft.com/lib/1/hosted/Office.js.The CDN for the library is 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.Add-ins submitted to the Office Store must reference Office.js by this CDN; they can't use a local reference.

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.Reference the CDN in a <script> tag in the <head> tag of the web page (.html, .aspx, or .php file) that implements the UI of your add-in.

<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.As we add new APIs, the URL to Office.js will stay the same. We will change the version in the URL only if we break an existing API behavior.

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.When developing an add-in for any Office host application, reference the JavaScript API for Office from inside the <head> section of the page. Dadurch wird sichergestellt, dass die API vor Elementen des Textkörpers vollständig initialisiert wird.This ensures that the API is fully initialized prior to any body elements. Office-Hosts erfordern, dass Add-Ins innerhalb von 5 Sekunden nach Aktivierung initialisiert werden.Office hosts require that add-ins initialize within 5 seconds of activation. Bei Überschreitung dieses Grenzwerts wird das Add-In als reaktionsunfähig deklariert und dem Benutzer eine Fehlermeldung angezeigt.Crossing this threshold results in the add-in being declared unresponsive and an error message is displayed to the user.

AnforderungssätzeRequirement sets

Alle Outlook-APIs gehören zum Mailbox-Anforderungssatz.All Outlook APIs belong to the Mailbox requirement set. 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.The Mailbox requirement set has versions, and each new set of APIs that are released belongs to a higher version of the set. 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.Not all Outlook clients will support the newest set of APIs when they are released, but if an Outlook client declares support for a requirement set, it will support all the APIs in that requirement set.

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.To control which Outlook clients the add-in appears in, specify a minimum requirement set version in the manifest. For example, if you specify requirement set version 1.3, the add-in will not show up in any Outlook client that doesn't support a minimum version of 1.3.

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.Specifying a requirement set doesn't limit your add-in to the APIs in that version. If the add-in specifies requirement set v1.1 but is running in an Outlook client that supports v1.3, the add-in can still use v1.3 APIs. The requirement set only controls which Outlook clients the add-in appears in.

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:To check the availability of any APIs from a requirement set greater than the one specified in the manifest, you can use standard JavaScript:

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.These checks are not needed for any APIs that are in the requirement set version specified in the manifest.

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.Specify the minimum requirement set that supports the critical set of APIs for your scenario, without which features of your add-in won't work. Der Anforderungssatz im Manifest wird im <Requirements>-Element angegeben.You specify the requirement set in the manifest in the <Requirements> element. Weitere Informationen finden Sie unter Outlook-Add-In-Manifeste und Grundlegendes zu Outlook-API-Anforderungssätzen.For more information, see Outlook Add-in manifests and Understanding Outlook API requirement sets.

Das <Methods>-Element gilt nicht für Outlook-Add-Ins. Deshalb können Sie keine Unterstützung für bestimme Methoden deklarieren.The <Methods> element doesn't apply to Outlook Add-ins, so you can't declare support for specific methods.

BerechtigungenPermissions

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.Your add-in requires the appropriate permissions to use the APIs that it needs. There are four levels of permissions. For more details, see Understanding Outlook Add-in permissions.

BerechtigungsstufePermission level BeschreibungDescription
RestrictedRestricted Ermöglicht die Verwendung von Entitäten, jedoch nicht von regulären Ausdrücken.Allows use of entities but not regular expressions.
Read itemRead item Verleiht zusätzlich zu den von Restricted zugelassenen die folgenden Berechtigungen:In addition to what is allowed in Restricted, it allows:
  • Reguläre Ausdrückeregular expressions
  • Lesezugriff auf Outlook-Add-in-APIOutlook Add-in API read access
  • Abrufen der Elementeigenschaften und des Rückruftokensgetting the item properties and the callback token
Read/writeRead/write Verleiht zusätzlich zu den von Read item zugelassenen die folgenden Berechtigungen:In addition to what is allowed in Read item, it allows:
  • voller Zugriff auf Outlook-Add-In-API mit Ausnahme von makeEwsRequestAsyncfull Outlook Add-in API access except makeEwsRequestAsync
  • Festlegen der Elementeigenschaftensetting the item properties
Read/write mailboxRead/write mailbox Verleiht zusätzlich zu den von Read/write zugelassenen die folgenden Berechtigungen:In addition to what is allowed in Read/write, it allows:
  • Erstellen, Lesen und Schreiben von Elementen und Ordnerncreating, reading, writing items and folders
  • Senden von Elementensending items
  • Aufrufen von makeEwsRequestAsynccalling makeEwsRequestAsync

Im Allgemeinen sollten Sie die niedrigste Berechtigungsstufe angeben, die für Ihr Add-In erforderlich ist.In general, you should specify the minimum permission needed for your add-in. Berechtigungen werden im <Permissions>-Element im Manifest deklariert.Permissions are declared in the <Permissions> element in the manifest. Weitere Informationen finden Sie unter Outlook-Add-In-Manifeste.For more information, see Outlook Add-in manifests. Informationen zu Sicherheitsproblemen finden Sie unter Datenschutz, Berechtigungen und Sicherheit für Office-Add-Ins.For information about security issues, see Privacy, permissions, and security for Office add-ins.

Siehe auchSee also