Abrufen und Festlegen von Add-In-Metadaten für ein Outlook-Add-In

  • Artikel

Sie können benutzerdefinierte Daten in Ihrem Outlook-Add-In verwalten, indem Sie eine der folgenden Optionen verwenden:

  • Roamingeinstellungen, mit denen benutzerdefinierte Daten für das Postfach des Benutzers verwaltet werden.
  • Benutzerdefinierte Eigenschaften, mit denen benutzerdefinierte Daten für ein Element im Postfach des Benutzers verwaltet werden.

Beides gibt Zugriff auf benutzerdefinierte Daten, auf die nur Ihr Outlook-Add-In zugreifen kann, aber jede Methode speichert die Daten getrennt von der anderen. Das heißt, auf die über Roamingeinstellungen gespeicherten Daten kann von benutzerdefinierten Eigenschaften nicht zugegriffen werden und umgekehrt. Roamingeinstellungen werden im Postfach des Benutzers gespeichert, während benutzerdefinierte Eigenschaften für eine Nachricht oder einen Termin gespeichert werden. Auf gespeicherte Daten kann in nachfolgenden Outlook-Sitzungen auf alle Formfaktoren zugegriffen werden, die das Add-In unterstützt.

Benutzerdefinierte Daten pro Postfach: Roamingeinstellungen

Mithilfe des RoamingSettings-Objekts können Sie Daten angeben, die spezifisch für das Postfach eines Exchange-Benutzers sind. Beispiele solcher Daten sind die persönlichen Daten und Einstellungen des Benutzers. Ihr Mail-Add-In kann auf Roamingeinstellungen zugreifen, wenn das Roaming auf dem entsprechenden Gerät (Desktop, Tablet oder Smartphone) aktiviert ist.

Änderungen an diesen Daten werden in einer speicherinterne Kopie der Einstellungen für die aktuelle Outlook-Sitzung gespeichert. Sie sollten alle Roamingeinstellungen nach dem Aktualisieren explizit speichern, damit sie verfügbar sind, wenn der Benutzer Das Add-In das nächste Mal auf demselben oder einem anderen unterstützten Gerät öffnet.

Format der Roamingeinstellungen

Die Daten in einem Objekt des Typs RoamingSettings werden als serialisierte JSON-Zeichenfolge (JavaScript Object Notation) gespeichert.

Im Folgenden finden Sie ein Beispiel für die -Struktur, vorausgesetzt, es gibt drei definierte Roamingeinstellungen mit den Namen add-in_setting_name_0, add-in_setting_name_1und add-in_setting_name_2.

{
  "add-in_setting_name_0": "add-in_setting_value_0",
  "add-in_setting_name_1": "add-in_setting_value_1",
  "add-in_setting_name_2": "add-in_setting_value_2"
}

Laden der Roamingeinstellungen

Ein E-Mail-Add-In lädt in der Regel die Roamingeinstellungen im Office.initialize-Ereignishandler. Das folgende JavaScript-Codebeispiel zeigt, wie vorhandene Roamingeinstellungen geladen und die Werte der beiden Einstellungen customerName und customerBalance abgerufen werden.

let _mailbox;
let _settings;
let _customerName;
let _customerBalance;

// The initialize function is required for all add-ins.
Office.initialize = function () {
  // Initialize instance variables to access API objects.
  _mailbox = Office.context.mailbox;
  _settings = Office.context.roamingSettings;
  _customerName = _settings.get("customerName");
  _customerBalance = _settings.get("customerBalance");
}

Erstellen oder Zuweisen einer Roamingeinstellung

Die folgende JavaScript-Funktion zeigt, wie die RoamingSettings.set-Methode verwendet wird, setAddInSettingum eine Einstellung mit dem Namen cookie des heutigen Datums festzulegen und die Daten mithilfe der RoamingSettings.saveAsync-Methode beizubehalten, um alle Roamingeinstellungen im Postfach des Benutzers zu speichern.

