Office. Mailbox interface

MessageCompose, MessageRead, AppointmentCompose, AppointmentRead

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Compose oder Lesen

Wichtig:

Ihre App muss über die im Manifest angegebene Berechtigung zum Lesen von Elementen verfügen, um das ewsUrl Element im Lesemodus aufrufen zu können.
Im Verfassenmodus müssen Sie die saveAsync -Methode aufrufen, bevor Sie den ewsUrl Member verwenden können. Ihre App muss über Lese-/Schreibberechtigungen für Elemente verfügen, um die saveAsync -Methode aufrufen zu können.
Diese Eigenschaft wird in Outlook unter Android oder iOS nicht unterstützt. Weitere Informationen zu unterstützten APIs in Outlook Mobile finden Sie unter In Outlook unterstützte JavaScript-APIs auf mobilen Geräten.
Der ewsUrl Wert kann von einem Remotedienst verwendet werden, um EWS-Aufrufe an das Postfach des Benutzers zu tätigen. Sie können beispielsweise einen Remotedienst erstellen, um Anlagen aus dem ausgewählten Element abzurufen.

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-and-service-calls/ids-and-urls.yaml

// Get the EWS URL and EWS item ID.
console.log("EWS URL: " + Office.context.mailbox.ewsUrl);
const ewsId = Office.context.mailbox.item.itemId;
console.log("EWS item ID: " + Office.context.mailbox.item.itemId);

// Convert the EWS item ID to a REST-formatted ID.
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
console.log("REST item ID: " + restId);

// Convert the REST-formatted ID back to an EWS-formatted ID.
const ewsId2 = Office.context.mailbox.convertToEwsId(restId, Office.MailboxEnums.RestVersion.v2_0);
console.log("EWS ID (from REST ID): " + ewsId2);

item

Das Postfachelement. Je nach Kontext, in dem das Add-In geöffnet wurde, kann der Elementtyp variieren. Wenn IntelliSense nur für einen bestimmten Typ oder Modus angezeigt werden soll, wandeln Sie dieses Element in eine der folgenden Elemente um:

Wichtig:

Beachten Sie beim Aufrufen Office.context.mailbox.item einer Nachricht, dass der Lesebereich im Outlook-Client aktiviert sein muss. Eine Anleitung zum Konfigurieren des Lesebereichs finden Sie unter Verwenden und Konfigurieren des Lesebereichs für die Vorschau von Nachrichten.
item kann NULL sein, wenn Das Add-In das Anheften des Aufgabenbereichs unterstützt. Ausführliche Informationen zur Behandlung finden Sie unter Implementieren eines anheftbaren Aufgabenbereichs in Outlook.

item?: Item & ItemCompose & ItemRead & Message & MessageCompose & MessageRead & Appointment & AppointmentCompose & AppointmentRead;

Eigenschaftswert

Office.Item & Office.ItemCompose & Office.ItemRead & Office.Message & Office.MessageCompose & Office.MessageRead & Office.Appointment & Office.AppointmentCompose & Office.AppointmentRead

masterCategories

Ruft ein -Objekt ab, das Methoden zum Verwalten der Kategorien master Liste bereitstellt, die einem Postfach zugeordnet ist.

masterCategories: MasterCategories;

Eigenschaftswert

Office.MasterCategories

Hinweise

[ API-Satz: Postfach 1.8 ]

Minimale Berechtigungsstufe: Postfach lesen/schreiben

Anwendbarer Outlook-Modus: Compose oder Lesen

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/45-categories/work-with-master-categories.yaml

Office.context.mailbox.masterCategories.getAsync(function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    const categories = asyncResult.value;
    if (categories && categories.length > 0) {
      console.log("Master categories:");
      console.log(JSON.stringify(categories));
    } else {
      console.log("There are no categories in the master list.");
    }
  } else {
    console.error(asyncResult.error);
  }
});

...

const masterCategoriesToAdd = [
  {
    displayName: "TestCategory",
    color: Office.MailboxEnums.CategoryColor.Preset0
  }
];

Office.context.mailbox.masterCategories.addAsync(masterCategoriesToAdd, function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Successfully added categories to master list");
  } else {
    console.log("masterCategories.addAsync call failed with error: " + asyncResult.error.message);
  }
});

...

const masterCategoriesToRemove = ["TestCategory"];

Office.context.mailbox.masterCategories.removeAsync(masterCategoriesToRemove, function(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    console.log("Successfully removed categories from master list");
  } else {
    console.log("masterCategories.removeAsync call failed with error: " + asyncResult.error.message);
  }
});

restUrl

Ruft die URL des REST-Endpunkts für das betreffende E-Mail-Konto ab.

restUrl: string;

Eigenschaftswert

string

Hinweise

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Compose oder Lesen

Wichtig:

Die Outlook REST v2.0- und Beta-Endpunkte sind jetzt veraltet. Privat veröffentlichte und von AppSource gehostete Add-Ins können den REST-Dienst jedoch verwenden, bis der erweiterte Support für Outlook 2019 am 14. Oktober 2025 endet. Datenverkehr von diesen Add-Ins wird automatisch als Ausnahme identifiziert. Diese Ausnahme gilt auch für neue Add-Ins, die nach dem 31. März 2024 entwickelt wurden. Obwohl Add-Ins den REST-Dienst bis 2025 verwenden können, empfehlen wir Ihnen dringend, Ihre Add-Ins zur Verwendung von Microsoft Graph zu migrieren. Eine Anleitung finden Sie unter Vergleichen von Microsoft Graph- und Outlook-REST-API-Endpunkten.
Ihr Add-In muss über die berechtigung zum Lesen von Elementen verfügen, die im Manifest angegeben ist, um das restUrl Element im Lesemodus aufzurufen.
Im Verfassenmodus müssen Sie die saveAsync-Methode aufrufen, bevor Sie das restUrl-Element verwenden können. Ihr Add-In muss über Lese-/Schreibberechtigungen für Elemente verfügen, um die saveAsync -Methode aufrufen zu können. In Delegat- oder freigegebenen Szenarien sollten Sie jedoch stattdessen die targetRestUrl -Eigenschaft des SharedProperties-Objekts verwenden (eingeführt in Anforderungssatz 1.8). Weitere Informationen finden Sie im Artikel freigegebene Ordner und freigegebene Postfächer .

Beispiele

// Get the URL of the REST endpoint.
const restUrl = Office.context.mailbox.restUrl;
console.log(`REST API URL: ${restUrl}`);

userProfile

Informationen zum Benutzer, der dem Postfach zugeordnet ist. Dies umfasst den Kontotyp, den Anzeigenamen, die E-Mail-Adresse und die Zeitzone.

Weitere Informationen findest du unter Office.UserProfile.

userProfile: UserProfile;

Eigenschaftswert

Office.UserProfile

Details zur Methode

addHandlerAsync(eventType, handler, options, callback)

Fügt einen Ereignishandler für ein unterstütztes Ereignis hinzu. Hinweis: Ereignisse sind nur bei der Implementierung des Aufgabenbereichs verfügbar.

Informationen zu unterstützten Ereignissen finden Sie im Abschnitt Ereignisse des Postfachobjektmodells.

