Outlook-Add-In-APIs

Bevor Ihr Outlook-Add-In Nachrichtendaten lesen, Elemente aktualisieren oder externe Dienste aufrufen kann, benötigt es einen Verweis auf die Office.js Bibliothek, einen deklarierten Anforderungssatz und die richtigen Berechtigungen. In diesem Artikel wird erläutert, wie Sie jeden dieser Bausteine konfigurieren und über das Mailbox-Objekt auf die Outlook-API zugreifen.

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://officeapis.public.onecdn.static.microsoft/1/office.js. Add-Ins, die an den Microsoft Marketplace übermittelt werden, müssen von diesem CDN auf Office.js verweisen. Sie können keinen lokalen Bezug 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://officeapis.public.onecdn.static.microsoft/1/office.js" type="text/javascript"></script>

Beim Hinzufügen neuer APIs bleibt die URL zuOffice.js gleich. Wir ändern die Version in der URL nur dann, wenn ein vorhandenes API-Verhalten unterbrochen wird.

Wichtig

Wenn Sie ein Add-In für eine beliebige Office-Clientanwendung entwickeln, verweisen Sie im <head> Abschnitt der Seite auf die 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 für das 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 die neuesten Sätze von APIs, sobald sie veröffentlicht werden. Wenn jedoch ein Outlook-Client die Unterstützung für einen Anforderungssatz deklariert, werden alle APIs in diesem Anforderungssatz unterstützt.

Um zu steuern, auf welchen Outlook-Clients das Add-In angezeigt wird, geben Sie im Manifest eine Mindestversion für den Anforderungssatz an. Wenn Sie beispielsweise Version 1.3 für den Anforderungssatz angeben, wird das Add-In nicht in Outlook-Clients angezeigt, die nicht die Mindestversion 1.3 unterstützen.

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 größer ist als der im Manifest angegebene, können Sie Standard-JavaScript verwenden. Der folgende Code prüft getItemIdAsyncz. B. auf , für das der Postfachanforderungssatz 1.8 erforderlich ist, bevor er aufgerufen wird.

// Check whether a Mailbox 1.8 API is available before calling it.
if (Office.context.mailbox.item.getItemIdAsync) {
    Office.context.mailbox.item.getItemIdAsync((result) => {
        if (result.status === Office.AsyncResultStatus.Succeeded) {
            console.log("Item ID:", result.value);
        }
    });
}

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 die im Manifest festgelegte Anforderung an. Das Markup variiert je nach verwendetem Manifest.

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

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 Berechtigungsstufen: eingeschränkt, Element lesen, Element lesen/schreiben undPostfach lesen/schreiben. 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. Für den Zugriff auf die Objekte und Elemente zur Verwendung in Outlook-Add-Ins, z. B. das Item-Objekt im Erstellungs- oder Lesemodus, verwenden Sie die Mailbox-Eigenschaft des Context-Objekts , um auf das Mailbox-Objekt zuzugreifen. Hier ein Beispielcode:

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

Wichtig

Beachten Sie beim Aufrufen Office.context.mailbox.item einer Nachricht, dass der Lesebereich im Outlook-Client aktiviert sein muss. Anleitungen zum Konfigurieren des Lesebereichs finden Sie unter Verwenden und Konfigurieren des Lesebereichs für die Vorschau von Nachrichten.

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.

Informationen zur Verwendung von JavaScript in Outlook-Add-Ins finden Sie unter Outlook-Add-Ins. Informationen zum Outlook JavaScript-API finden Sie auf der Referenzseite zur Outlook-API .

Siehe auch

  • Zuletzt aktualisiert um