Die set -Methode erstellt die Einstellung, wenn die Einstellung noch nicht vorhanden ist, und weist die Einstellung dem angegebenen Wert zu. Die saveAsync -Methode speichert Roamingeinstellungen asynchron. In diesem Codebeispiel wird die Rückruffunktion saveMyAddInSettingsCallbackan saveAsyncübergeben. Wenn der asynchrone Aufruf abgeschlossen ist, saveMyAddInSettingsCallback wird mit einem Parameter aufgerufen, asyncResult. Dieser Parameter ist ein AsyncResult-Objekt, das das Ergebnis und die Details zu dem asynchronen Aufruf enthält. Sie können den optionalen userContext-Parameter verwenden, um jegliche Zustandsinformationen von dem asynchronen Aufruf an die Rückruffunktion zu übergeben.

// Set a roaming setting.
function setAddInSetting() {
  _settings.set("cookie", Date());
  // Save roaming settings to the mailbox, so that they'll be available in the next session.
  _settings.saveAsync(saveMyAddInSettingsCallback);
}

// Callback function after saving custom roaming settings.
function saveMyAddInSettingsCallback(asyncResult) {
  if (asyncResult.status == Office.AsyncResultStatus.Failed) {
    // Handle the failure.
  }
}

Entfernen einer Roamingeinstellung

Die folgende JavaScript-Funktion zeigt außerdem, wie die RoamingSettings.remove-Methode verwendet wird, removeAddInSettingum die cookie Einstellung zu entfernen und alle Roamingeinstellungen im Postfach zu speichern.

// Remove an add-in setting.
function removeAddInSetting()
{
  _settings.remove("cookie");
  // Save changes to the roaming settings for the mailbox, so that they'll be available in the next session.
  _settings.saveAsync(saveMyAddInSettingsCallback);
}

Benutzerdefinierte Daten pro Element in einem Postfach: benutzerdefinierte Eigenschaften

Sie können Daten für ein bestimmtes Element im Benutzerpostfach mit dem CustomProperties-Objekt angeben. Ihr Add-In könnte beispielsweise bestimmte Nachrichten kategorisieren und die Kategorie mithilfe der benutzerdefinierten Eigenschaft messageCategory kennzeichnen. Wenn Ihr Mail-Add-In Termine aus Besprechungsvorschlägen in einer Nachricht erstellt, können Sie mit einer benutzerdefinierten Eigenschaft diese Termine nachverfolgen. Dadurch wird sichergestellt, dass ihr E-Mail-Add-In nicht anbietet, den Termin ein zweites Mal zu erstellen, wenn der Benutzer die Nachricht erneut öffnet.

Ähnlich wie bei Roamingeinstellungen werden die Änderungen an benutzerdefinierten Eigenschaften in speicherinternen Kopien er Eigenschaften der aktuellen Outlook-Sitzung gespeichert. Um sicherzustellen, dass diese benutzerdefinierten Eigenschaften in der nächsten Sitzung verfügbar sind, verwenden Sie CustomProperties.saveAsync.

Auf diese add-in-spezifischen, elementspezifischen benutzerdefinierten Eigenschaften kann nur mithilfe des CustomProperties -Objekts zugegriffen werden. Diese Eigenschaften unterscheiden sich von den benutzerdefinierten MAPI-basierten UserProperties im Outlook-Objektmodell und erweiterten Eigenschaften in Exchange-Webdiensten (EWS). Sie können nicht direkt auf das Outlook-Objektmodell, EWS oder REST zugreifen CustomProperties . Informationen zum Zugreifen CustomProperties mithilfe von EWS oder REST finden Sie im Abschnitt Abrufen benutzerdefinierter Eigenschaften mithilfe von EWS oder REST.

Hinweis

Benutzerdefinierte Eigenschaften sind nur für das Add-In verfügbar, das sie erstellt hat, und nur über das E-Mail-Element, in dem sie gespeichert wurden. Aus diesem Gründen werden Eigenschaften, die im Verfassenmodus festgelegt werden, nicht an Empfänger des E-Mail-Elements übertragen. Wenn eine Nachricht oder ein Termin mit benutzerdefinierten Eigenschaften gesendet wird, kann über das Element im Ordner Gesendete Elemente auf ihre Eigenschaften zugegriffen werden. Damit Empfänger die benutzerdefinierten Daten empfangen können, die Ihr Add-In festlegt, sollten Sie stattdessen InternetHeaders verwenden.

