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 permissions 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. Das CDN für die Bibliothek lautet https://appsforoffice.microsoft.com/lib/1/hosted/Office.js. Add-Ins, die an den Office Store gesendet werden, müssen Office.js mit diesem CDN referenzieren. Sie können keine lokale Referenz verwenden.To interact with the Outlook add-in API, you need to use the JavaScript APIs in Office.js. The CDN for the library is https://appsforoffice.microsoft.com/lib/1/hosted/Office.js. 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 in einem <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>

Wenn wir neue APIs hinzufügen, bleibt die URL zu Office.js gleich. Wir werden die Version in der URL nur ändern, wenn wir ein bestehendes API-Verhalten unterbrechen.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-Anwendung entwickeln, verweisen Sie auf die JavaScript-API für Office im Abschnitt <head> der Seite. Dadurch wird sichergestellt, dass die API vor allen Textkörper-Elementen vollständig initialisiert wird. Office Hosts erfordern, dass Add-Ins innerhalb von 5 Sekunden nach der Aktivierung initialisiert werden. Das Überschreiten dieses Schwellenwerts führt dazu, dass das Add-In als nicht reagierend erklärt und dem Benutzer eine Fehlermeldung angezeigt wird.When developing an add-in for any Office host application, reference the JavaScript API for Office from inside the <head> section of the page. This ensures that the API is fully initialized prior to any body elements. Office hosts require that add-ins initialize within 5 seconds of activation. Crossing this threshold results in the add-in being declared unresponsive and an error message is displayed to the user.

Anforderungs-GruppenRequirement sets

Alle Outlook-APIs gehören zum Anforderungssatz Mailbox. Der Anforderungssatz Mailbox hat Versionen, und jeder neue Satz von APIs, der freigegeben wird, 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 die Unterstützung für einen Anforderungssatz erklärt, unterstützt er alle APIs in diesem Anforderungssatz.All Outlook APIs belong to the Mailbox requirement set. The Mailbox requirement set has versions, and each new set of APIs that are released belongs to a higher version of the set. 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, 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 Mindestanforderungssatz an, der den kritischen Satz von APIs für Ihr Szenario unterstützt, ohne den die Funktionen Ihres Add-Ins nicht funktionieren. Die im Manifest festgelegte Anforderung geben Sie im Element <Requirements> an. Weitere Informationen finden Sie unter Outlook Add-In Manifeste und Understanding Outlook API Requirements Sets.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. You specify the requirement set in the manifest in the <Requirements> element. For more information, see Outlook add-in manifests and Understanding Outlook API requirement sets.

Das <Methods> Element wird nicht für Outlook-Add-Ins angewendet. 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 erforderlichen Berechtigungen, um die von ihm benötigten APIs zu verwenden. Es gibt vier Stufen von Berechtigungen. Weitere Informationen finden Sie unter Outlook Add-In-Berechtigungen verstehen.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
EingeschränktRestricted Ermöglicht die Verwendung von Entitäten, jedoch nicht von regulären Ausdrücken.Allows use of entities but not regular expressions.
Element lesenRead 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
Postfach lesen/schreibenRead/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 Mindestberechtigung, die für Ihr Add-In benötigt wird, angeben. Berechtigungen werden im Element <Permissions> 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.In general, you should specify the minimum permission needed for your add-in. Permissions are declared in the <Permissions> element in the manifest. For more information, see Outlook add-in manifests. For information about security issues, see Privacy, permissions, and security for Office Add-ins.

Siehe auchSee also