addHandlerAsync(eventType: Office.EventType | string, handler: any, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameter

eventType: Office.EventType | string

Das Ereignis, das den Handler aufrufen soll

handler: any

Die Funktion, die das Ereignis behandeln soll. Die Funktion muss einen einzigen Parameter akzeptieren (ein Objektliteral). Die type -Eigenschaft für den -Parameter entspricht dem parameter, der eventType an addHandlerAsyncübergeben wird.

options: Office.AsyncContextOptions

Bietet eine Option zum Beibehalten von Kontextdaten eines beliebigen Typs , unverändert, für die Verwendung in einem Rückruf.

callback: (asyncResult: Office.AsyncResult<void>) => void

Optional. Wenn die -Methode abgeschlossen ist, wird die im callback -Parameter übergebene Funktion mit einem einzelnen Parameter vom Typ Office.AsyncResultaufgerufen.

Gibt zurück

void

Hinweise

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Compose oder Lesen

Beispiele

Office.onReady(() => {
    document.addEventListener('DOMContentLoaded', () => {
        // Get a reference to the mailbox and use it to add an event handler.
        const mailbox = Office.context.mailbox;
        mailbox.addHandlerAsync(Office.EventType.ItemChanged, loadNewItem, (result) => {
            if (result.status === Office.AsyncResultStatus.Failed) {
                // Handle error.
            }
        });
    });
});

function loadNewItem(eventArgs) {
    const item = Office.context.mailbox.item;

    // Check that item isn't null.
    if (item !== null) {
        // Work with item. For example, define and call a function that
        // loads the properties of the newly selected item.
        loadProps(item);
    }
}

addHandlerAsync(eventType, handler, callback)

Fügt einen Ereignishandler für ein unterstütztes Ereignis hinzu. Hinweis: Ereignisse sind nur bei der Implementierung des Aufgabenbereichs verfügbar.

Informationen zu unterstützten Ereignissen finden Sie im Abschnitt Ereignisse des Postfachobjektmodells.

addHandlerAsync(eventType: Office.EventType | string, handler: any, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameter

eventType: Office.EventType | string

Das Ereignis, das den Handler aufrufen soll

handler: any

callback: (asyncResult: Office.AsyncResult<void>) => void

Optional. Wenn die -Methode abgeschlossen ist, wird die im callback -Parameter übergebene Funktion mit einem einzelnen Parameter vom Typ Office.AsyncResultaufgerufen.

Gibt zurück

void

Hinweise

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Compose oder Lesen

convertToEwsId(id, restVersion)

Konvertiert eine unterstützte ID in das EWS-Format (Exchange-Webdienste).

convertToEwsId(id: string, restVersion: MailboxEnums.RestVersion | string): string;

Parameter

id: string

Die ID, die in das EWS-Format konvertiert werden soll. Bei dieser Zeichenfolge kann es sich um eine Element-ID handeln, die für die Outlook-REST-APIs formatiert ist, oder um eine konversations-ID, die aus Office.context.mailbox.item.conversationIdabgerufen wurde.

restVersion: Office.MailboxEnums.RestVersion | string

Ein Wert, der die Version der Outlook-REST-API angibt, die zum Abrufen der Element-ID verwendet wurde.

Gibt zurück

string

Hinweise

[ API-Satz: Postfach 1.3 ]

Mindestberechtigungsstufe: eingeschränkt

Anwendbarer Outlook-Modus: Compose oder Lesen

Wichtig:

Im Oktober 2024 werden ältere Exchange-Benutzeridentitäts- und -Rückruftoken für alle Exchange Online Mandanten standardmäßig deaktiviert. Dies ist Teil der Secure Future Initiative von Microsoft, die Organisationen die Tools zur Verfügung stellt, die sie benötigen, um auf die aktuelle Bedrohungslandschaft zu reagieren. Exchange-Benutzeridentitätstoken funktionieren weiterhin für lokale Exchange-Instanzen. Die Authentifizierung geschachtelter Apps ist der empfohlene Ansatz für token in Zukunft. Weitere Informationen finden Sie in unserem Blogbeitrag und in den häufig gestellten Fragen.
Diese Methode wird in Outlook unter Android oder iOS nicht unterstützt. Weitere Informationen zu unterstützten APIs in Outlook Mobile finden Sie unter In Outlook unterstützte JavaScript-APIs auf mobilen Geräten.
Element-IDs, die über eine REST-API (z. B. Microsoft Graph) abgerufen werden, verwenden ein anderes Format als das von EWS verwendete Format. Die convertToEwsId -Methode konvertiert eine REST-formatierte ID in das richtige Format für EWS.

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-and-service-calls/ids-and-urls.yaml

// Get the EWS URL and EWS item ID.
console.log("EWS URL: " + Office.context.mailbox.ewsUrl);
const ewsId = Office.context.mailbox.item.itemId;
console.log("EWS item ID: " + Office.context.mailbox.item.itemId);

// Convert the EWS item ID to a REST-formatted ID.
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
console.log("REST item ID: " + restId);

// Convert the REST-formatted ID back to an EWS-formatted ID.
const ewsId2 = Office.context.mailbox.convertToEwsId(restId, Office.MailboxEnums.RestVersion.v2_0);
console.log("EWS ID (from REST ID): " + ewsId2);

convertToLocalClientTime(timeValue)

Ruft ein Wörterbuch mit Uhrzeitinformationen basierend auf der Zeiteinstellung des lokalen Clients ab.

Die vom Outlook-Client verwendete Zeitzone variiert je nach Plattform. Outlook unter Windows (klassisch) und auf Mac verwendet die Zeitzone des Clientcomputers. Outlook im Web und neue Outlook unter Windows verwenden die Zeitzone, die im Exchange Admin Center (EAC) festgelegt ist. Sie sollten Datums- und Uhrzeitwerte bearbeiten, damit die auf der Benutzeroberfläche angezeigten Werte immer den von Benutzer erwarteten Zeitzonen entsprechen.

In Outlook für Windows (klassisch) und auf Mac gibt die convertToLocalClientTime Methode ein Wörterbuchobjekt mit den Werten zurück, die auf die Zeitzone des Clientcomputers festgelegt sind. In Outlook im Web und dem neuen Outlook unter Windows gibt die convertToLocalClientTime Methode ein Wörterbuchobjekt mit den Werten zurück, die auf die im EAC angegebene Zeitzone festgelegt sind.

convertToLocalClientTime(timeValue: Date): LocalClientTime;

Parameter

timeValue: Date

Ein Date-Objekt.

Gibt zurück

Office.LocalClientTime

Hinweise

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Compose oder Lesen

convertToRestId(id, restVersion)

Konvertiert eine unterstützte ID in das REST-Format.

convertToRestId(id: string, restVersion: MailboxEnums.RestVersion | string): string;

Parameter

id: string

Die ID, die in das REST-Format konvertiert werden soll. Bei dieser Zeichenfolge kann es sich um eine Element-ID handeln, die für EWS formatiert ist und normalerweise von Office.context.mailbox.item.itemIdabgerufen wird, eine Konversations-ID, die vonOffice.context.mailbox.item.conversationId abgerufen wird, oder eine Serien-ID, die von Office.context.mailbox.item.seriesIdabgerufen wird.

restVersion: Office.MailboxEnums.RestVersion | string

Ein Wert, der die Version der Outlook-REST-API angibt, die mit der konvertierten ID verwendet wird.

Gibt zurück

string

Hinweise

[ API-Satz: Postfach 1.3 ]

Mindestberechtigungsstufe: eingeschränkt

Anwendbarer Outlook-Modus: Compose oder Lesen

Wichtig:

Diese Methode wird in Outlook unter Android oder iOS nicht unterstützt. Weitere Informationen zu unterstützten APIs in Outlook Mobile finden Sie unter In Outlook unterstützte JavaScript-APIs auf mobilen Geräten.
Element-IDs, die über Exchange-Webdienste (EWS) oder über die itemId -Eigenschaft abgerufen werden, verwenden ein anderes Format als das format, das von REST-APIs (z. B. Microsoft Graph) verwendet wird. Die convertToRestId -Methode konvertiert eine EWS-formatierte ID in das richtige Format für REST.

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-and-service-calls/ids-and-urls.yaml

// Get the EWS URL and EWS item ID.
console.log("EWS URL: " + Office.context.mailbox.ewsUrl);
const ewsId = Office.context.mailbox.item.itemId;
console.log("EWS item ID: " + Office.context.mailbox.item.itemId);

// Convert the EWS item ID to a REST-formatted ID.
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
console.log("REST item ID: " + restId);

// Convert the REST-formatted ID back to an EWS-formatted ID.
const ewsId2 = Office.context.mailbox.convertToEwsId(restId, Office.MailboxEnums.RestVersion.v2_0);
console.log("EWS ID (from REST ID): " + ewsId2);

convertToUtcClientTime(input)

Ruft ein Date -Objekt aus einem Wörterbuch ab, das Zeitinformationen enthält.

Die convertToUtcClientTime -Methode konvertiert ein Wörterbuch, das ein lokales Datum und eine lokale Uhrzeit enthält, in ein Date -Objekt mit den richtigen Werten für das lokale Datum und die lokale Uhrzeit.

convertToUtcClientTime(input: LocalClientTime): Date;

Parameter

input: Office.LocalClientTime

Der zu konvertierende Wert für die lokale Uhrzeit.

Gibt zurück

Date

Ein Date-Objekt der Uhrzeit in UTC.

Hinweise

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Compose oder Lesen

Beispiele

// Represents 3:37 PM PDT on Monday, August 26, 2019.
const input = {
    date: 26,
    hours: 15,
    milliseconds: 2,
    minutes: 37,
    month: 7,
    seconds: 2,
    timezoneOffset: -420,
    year: 2019
};

// result should be a Date object.
const result = Office.context.mailbox.convertToUtcClientTime(input);

// Output should be "2019-08-26T22:37:02.002Z".
console.log(result.toISOString());

displayAppointmentForm(itemId)

Zeigt einen bestehenden Kalendertermin an.

Die displayAppointmentForm -Methode öffnet einen vorhandenen Kalendertermin in einem neuen Fenster auf dem Desktop.

In Outlook für Mac können Sie diese Methode verwenden, um einen einzelnen Termin anzuzeigen, der nicht Teil einer Serie ist, oder den master Termins einer Serie. Sie können jedoch keine instance der Reihe anzeigen, da Sie nicht auf die Eigenschaften (einschließlich der Element-ID) von Instanzen einer Serie zugreifen können.

In Outlook im Web und dem neuen Outlook unter Windows öffnet diese Methode das angegebene Formular nur, wenn der Text des Formulars kleiner oder gleich 32.000 Zeichen ist.

Wenn der angegebene Elementbezeichner keinen vorhandenen Termin identifiziert, wird auf dem Clientcomputer oder Gerät ein leerer Bereich geöffnet, und es wird keine Fehlermeldung zurückgegeben.

displayAppointmentForm(itemId: string): void;

Parameter

itemId: string

Der EWS-Bezeichner (Exchange Web Services, Exchange-Webdienste) für einen vorhandenen Kalendertermin.

Gibt zurück

void

Hinweise

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Compose oder Lesen

Wichtig: Diese Methode wird in Outlook unter Android oder iOS nicht unterstützt. Weitere Informationen zu unterstützten APIs in Outlook Mobile finden Sie unter In Outlook unterstützte JavaScript-APIs auf mobilen Geräten.

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-existing-appointment.yaml

const itemId = $("#itemId").val();
Office.context.mailbox.displayAppointmentForm(itemId);

displayAppointmentFormAsync(itemId, options, callback)

Zeigt einen bestehenden Kalendertermin an.

Mit der displayAppointmentFormAsync-Methode wird ein vorhandener Kalendertermin auf dem Desktop in einem neuen Fenster oder auf Mobilgeräten in einem Dialogfeld geöffnet.

In Outlook im Web und dem neuen Outlook unter Windows öffnet diese Methode das angegebene Formular nur, wenn der Text des Formulars kleiner oder gleich 32.000 Zeichen ist.

Wenn der angegebene Elementbezeichner keinen vorhandenen Termin identifiziert, wird auf dem Clientcomputer oder Gerät ein leerer Bereich geöffnet, und es wird keine Fehlermeldung zurückgegeben.

Hinweis: Diese Methode wird in Outlook unter iOS oder Android nicht unterstützt.

displayAppointmentFormAsync(itemId: string, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameter

itemId: string

Der EWS-Bezeichner (Exchange Web Services, Exchange-Webdienste) für einen vorhandenen Kalendertermin.

options: Office.AsyncContextOptions

Ein Objektliteral, das eine oder mehrere der folgenden Eigenschaften enthält: asyncContextEntwickler können jedes Objekt bereitstellen, auf das sie in der Rückruffunktion zugreifen möchten.

callback: (asyncResult: Office.AsyncResult<void>) => void

Optional. Wenn die -Methode abgeschlossen ist, wird die im callback -Parameter übergebene Funktion mit einem einzelnen Parameter aufgerufen, asyncResult, der ein Office.AsyncResult -Objekt ist.

Gibt zurück

void

Hinweise

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Compose oder Lesen

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-existing-appointment.yaml

const itemId = $("#itemId").val();

// The async version will return error 9049 if the item is not found.
// The async version is only available starting with requirement set 1.9.
Office.context.mailbox.displayAppointmentFormAsync(itemId, function(asyncResult) {
  console.log("Result: " + JSON.stringify(asyncResult));
});

displayAppointmentFormAsync(itemId, callback)

Zeigt einen bestehenden Kalendertermin an.

Mit der displayAppointmentFormAsync-Methode wird ein vorhandener Kalendertermin auf dem Desktop in einem neuen Fenster oder auf Mobilgeräten in einem Dialogfeld geöffnet.

In Outlook im Web und dem neuen Outlook unter Windows öffnet diese Methode das angegebene Formular nur, wenn der Text des Formulars kleiner oder gleich 32.000 Zeichen ist.

Wenn der angegebene Elementbezeichner keinen vorhandenen Termin identifiziert, wird auf dem Clientcomputer oder Gerät ein leerer Bereich geöffnet, und es wird keine Fehlermeldung zurückgegeben.

Hinweis: Diese Methode wird in Outlook unter iOS oder Android nicht unterstützt.

displayAppointmentFormAsync(itemId: string, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameter

itemId: string

Der EWS-Bezeichner (Exchange Web Services, Exchange-Webdienste) für einen vorhandenen Kalendertermin.

callback: (asyncResult: Office.AsyncResult<void>) => void

Gibt zurück

void

Hinweise

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Compose oder Lesen

displayMessageForm(itemId)

Zeigt eine vorhandene Nachricht an.

Die displayMessageForm -Methode öffnet eine vorhandene Nachricht in einem neuen Fenster auf dem Desktop.

In Outlook im Web und dem neuen Outlook unter Windows öffnet diese Methode das angegebene Formular nur, wenn der Text des Formulars kleiner oder gleich 32.000 Zeichen ist.

Wenn der angegebene Elementbezeichner keine vorhandene Nachricht identifiziert, wird keine Meldung auf dem Clientcomputer angezeigt, und es wird keine Fehlermeldung zurückgegeben.

displayMessageForm(itemId: string): void;

Parameter

itemId: string

Der Exchange-Webdienste (EWS) für eine vorhandene Nachricht.

Gibt zurück

void

Hinweise

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Compose oder Lesen

Wichtig:

Diese Methode wird in Outlook unter Android oder iOS nicht unterstützt. Weitere Informationen zu unterstützten APIs in Outlook Mobile finden Sie unter In Outlook unterstützte JavaScript-APIs auf mobilen Geräten.
Verwenden Sie nicht mit displayMessageForm einer itemId, die einen Termin darstellt. Verwenden Sie die displayAppointmentForm-Methode, um einen vorhandenen Termin anzuzeigen, und displayNewAppointmentForm, um ein Formular zum Erstellen eines neuen Termins anzuzeigen.

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-existing-message.yaml

const itemId = $("#itemId").val();
Office.context.mailbox.displayMessageForm(itemId);

displayMessageFormAsync(itemId, options, callback)

Zeigt eine vorhandene Nachricht an.

Die displayMessageFormAsync-Methode öffnet eine vorhandene Nachricht in einem neuen Fenster auf dem Desktop bzw. in einem Dialogfeld auf Mobilgeräten.

In Outlook im Web und dem neuen Outlook unter Windows öffnet diese Methode das angegebene Formular nur, wenn der Text des Formulars kleiner oder gleich 32.000 Zeichen ist.

Wenn der angegebene Elementbezeichner keine vorhandene Nachricht identifiziert, wird keine Meldung auf dem Clientcomputer angezeigt, und es wird keine Fehlermeldung zurückgegeben.

Verwenden Sie die displayMessageForm - oder displayMessageFormAsync -Methode nicht mit einer itemId, die einen Termin darstellt. Verwenden Sie die displayAppointmentForm - oder displayAppointmentFormAsync -Methode, um einen vorhandenen Termin anzuzeigen, und displayNewAppointmentForm oder displayNewAppointmentFormAsync um ein Formular zum Erstellen eines neuen Termins anzuzeigen.

Hinweis: Diese Methode wird in Outlook unter iOS oder Android nicht unterstützt.

displayMessageFormAsync(itemId: string, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameter

itemId: string

Der Exchange-Webdienste (EWS) für eine vorhandene Nachricht.

options: Office.AsyncContextOptions

Ein Objektliteral, das eine oder mehrere der folgenden Eigenschaften enthält: asyncContextEntwickler können jedes Objekt bereitstellen, auf das sie in der Rückruffunktion zugreifen möchten.

callback: (asyncResult: Office.AsyncResult<void>) => void

Gibt zurück

void

Hinweise

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Compose oder Lesen

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-existing-message.yaml

const itemId = $("#itemId").val();

// The async version will return error 9049 if the item is not found.
// The async version is only available starting with requirement set 1.9.
Office.context.mailbox.displayMessageFormAsync(itemId, function (asyncResult) {
 console.log("Result: " + JSON.stringify(asyncResult));
});

displayMessageFormAsync(itemId, callback)

Zeigt eine vorhandene Nachricht an.

Die displayMessageFormAsync-Methode öffnet eine vorhandene Nachricht in einem neuen Fenster auf dem Desktop bzw. in einem Dialogfeld auf Mobilgeräten.

In Outlook im Web und dem neuen Outlook unter Windows öffnet diese Methode das angegebene Formular nur, wenn der Text des Formulars kleiner oder gleich 32.000 Zeichen ist.

Wenn der angegebene Elementbezeichner keine vorhandene Nachricht identifiziert, wird keine Meldung auf dem Clientcomputer angezeigt, und es wird keine Fehlermeldung zurückgegeben.

Hinweis: Diese Methode wird in Outlook unter iOS oder Android nicht unterstützt.

displayMessageFormAsync(itemId: string, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameter

itemId: string

Der Exchange-Webdienste (EWS) für eine vorhandene Nachricht.

callback: (asyncResult: Office.AsyncResult<void>) => void

Gibt zurück

void

Hinweise

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Compose oder Lesen

displayNewAppointmentForm(parameters)

Zeigt ein Formular zum Erstellen eines neuen Kalendertermins an.

Mit der displayNewAppointmentForm-Methode wird ein Formular geöffnet, mit dem der Benutzer einen neuen Termin oder eine Besprechung erstellen kann. Wenn Parameter angegeben wurden, werden die Felder im Terminformular automatisch mit dem Inhalt der Parameter ausgefüllt.

In Outlook im Web und neuen Outlook unter Windows zeigt diese Methode immer ein Formular mit einem Teilnehmerfeld an. Wenn Sie keine Teilnehmer als Eingabeargumente angeben, zeigt die Methode ein Formular mit der Schaltfläche Speichern an. Wenn Sie Teilnehmer angegeben haben, enthält das Formular die Teilnehmer und eine Schaltfläche Senden.

Wenn Sie in Outlook für Windows (klassisch) und auf Mac teilnehmer oder Ressourcen in den requiredAttendeesParametern , optionalAttendeesoder resources angeben, zeigt diese Methode ein Besprechungsformular mit der Schaltfläche Senden an. Wenn keine Teilnehmer angegeben werden, wird mit dieser Methode ein Terminformular mit der Schaltfläche Speichern & schließen angezeigt.

Wenn einer der Parameter die angegebenen Größenbeschränkungen überschreitet oder wenn ein unbekannter Parametername angegeben wird, wird eine Ausnahme ausgelöst.

displayNewAppointmentForm(parameters: AppointmentForm): void;

Parameter

parameters: Office.AppointmentForm

Eine AppointmentForm , die den neuen Termin beschreibt. Alle Eigenschaften sind optional.

Gibt zurück

void

Hinweise

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Lesen

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-new-appointment.yaml

const start = new Date();
const end = new Date();
end.setHours(start.getHours() + 1);

Office.context.mailbox.displayNewAppointmentForm({
  requiredAttendees: ["bob@contoso.com"],
  optionalAttendees: ["sam@contoso.com"],
  start: start,
  end: end,
  location: "Home",
  subject: "meeting",
  resources: ["projector@contoso.com"],
  body: "Hello World!"
});

displayNewAppointmentFormAsync(parameters, options, callback)

Zeigt ein Formular zum Erstellen eines neuen Kalendertermins an.

Mit der displayNewAppointmentFormAsync-Methode wird ein Formular geöffnet, mit dem der Benutzer einen neuen Termin oder eine Besprechung erstellen kann. Wenn Parameter angegeben wurden, werden die Felder im Terminformular automatisch mit dem Inhalt der Parameter ausgefüllt.

In Outlook im Web und neuen Outlook unter Windows zeigt diese Methode immer ein Formular mit einem Teilnehmerfeld an. Wenn Sie keine Teilnehmer als Eingabeargumente angeben, zeigt die Methode ein Formular mit einer Schaltfläche Speichern an. Wenn Sie Teilnehmer angegeben haben, enthält das Formular die Teilnehmer und eine Schaltfläche Senden.

Wenn einer der Parameter die angegebenen Größenbeschränkungen überschreitet oder wenn ein unbekannter Parametername angegeben wird, wird eine Ausnahme ausgelöst.

Hinweis: Diese Methode wird in Outlook unter iOS oder Android nicht unterstützt.

displayNewAppointmentFormAsync(parameters: AppointmentForm, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameter

parameters: Office.AppointmentForm

Eine AppointmentForm , die den neuen Termin beschreibt. Alle Eigenschaften sind optional.

options: Office.AsyncContextOptions

Ein Objektliteral, das eine oder mehrere der folgenden Eigenschaften enthält: asyncContextEntwickler können jedes Objekt bereitstellen, auf das sie in der Rückruffunktion zugreifen möchten.

callback: (asyncResult: Office.AsyncResult<void>) => void

Gibt zurück

void

Hinweise

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Lesen

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-new-appointment.yaml

const start = new Date();
const end = new Date();
end.setHours(start.getHours() + 1);

// The async version is only available starting with requirement set 1.9,
// and provides a callback when the new appointment form has been created.
Office.context.mailbox.displayNewAppointmentFormAsync(
  {
    requiredAttendees: ["bob@contoso.com"],
    optionalAttendees: ["sam@contoso.com"],
    start: start,
    end: end,
    location: "Home",
    subject: "meeting",
    resources: ["projector@contoso.com"],
    body: "Hello World!"
  },
  function(asyncResult) {
    console.log(JSON.stringify(asyncResult));
  }
);

displayNewAppointmentFormAsync(parameters, callback)

Zeigt ein Formular zum Erstellen eines neuen Kalendertermins an.

In Outlook im Web und neuen Outlook unter Windows zeigt diese Methode immer ein Formular mit einem Teilnehmerfeld an. Wenn Sie keine Teilnehmer als Eingabeargumente angeben, zeigt die Methode ein Formular mit einer Schaltfläche Speichern an. Wenn Sie Teilnehmer angegeben haben, enthält das Formular die Teilnehmer und eine Schaltfläche Senden.

Wenn einer der Parameter die angegebenen Größenbeschränkungen überschreitet oder wenn ein unbekannter Parametername angegeben wird, wird eine Ausnahme ausgelöst.

Hinweis: Diese Methode wird in Outlook unter iOS oder Android nicht unterstützt.

displayNewAppointmentFormAsync(parameters: AppointmentForm, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameter

parameters: Office.AppointmentForm

Eine AppointmentForm , die den neuen Termin beschreibt. Alle Eigenschaften sind optional.

callback: (asyncResult: Office.AsyncResult<void>) => void

Gibt zurück

void

Hinweise

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Lesen

displayNewMessageForm(parameters)

Zeigt ein Formular zum Erstellen einer neuen Nachricht an.

Die displayNewMessageForm -Methode öffnet ein Formular, mit dem der Benutzer eine neue Nachricht erstellen kann. Wenn Parameter angegeben werden, werden die Nachrichtenformularfelder automatisch mit dem Inhalt der Parameter aufgefüllt.

Wenn einer der Parameter die angegebenen Größenbeschränkungen überschreitet oder wenn ein unbekannter Parametername angegeben wird, wird eine Ausnahme ausgelöst.

displayNewMessageForm(parameters: any): void;

Parameter

parameters: any

Ein Wörterbuch, das alle Werte enthält, die für den Benutzer im neuen Formular ausgefüllt werden sollen. Alle Parameter sind optional.

toRecipients : Ein Array von Zeichenfolgen, die die E-Mail-Adressen enthalten, oder ein Array, das ein EmailAddressDetails-Objekt für jeden der Empfänger in der Zeile An enthält. Das Array darf maximal 100 Einträge enthalten.

ccRecipients : Ein Array von Zeichenfolgen, die die E-Mail-Adressen enthalten, oder ein Array, das ein EmailAddressDetails-Objekt für jeden empfänger in der Zeile Cc enthält. Das Array darf maximal 100 Einträge enthalten.

bccRecipients : Ein Array von Zeichenfolgen, die die E-Mail-Adressen enthalten, oder ein Array, das ein EmailAddressDetails-Objekt für jeden der Empfänger in der Bcc-Zeile enthält. Das Array darf maximal 100 Einträge enthalten.

subject : Eine Zeichenfolge, die den Betreff der Nachricht enthält. Die Zeichenfolge ist auf maximal 255 Zeichen beschränkt.

htmlBody : Der HTML-Text der Nachricht. Der Textkörper ist auf eine maximale Größe von 32 KB beschränkt.

attachments : Ein Array von JSON-Objekten, die entweder Datei- oder Elementanlagen sind.

attachments.type : Gibt den Typ der Anlage an. Muss file für eine Dateianlage oder item für eine Elementanlage sein.

attachments.name : Eine Zeichenfolge, die den Namen der Anlage mit einer Länge von bis zu 255 Zeichen enthält.

attachments.url : Wird nur verwendet, wenn der Anlagentyp auf filefestgelegt ist. Der URI des Speicherorts für die Datei. Wichtig: Dieser Link muss öffentlich zugänglich sein, ohne dass eine Authentifizierung durch Exchange Online Server erforderlich ist. Mit lokalem Exchange kann jedoch in einem privaten Netzwerk auf den Link zugegriffen werden, solange keine weitere Authentifizierung erforderlich ist.

attachments.isInline : Wird nur verwendet, wenn der Anlagentyp auf filefestgelegt ist. Wenn true, gibt an, dass die Anlage inline als Bild im Nachrichtentext angezeigt wird und nicht in der Anlageliste angezeigt wird.

attachments.itemId : Wird nur verwendet, wenn der Anlagentyp auf itemfestgelegt ist. Die EWS-Element-ID der vorhandenen E-Mail, die Sie an die neue Nachricht anfügen möchten. Diese Zeichenfolge kann bis zu 100 Zeichen lang sein.

Gibt zurück

void

Hinweise

[ API-Satz: Postfach 1.6 ]

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Lesen

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-new-message.yaml

Office.context.mailbox.displayNewMessageForm({
  toRecipients: Office.context.mailbox.item.to, // Copies the To line from current item
  ccRecipients: ["sam@contoso.com"],
  subject: "Outlook add-ins are cool!",
  htmlBody: 'Hello <b>World</b>!<br/><img src="cid:image.png"></i>',
  attachments: [
    {
      type: "file",
      name: "image.png",
      url: "https://i.imgur.com/9S36xvA.jpg",
      isInline: true
    }
  ]
});

displayNewMessageFormAsync(parameters, options, callback)

Zeigt ein Formular zum Erstellen einer neuen Nachricht an.

Die displayNewMessageFormAsync -Methode öffnet ein Formular, mit dem der Benutzer eine neue Nachricht erstellen kann. Wenn Parameter angegeben werden, werden die Nachrichtenformularfelder automatisch mit dem Inhalt der Parameter aufgefüllt.

Wenn einer der Parameter die angegebenen Größenbeschränkungen überschreitet oder wenn ein unbekannter Parametername angegeben wird, wird eine Ausnahme ausgelöst.

displayNewMessageFormAsync(parameters: any, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameter

parameters: any

Ein Wörterbuch, das alle Werte enthält, die für den Benutzer im neuen Formular ausgefüllt werden sollen. Alle Parameter sind optional.

subject : Eine Zeichenfolge, die den Betreff der Nachricht enthält. Die Zeichenfolge ist auf maximal 255 Zeichen beschränkt.

htmlBody : Der HTML-Text der Nachricht. Der Textkörper ist auf eine maximale Größe von 32 KB beschränkt.

attachments : Ein Array von JSON-Objekten, die entweder Datei- oder Elementanlagen sind.

attachments.type : Gibt den Typ der Anlage an. Muss file für eine Dateianlage oder item für eine Elementanlage sein.

attachments.name : Eine Zeichenfolge, die den Namen der Anlage mit einer Länge von bis zu 255 Zeichen enthält.

options: Office.AsyncContextOptions

Ein Objektliteral, das eine oder mehrere der folgenden Eigenschaften enthält: asyncContextEntwickler können jedes Objekt bereitstellen, auf das sie in der Rückruffunktion zugreifen möchten.

callback: (asyncResult: Office.AsyncResult<void>) => void

Gibt zurück

void

Hinweise

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Lesen

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/55-display-items/display-new-message.yaml

// The async version is only available starting with requirement set 1.9,
// and provides a callback when the new message form has been created.
Office.context.mailbox.displayNewMessageFormAsync(
  {
    toRecipients: Office.context.mailbox.item.to, // Copies the To line from current item
    ccRecipients: ["sam@contoso.com"],
    subject: "Outlook add-ins are cool!",
    htmlBody: 'Hello <b>World</b>!<br/><img src="cid:image.png"></i>',
    attachments: [
      {
        type: "file",
        name: "image.png",
        url: "https://i.imgur.com/9S36xvA.jpg",
        isInline: true
      }
    ]
  },
  (asyncResult) => {
    console.log(JSON.stringify(asyncResult));
  }
);

displayNewMessageFormAsync(parameters, callback)

Zeigt ein Formular zum Erstellen einer neuen Nachricht an.

Wenn einer der Parameter die angegebenen Größenbeschränkungen überschreitet oder wenn ein unbekannter Parametername angegeben wird, wird eine Ausnahme ausgelöst.

displayNewMessageFormAsync(parameters: any, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameter

parameters: any

Ein Wörterbuch, das alle Werte enthält, die für den Benutzer im neuen Formular ausgefüllt werden sollen. Alle Parameter sind optional.

subject : Eine Zeichenfolge, die den Betreff der Nachricht enthält. Die Zeichenfolge ist auf maximal 255 Zeichen beschränkt.

htmlBody : Der HTML-Text der Nachricht. Der Textkörper ist auf eine maximale Größe von 32 KB beschränkt.

attachments : Ein Array von JSON-Objekten, die entweder Datei- oder Elementanlagen sind.

attachments.type : Gibt den Typ der Anlage an. Muss file für eine Dateianlage oder item für eine Elementanlage sein.

attachments.name : Eine Zeichenfolge, die den Namen der Anlage mit einer Länge von bis zu 255 Zeichen enthält.

callback: (asyncResult: Office.AsyncResult<void>) => void

Gibt zurück

void

Hinweise

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Lesen

getCallbackTokenAsync(options, callback)

Ruft eine Zeichenfolge ab, die ein Token enthält, das zum Aufrufen von REST-APIs oder Exchange-Webdiensten (EWS) verwendet wird.

Die getCallbackTokenAsync-Methode führt einen asynchronen Aufruf zum Abruf eines nicht transparenten Tokens vom Exchange-Server aus, der das Postfach des Benutzers hostet. Die Gültigkeitsdauer des Rückruftokens beträgt 5 Minuten.

Das Token wird als Zeichenfolge in der asyncResult.value -Eigenschaft zurückgegeben.

getCallbackTokenAsync(options: Office.AsyncContextOptions & { isRest?: boolean }, callback: (asyncResult: Office.AsyncResult<string>) => void): void;

Parameter

options: Office.AsyncContextOptions & { isRest?: boolean }

Ein Objektliteral, das eine oder mehrere der folgenden Eigenschaften enthält:- isRest: Bestimmt, ob das bereitgestellte Token für die Outlook-REST-APIs oder Exchange-Webdienste verwendet wird. Der Standardwert ist false. asyncContext : Alle Zustandsdaten, die an die asynchrone Methode übergeben werden.

callback: (asyncResult: Office.AsyncResult<string>) => void

Wenn die Methode abgeschlossen ist, wird die im Rückrufparameter übergebene Funktion mit einem einzelnen Parameter vom Typ Office.AsyncResultaufgerufen. Das Token wird als Zeichenfolge in der asyncResult.value -Eigenschaft zurückgegeben. Wenn ein Fehler aufgetreten ist, können die Eigenschaften asyncResult.error und asyncResult.diagnostics weitere Informationen enthalten.

Gibt zurück

void

Hinweise

[ API-Satz: Alle unterstützen den Lesemodus; Mailbox 1.3 wurde Compose-Modus-Unterstützung eingeführt ]

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Compose oder Lesen

Wichtig:

Im Oktober 2024 werden ältere Exchange-Benutzeridentitäts- und -Rückruftoken für alle Exchange Online Mandanten standardmäßig deaktiviert. Dies ist Teil der Secure Future Initiative von Microsoft, die Organisationen die Tools zur Verfügung stellt, die sie benötigen, um auf die aktuelle Bedrohungslandschaft zu reagieren. Exchange-Benutzeridentitätstoken funktionieren weiterhin für lokale Exchange-Instanzen. Die Authentifizierung geschachtelter Apps ist der empfohlene Ansatz für token in Zukunft. Weitere Informationen finden Sie in unserem Blogbeitrag und in den häufig gestellten Fragen.
Die Outlook REST v2.0- und Beta-Endpunkte sind jetzt veraltet. Privat veröffentlichte und von AppSource gehostete Add-Ins können den REST-Dienst jedoch verwenden, bis der erweiterte Support für Outlook 2019 am 14. Oktober 2025 endet. Datenverkehr von diesen Add-Ins wird automatisch als Ausnahme identifiziert. Diese Ausnahme gilt auch für neue Add-Ins, die nach dem 31. März 2024 entwickelt wurden. Obwohl Add-Ins den REST-Dienst bis 2025 verwenden können, empfehlen wir Ihnen dringend, Ihre Add-Ins zur Verwendung von Microsoft Graph zu migrieren. Eine Anleitung finden Sie unter Vergleichen von Microsoft Graph- und Outlook-REST-API-Endpunkten.
Diese Methode wird nicht unterstützt, wenn Sie ein Add-In in ein Outlook.com- oder Gmail-Postfach laden.
Diese Methode wird nur im Lesemodus in Outlook unter Android und iOS unterstützt. Weitere Informationen zu unterstützten APIs in Outlook Mobile finden Sie unter In Outlook unterstützte JavaScript-APIs auf mobilen Geräten.
EWS-Vorgänge werden in Add-Ins, die in Outlook unter iOS und Android ausgeführt werden, nicht unterstützt. Ein REST-Token wird in mobilen Outlook-Clients immer zurückgegeben, auch wenn options.isRest auf falsefestgelegt ist.
Für das Aufrufen der getCallbackTokenAsync Methode im Lesemodus ist eine Mindestberechtigungsstufe für das Lesen von Elementen erforderlich.
Wenn Sie die getCallbackTokenAsync -Methode im Verfassenmodus aufrufen, müssen Sie das Element gespeichert haben. Die saveAsync -Methode erfordert eine Mindestberechtigungsstufe für Lese-/Schreibzugriff.
Anleitungen zu Delegat- oder freigegebenen Szenarien finden Sie im Artikel freigegebene Ordner und freigegebene Postfächer .

REST-Token

Wenn ein REST-Token angefordert wird (options.isRest = true), funktioniert das resultierende Token nicht zum Authentifizieren von EWS-Aufrufen. Das Token ist im Bereich auf den schreibgeschützten Zugriff auf das aktuelle Element und seine Anlagen beschränkt, es sei denn, das Add-In hat die Lese-/Schreibberechtigung für Das Postfach in seinem Manifest angegeben. Wenn die Lese-/Schreibberechtigung für Das Postfach angegeben ist, gewährt das resultierende Token Lese-/Schreibzugriff auf E-Mails, Kalender und Kontakte, einschließlich der Möglichkeit zum Senden von E-Mails.

Das Add-In sollte die Eigenschaft restUrl verwenden, um die korrekte URL für REST-API-Aufrufe zu ermitteln.

Diese API funktioniert für die folgenden Bereiche.

Mail.ReadWrite
Mail.Send
Calendars.ReadWrite
Contacts.ReadWrite

EWS-Tokens

Wenn ein EWS-Token angefordert wird (options.isRest = false), funktioniert das resultierende Token nicht zum Authentifizieren von REST-API-Aufrufen. Der Bereich des Tokens ist auf den Zugriff auf das aktuelle Element beschränkt.

Das Add-In sollte die Eigenschaft ewsUrl verwenden, um die korrekte URL für EWS-Aufrufe zu ermitteln.

Sie können sowohl das Token als auch einen Anlagenbezeichner oder einen Elementbezeichner an ein externes System übergeben. Dieses System verwendet das Token als Bearerautorisierungstoken, um den EwS-GetAttachment-Vorgang (Exchange Web Services) oder den GetItem-Vorgang aufzurufen, um eine Anlage oder ein Element zurückzugeben. Sie können beispielsweise einen Remotedienst erstellen, um Anlagen aus dem ausgewählten Element abzurufen.

Fehler:

HTTPRequestFailure : Fehler bei der Anforderung. Den HTTP-Fehlercode finden Sie im Diagnoseobjekt.
InternalServerError : Der Exchange-Server hat einen Fehler zurückgegeben. Weitere Informationen finden Sie im Diagnoseobjekt.
NetworkError : Der Benutzer ist nicht mehr mit dem Netzwerk verbunden. Überprüfen Sie Ihre Netzwerkverbindung, und versuchen Sie es erneut.

getCallbackTokenAsync(callback, userContext)

Ruft eine Zeichenfolge ab, die einen Token enthält, der verwendet wird, um eine Anlage oder ein Element von einem Exchange Server abzurufen.

Das Token wird als Zeichenfolge in der asyncResult.value -Eigenschaft zurückgegeben.

getCallbackTokenAsync(callback: (asyncResult: Office.AsyncResult<string>) => void, userContext?: any): void;

Parameter

callback: (asyncResult: Office.AsyncResult<string>) => void

userContext: any

Optional. Jegliche Zustandsdaten, die an die asynchrone Methode übergeben werden.

Gibt zurück

void

Hinweise

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Compose oder Lesen

Wichtig:

Im Oktober 2024 werden ältere Exchange-Benutzeridentitäts- und -Rückruftoken für alle Exchange Online Mandanten standardmäßig deaktiviert. Dies ist Teil der Secure Future Initiative von Microsoft, die Organisationen die Tools zur Verfügung stellt, die sie benötigen, um auf die aktuelle Bedrohungslandschaft zu reagieren. Exchange-Benutzeridentitätstoken funktionieren weiterhin für lokale Exchange-Instanzen. Die Authentifizierung geschachtelter Apps ist der empfohlene Ansatz für token in Zukunft. Weitere Informationen finden Sie in unserem Blogbeitrag und in den häufig gestellten Fragen.
Sie können sowohl das Token als auch einen Anlagenbezeichner oder einen Elementbezeichner an ein externes System übergeben. Dieses System verwendet das Token als Bearerautorisierungstoken, um den EwS-Vorgang (Exchange Web Services) GetAttachment oder GetItem aufzurufen, um eine Anlage oder ein Element zurückzugeben. Sie können beispielsweise einen Remotedienst erstellen, um Anlagen aus dem ausgewählten Element abzurufen.
Für das Aufrufen der getCallbackTokenAsync Methode im Lesemodus ist eine Mindestberechtigungsstufe für das Lesen von Elementen erforderlich.
Wenn Sie die getCallbackTokenAsync -Methode im Verfassenmodus aufrufen, müssen Sie das Element gespeichert haben. Die saveAsync -Methode erfordert eine Mindestberechtigungsstufe für Lese-/Schreibzugriff.
Diese Methode wird in Outlook unter Android oder iOS nicht unterstützt. EWS-Vorgänge werden in Add-Ins, die in Outlook auf mobilen Clients ausgeführt werden, nicht unterstützt. Weitere Informationen zu unterstützten APIs in Outlook Mobile finden Sie unter In Outlook unterstützte JavaScript-APIs auf mobilen Geräten.
Diese Methode wird nicht unterstützt, wenn Sie ein Add-In in ein Outlook.com- oder Gmail-Postfach laden.
Anleitungen zu Delegat- oder freigegebenen Szenarien finden Sie im Artikel freigegebene Ordner und freigegebene Postfächer .

Fehler:

HTTPRequestFailure : Fehler bei der Anforderung. Den HTTP-Fehlercode finden Sie im Diagnoseobjekt.
InternalServerError : Der Exchange-Server hat einen Fehler zurückgegeben. Weitere Informationen finden Sie im Diagnoseobjekt.
NetworkError : Der Benutzer ist nicht mehr mit dem Netzwerk verbunden. Überprüfen Sie Ihre Netzwerkverbindung, und versuchen Sie es erneut.

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-and-service-calls/user-callback-token.yaml

Office.context.mailbox.getCallbackTokenAsync((result) => {
    if (result.status === Office.AsyncResultStatus.Failed) {
        console.error(`Token retrieval failed with message: ${result.error.message}`);
        return;
    }

    console.log(result.value);
});

getUserIdentityTokenAsync(callback, userContext)

Ruft ein Token ab, das den Benutzer und das Office-Add-In identifiziert.

Das Token wird als Zeichenfolge in der asyncResult.value -Eigenschaft zurückgegeben.

getUserIdentityTokenAsync(callback: (asyncResult: Office.AsyncResult<string>) => void, userContext?: any): void;

Parameter

callback: (asyncResult: Office.AsyncResult<string>) => void

userContext: any

Optional. Jegliche Zustandsdaten, die an die asynchrone Methode übergeben werden.

Gibt zurück

void

Hinweise

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Compose oder Lesen

Wichtig:

Im Oktober 2024 werden ältere Exchange-Benutzeridentitäts- und -Rückruftoken für alle Exchange Online Mandanten standardmäßig deaktiviert. Dies ist Teil der Secure Future Initiative von Microsoft, die Organisationen die Tools zur Verfügung stellt, die sie benötigen, um auf die aktuelle Bedrohungslandschaft zu reagieren. Exchange-Benutzeridentitätstoken funktionieren weiterhin für lokale Exchange-Instanzen. Die Authentifizierung geschachtelter Apps ist der empfohlene Ansatz für token in Zukunft. Weitere Informationen finden Sie in unserem Blogbeitrag und in den häufig gestellten Fragen.
Die getUserIdentityTokenAsync Methode gibt ein Token zurück, das Sie verwenden können, um das Add-In und den Benutzer mit einem externen System zu identifizieren und zu authentifizieren.
Diese Methode wird nicht unterstützt, wenn Sie ein Add-In in ein Outlook.com- oder Gmail-Postfach laden.

Fehler:

HTTPRequestFailure : Fehler bei der Anforderung. Den HTTP-Fehlercode finden Sie im Diagnoseobjekt.
InternalServerError : Der Exchange-Server hat einen Fehler zurückgegeben. Weitere Informationen finden Sie im Diagnoseobjekt.
NetworkError : Der Benutzer ist nicht mehr mit dem Netzwerk verbunden. Überprüfen Sie Ihre Netzwerkverbindung, und versuchen Sie es erneut.

Beispiele

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-and-service-calls/user-identity-token.yaml

Office.context.mailbox.getUserIdentityTokenAsync((result) => {
    if (result.status === Office.AsyncResultStatus.Failed) {
        console.error(`Token retrieval failed with message: ${result.error.message}`)
        return;
    }

    console.log(result.value);
});

makeEwsRequestAsync(data, callback, userContext)

Sendet eine asynchrone Anforderung an einen Exchange-Webdienstdienst (EWS) auf dem Exchange-Server, der das Postfach des Benutzers hostet.

Die makeEwsRequestAsync-Methode sendet eine EWS-Anforderung für das Add-In zu Exchange.

makeEwsRequestAsync(data: any, callback: (asyncResult: Office.AsyncResult<string>) => void, userContext?: any): void;

Parameter

data: any

Die EWS-Anforderung.

callback: (asyncResult: Office.AsyncResult<string>) => void

Wenn die -Methode abgeschlossen ist, wird die im callback -Parameter übergebene Funktion mit einem einzelnen Parameter aufgerufen, asyncResult, der ein Office.AsyncResult -Objekt ist. Die XML-Antwort der EWS-Anforderung wird als Zeichenfolge in der asyncResult.value -Eigenschaft bereitgestellt. In Outlook im Web, unter Windows (neu und klassisch(ab Version 2303, Build 16225.10000)) und unter Mac (ab Version 16.73 (23042601)) wird eine Fehlermeldung zurückgegebenasyncResult.error, wenn die Antwort eine Größe von 5 MB überschreitet. In früheren Versionen von Outlook unter Windows (klassisch) und auf Mac wird eine Fehlermeldung zurückgegeben, wenn die Antwort eine Größe von 1 MB überschreitet.

userContext: any

Optional. Jegliche Zustandsdaten, die an die asynchrone Methode übergeben werden.

Gibt zurück

void

Hinweise

Minimale Berechtigungsstufe: Postfach lesen/schreiben

Anwendbarer Outlook-Modus: Compose oder Lesen

Wichtig:

Im Oktober 2024 werden ältere Exchange-Benutzeridentitäts- und -Rückruftoken für alle Exchange Online Mandanten standardmäßig deaktiviert. Dies ist Teil der Secure Future Initiative von Microsoft, die Organisationen die Tools zur Verfügung stellt, die sie benötigen, um auf die aktuelle Bedrohungslandschaft zu reagieren. Exchange-Benutzeridentitätstoken funktionieren weiterhin für lokale Exchange-Instanzen. Die Authentifizierung geschachtelter Apps ist der empfohlene Ansatz für token in Zukunft. Weitere Informationen finden Sie in unserem Blogbeitrag und in den häufig gestellten Fragen.
Um die makeEwsRequestAsync -Methode für EWS-Anforderungen zu aktivieren, muss der Serveradministrator im EWS-Verzeichnis des Clientzugriffsservers auf true festlegenOAuthAuthentication.
Ihr Add-In muss über die Berechtigung zum Lesen/Schreiben des Postfachs verfügen, um die makeEwsRequestAsync -Methode verwenden zu können. Informationen zur Verwendung der Lese-/Schreibberechtigung für Postfächer und zu den EWS-Vorgängen, die Sie mit der makeEwsRequestAsync -Methode aufrufen können, finden Sie unter Angeben von Berechtigungen für den E-Mail-Add-In-Zugriff auf das Postfach des Benutzers.
Wenn Ihr Add-In auf Ordner zugeordnete Elemente zugreifen muss oder seine XML-Anforderung UTF-8-Codierung (\<?xml version="1.0" encoding="utf-8"?\>) angeben muss, muss es stattdessen Microsoft Graph- oder REST-APIs verwenden, um auf das Postfach des Benutzers zuzugreifen.
Diese Methode wird in Outlook unter Android oder iOS nicht unterstützt. Weitere Informationen zu unterstützten APIs in Outlook Mobile finden Sie unter In Outlook unterstützte JavaScript-APIs auf mobilen Geräten.
Diese Methode wird nicht unterstützt, wenn das Add-In in ein Gmail-Postfach geladen wird.
Wenn Sie die makeEwsRequestAsync -Methode in Add-Ins verwenden, die in Outlook-Versionen vor Version 15.0.4535.1004 ausgeführt werden, müssen Sie den Codierungswert auf ISO-8859-1 (<?xml version="1.0" encoding="iso-8859-1"?>) festlegen. Verwenden Sie die -Eigenschaft, um die mailbox.diagnostics.hostVersion Version eines Outlook-Clients zu bestimmen. Sie müssen den Codierungswert nicht festlegen, wenn Ihr Add-In in Outlook im Web oder in outlook unter Windows ausgeführt wird. Verwenden Sie die -Eigenschaft, um den Outlook-Client zu bestimmen, in dem mailbox.diagnostics.hostName ihr Add-In ausgeführt wird.

Beispiele

function getSubjectRequest(id) {
    // Return a GetItem operation request for the subject of the specified item.
    const request =
        '<?xml version="1.0" encoding="utf-8"?>' +
        '<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"' +
        '               xmlns:xsd="http://www.w3.org/2001/XMLSchema"' +
        '               xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"' +
        '               xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types">' +
        '  <soap:Header>' +
        '    <RequestServerVersion Version="Exchange2016" xmlns="http://schemas.microsoft.com/exchange/services/2006/types" soap:mustUnderstand="0" />' +
        '  </soap:Header>' +
        '  <soap:Body>' +
        '    <GetItem xmlns="http://schemas.microsoft.com/exchange/services/2006/messages">' +
        '      <ItemShape>' +
        '        <t:BaseShape>IdOnly</t:BaseShape>' +
        '        <t:AdditionalProperties>' +
        '            <t:FieldURI FieldURI="item:Subject"/>' +
        '        </t:AdditionalProperties>' +
        '      </ItemShape>' +
        '      <ItemIds><t:ItemId Id="' + id + '"/></ItemIds>' +
        '    </GetItem>' +
        '  </soap:Body>' +
        '</soap:Envelope>';

    return request;
}

function sendRequest() {
    // Create a local variable that contains the mailbox.
    Office.context.mailbox.makeEwsRequestAsync(
        getSubjectRequest(mailbox.item.itemId), callback);
}

function callback(asyncResult)  {
    const result = asyncResult.value;
    const context = asyncResult.asyncContext;

    // Process the returned response here.
}

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-and-service-calls/get-icaluid-as-attendee.yaml

const ewsId = Office.context.mailbox.item.itemId;
const request = `<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages" xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
      <soap:Header><t:RequestServerVersion Version="Exchange2013" /></soap:Header>
      <soap:Body>
        <m:GetItem>
          <m:ItemShape>
            <t:BaseShape>AllProperties</t:BaseShape>
          </m:ItemShape >
          <m:ItemIds>
            <t:ItemId Id="${ewsId}" />
          </m:ItemIds>
        </m:GetItem>
      </soap:Body>
    </soap:Envelope>`;

Office.context.mailbox.makeEwsRequestAsync(request, (result) => {
  if (result.status === Office.AsyncResultStatus.Failed) {
    console.error(result.error.message);
    return;
  }

  console.log(getUID(result.value));
});

...

const request = '<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages" xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">'+
    '  <soap:Header><t:RequestServerVersion Version="Exchange2010" /></soap:Header>'+
    '  <soap:Body>'+
    '    <m:CreateItem MessageDisposition="SendAndSaveCopy">'+
    '      <m:SavedItemFolderId><t:DistinguishedFolderId Id="sentitems" /></m:SavedItemFolderId>'+
    '      <m:Items>'+
    '        <t:Message>'+
    '          <t:Subject>Hello, Outlook!</t:Subject>'+
    '          <t:Body BodyType="HTML">This message was sent from a ScriptLab code sample, used from ' + Office.context.mailbox.diagnostics.hostName + ', version ' + Office.context.mailbox.diagnostics.hostVersion + '!</t:Body>'+
    '          <t:ToRecipients>'+
    '            <t:Mailbox><t:EmailAddress>' + Office.context.mailbox.userProfile.emailAddress + '</t:EmailAddress></t:Mailbox>'+
    '          </t:ToRecipients>'+
    '        </t:Message>'+
    '      </m:Items>'+
    '    </m:CreateItem>'+
    '  </soap:Body>'+
    '</soap:Envelope>';

Office.context.mailbox.makeEwsRequestAsync(request, (result) => {
    console.log(result);
});

removeHandlerAsync(eventType, options, callback)

Entfernt die Ereignishandler für einen unterstützten Ereignistyp. Hinweis: Ereignisse sind nur bei der Implementierung des Aufgabenbereichs verfügbar.

Informationen zu unterstützten Ereignissen finden Sie im Abschnitt Ereignisse des Postfachobjektmodells.

removeHandlerAsync(eventType: Office.EventType | string, options: Office.AsyncContextOptions, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameter

eventType: Office.EventType | string

Das Ereignis, das den Handler widerrufen soll.

options: Office.AsyncContextOptions

Bietet eine Option zum Beibehalten von Kontextdaten eines beliebigen Typs , unverändert, für die Verwendung in einem Rückruf.

callback: (asyncResult: Office.AsyncResult<void>) => void

Optional. Wenn die -Methode abgeschlossen ist, wird die im callback -Parameter übergebene Funktion mit einem einzelnen Parameter vom Typ Office.AsyncResultaufgerufen.

Gibt zurück

void

Hinweise

Mindestberechtigungsstufe: Element lesen

Anwendbarer Outlook-Modus: Compose oder Lesen

removeHandlerAsync(eventType, callback)

Entfernt die Ereignishandler für einen unterstützten Ereignistyp. Hinweis: Ereignisse sind nur bei der Implementierung des Aufgabenbereichs verfügbar.

Informationen zu unterstützten Ereignissen finden Sie im Abschnitt Ereignisse des Postfachobjektmodells.

removeHandlerAsync(eventType: Office.EventType | string, callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Parameter

eventType: Office.EventType | string

Das Ereignis, das den Handler widerrufen soll.

callback: (asyncResult: Office.AsyncResult<void>) => void

Optional. Wenn die -Methode abgeschlossen ist, wird die im callback -Parameter übergebene Funktion mit einem einzelnen Parameter vom Typ Office.AsyncResultaufgerufen.

Gibt zurück

void

Hinweise