Verwenden benutzerdefinierter Eigenschaften

Bevor Sie benutzerdefinierte Eigenschaften verwenden können, müssen Sie sie durch Aufrufen der loadCustomPropertiesAsync-Methode laden. Nachdem Sie den Eigenschaftenbehälter erstellt haben, können Sie die Set - und get-Methoden verwenden, um benutzerdefinierte Eigenschaften hinzuzufügen und abzurufen. Sie müssen die saveAsync-Methode verwenden, um am Eigenschaftenbehälter vorgenommene Änderungen zu speichern.

Hinweis

Beachten Sie bei der Verwendung von benutzerdefinierten Eigenschaften in Outlook-Add-Ins Folgendes:

  • Outlook auf Mac speichert keine benutzerdefinierten Eigenschaften zwischen. Wenn das Netzwerk des Benutzers ausfällt, können Add-Ins in Outlook auf Mac nicht auf ihre benutzerdefinierten Eigenschaften zugreifen.
  • In Outlook unter Windows werden benutzerdefinierte Eigenschaften, die im Verfassenmodus gespeichert wurden, nur beibehalten, nachdem das zu verfassende Element geschlossen wurde oder nach Office.context.mailbox.item.saveAsync dem Aufruf aufgerufen wurde.

Beispiel für benutzerdefinierte Eigenschaften

Das folgende Beispiel zeigt einen vereinfachten Satz von Funktionen und Methoden für ein Outlook-Add-In, das benutzerdefinierte Eigenschaften verwendet. Sie können dieses Beispiel als Ausgangspunkt für ein eigenes Mail-Add-In nutzen, in dem benutzerdefinierte Eigenschaften verwendet werden.

Dieses Beispiel enthält die folgenden Funktionen und Methoden.

  • Office.initialize – Initialisiert das Add-In und lädt den benutzerdefinierten Eigenschaftenbehälter vom Exchange-Server.

  • customPropsCallback : Ruft den benutzerdefinierten Eigenschaftenbehälter ab, der vom Server zurückgegeben wird, und speichert ihn zur späteren Verwendung lokal.

  • updateProperty : Legt eine bestimmte Eigenschaft fest oder aktualisiert diese und speichert die Änderung dann im lokalen Eigenschaftenbehälter.

  • removeProperty : Entfernt eine bestimmte Eigenschaft aus dem Eigenschaftenbehälter und speichert dann diese Änderungen.

let _mailbox;
let _customProps;

// The initialize function is required for all add-ins.
Office.initialize = function () {
  _mailbox = Office.context.mailbox;
  _mailbox.item.loadCustomPropertiesAsync(customPropsCallback);
}

// Callback function from loading custom properties.
function customPropsCallback(asyncResult) {
  if (asyncResult.status == Office.AsyncResultStatus.Failed) {
    // Handle the failure.
  }
  else {
    // Successfully loaded custom properties,
    // can get them from the asyncResult argument.
    _customProps = asyncResult.value;
  }
}

// Get individual custom property.
function getProperty() {
  const myProp = _customProps.get("myProp");
}

// Set individual custom property.
function updateProperty(name, value) {
  _customProps.set(name, value);
  // Save all custom properties to the mail item.
  _customProps.saveAsync(saveCallback);
}

// Remove a custom property.
function removeProperty(name) {
  _customProps.remove(name);
  // Save all custom properties to the mail item.
  _customProps.saveAsync(saveCallback);
}

// Callback function from saving custom properties.
function saveCallback() {
  if (asyncResult.status == Office.AsyncResultStatus.Failed) {
    // Handle the failure.
  }
}

Benutzerdefinierte Eigenschaften mit EWS oder REST abrufen

Um CustomProperties mit EWS oder REST abzurufen, sollten Sie zuerst den Namen der MAPI-basierten erweiterten Eigenschaft festlegen. Sie können die Eigenschaft dann auf die gleiche Weise abrufen wie eine MAPI-basierte erweiterte Eigenschaft.

Erfahren Sie, wie benutzerdefinierte Eigenschaften in einem Element gespeichert werden

Benutzerdefinierte Eigenschaften, die von einem Add-In festgelegt werden, entsprechen nicht normalen MAPI-basierten Eigenschaften. Add-In-APIs serialisieren alle Add-Ins CustomProperties als JSON-Nutzlast und speichern sie dann in einer einzelnen MAPI-basierten erweiterten Eigenschaft, deren Name cecp-<app-guid> (<app-guid> ist die ID Ihres Add-Ins) und die Eigenschaftensatz-GUID lautet {00020329-0000-0000-C000-000000000046}. (Weitere Informationen über dieses Objekt finden Sie unter MS-OXCEXT 2.2.5 Benutzerdefinierte Eigenschaften von Mail-Apps.) Sie können dann EWS oder REST zum Abrufen der MAPI-basierten Eigenschaft verwenden.

Benutzerdefinierte Eigenschaften mit EWS abrufen

Ihr E-Mail-Add-In kann die CustomProperties MAPI-basierte erweiterte Eigenschaft mithilfe des EWS GetItem-Vorgangs abrufen. Zugriff GetItem auf serverseitiger Seite mithilfe eines Rückruftokens oder clientseitig mithilfe der mailbox.makeEwsRequestAsync-Methode . Geben Sie in der GetItem Anforderung die CustomProperties MAPI-basierte Eigenschaft in ihrem Eigenschaftensatz an, indem Sie die Details im vorherigen Abschnitt Speichern benutzerdefinierter Eigenschaften für ein Element verwenden.

Das folgende Beispiel zeigt, wie Sie ein Element und seine benutzerdefinierten Eigenschaften abrufen.

Wichtig

Ersetzen Sie im folgenden Beispiel <app-guid> durch die ID Ihres Add-Ins.

let request_str =
    '<?xml version="1.0" encoding="utf-8"?>' +
    '<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 xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"' +
                     'xmlns:wsa="http://www.w3.org/2005/08/addressing">' +
            '<t:RequestServerVersion Version="Exchange2010_SP1"/>' +
        '</soap:Header>' +
        '<soap:Body>' +
            '<m:GetItem>' +
                '<m:ItemShape>' +
                    '<t:BaseShape>AllProperties</t:BaseShape>' +
                    '<t:IncludeMimeContent>true</t:IncludeMimeContent>' +
                    '<t:AdditionalProperties>' +
                        '<t:ExtendedFieldURI ' +
                          'DistinguishedPropertySetId="PublicStrings" ' +
                          'PropertyName="cecp-<app-guid>"' +
                          'PropertyType="String" ' +
                        '/>' +
                    '</t:AdditionalProperties>' +
                '</m:ItemShape>' +
                '<m:ItemIds>' +
                    '<t:ItemId Id="' +
                      Office.context.mailbox.item.itemId +
                    '"/>' +
                '</m:ItemIds>' +
            '</m:GetItem>' +
        '</soap:Body>' +
    '</soap:Envelope>';

Office.context.mailbox.makeEwsRequestAsync(
    request_str,
    function(asyncResult) {
        if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
            console.log(asyncResult.value);
        }
        else {
            console.log(JSON.stringify(asyncResult));
        }
    }
);

Sie können auch weitere benutzerdefinierte Eigenschaften abrufen, wenn Sie sie in der Abfragezeichenfolge als weitere ExtendedFieldURI-Elemente angeben.

Abrufen von benutzerdefinierte Eigenschaften mit REST

In Ihrem Add-In können Sie die REST-Abfrage für Nachrichten und Ereignisse so einstellen, dass diejenigen abgerufen werden, die bereits benutzerdefinierte Eigenschaften besitzen. In Ihrer Abfrage sollten Sie die MAPI-basierte CustomProperties-Eigenschaft und den Eigenschaftensatz mit den Angaben aus dem Abschnitt Erfahren Sie, wie benutzerdefinierte Eigenschaften in einem Element gespeichert werden angeben.

Im folgenden Beispiel erfahren Sie, wie Sie alle Ereignisse abrufen, für die benutzerdefinierte Eigenschaften durch Ihr Add-In festlegt werden, und wie Sie sicherstellen, dass die Antwort den Wert der Eigenschaft enthält, sodass Sie weitere Filterlogik anwenden können.

Wichtig

Ersetzten Sie im folgenden Beispiel <app-guid> durch die ID Ihres Add-Ins.

GET https://outlook.office.com/api/v2.0/Me/Events?$filter=SingleValueExtendedProperties/Any
  (ep: ep/PropertyId eq 'String {00020329-0000-0000-C000-000000000046}
  Name cecp-<app-guid>' and ep/Value ne null)
  &$expand=SingleValueExtendedProperties($filter=PropertyId eq 'String
  {00020329-0000-0000-C000-000000000046} Name cecp-<app-guid>')

Weitere Beispiele, in denen REST verwendet wird, um einwertige MAPI-basierte erweiterte Eigenschaften abzurufen, finden Sie unter Abrufen von singleValueExtendedProperty.

Das folgende Beispiel zeigt, wie Sie ein Element und seine benutzerdefinierten Eigenschaften abrufen. In der Rückruffunktion für die done-Methode enthält item.SingleValueExtendedProperties eine Liste der erforderlichen benutzerdefinierten Eigenschaften.

Wichtig

Ersetzen Sie im folgenden Beispiel <app-guid> durch die ID Ihres Add-Ins.

Office.context.mailbox.getCallbackTokenAsync(
    {
        isRest: true
    },
    function (asyncResult) {
        if (asyncResult.status === Office.AsyncResultStatus.Succeeded
            && asyncResult.value !== "") {
            let item_rest_id = Office.context.mailbox.convertToRestId(
                Office.context.mailbox.item.itemId,
                Office.MailboxEnums.RestVersion.v2_0);
            let rest_url = Office.context.mailbox.restUrl +
                           "/v2.0/me/messages('" +
                           item_rest_id +
                           "')";
            rest_url += "?$expand=SingleValueExtendedProperties($filter=PropertyId eq 'String {00020329-0000-0000-C000-000000000046} Name cecp-<app-guid>')";

            let auth_token = asyncResult.value;
            $.ajax(
                {
                    url: rest_url,
                    dataType: 'json',
                    headers:
                        {
                            "Authorization":"Bearer " + auth_token
                        }
                }
                ).done(
                    function (item) {
                        console.log(JSON.stringify(item));
                    }
                ).fail(
                    function (error) {
                        console.log(JSON.stringify(error));
                    }
                );
        } else {
            console.log(JSON.stringify(asyncResult));
        }
    }
);

Plattformverhalten in Nachrichten

In der folgenden Tabelle sind gespeicherte verhalten benutzerdefinierte Eigenschaften in Nachrichten für verschiedene Outlook-Clients zusammengefasst.

Szenario Outlook im Web und auf einem neuen Windows-Client (Vorschau) Klassisches Outlook unter Windows Outlook für Mac
Neuer Verfassen null null null
Antworten, allen antworten null null null
Weiterleiten null Lädt die Eigenschaften des übergeordneten Elements. null
Gesendetes Element aus dem neuen Verfassen null null null
Gesendetes Element aus "Antworten" oder "Allen antworten" null null null
Element von vorwärts gesendet null Entfernt die Eigenschaften des übergeordneten Elements, wenn sie nicht gespeichert wurden. null

So behandeln Sie die Situation in Outlook unter Windows:

  1. Überprüfen Sie bei der Initialisierung Ihres Add-Ins auf vorhandene Eigenschaften, und behalten Sie sie bei Bedarf bei, oder löschen Sie sie.
  2. Schließen Sie beim Festlegen benutzerdefinierter Eigenschaften eine zusätzliche Eigenschaft ein, um anzugeben, ob die benutzerdefinierten Eigenschaften im Lesemodus hinzugefügt wurden. Dadurch können Sie unterscheiden, ob die Eigenschaft im Verfassenmodus erstellt oder vom übergeordneten Element geerbt wurde.
  3. Um zu überprüfen, ob der Benutzer eine Nachricht weiterleitet oder darauf antwortet, können Sie item.getComposeTypeAsync (verfügbar im Anforderungssatz 1.10) verwenden.

Siehe auch