Abrufen und Festlegen von Add-In-Metadaten für ein Outlook-Add-InGet and set add-in metadata for an Outlook add-in

Sie können benutzerdefinierte Daten in Ihrem Outlook-Add-In verwalten, indem Sie eine der folgenden Optionen verwenden:You can manage custom data in your Outlook add-in by using either of the following:

  • Roamingeinstellungen, mit denen benutzerdefinierte Daten für das Postfach des Benutzers verwaltet werden.Roaming settings, which manage custom data for a user's mailbox.
  • Benutzerdefinierte Eigenschaften, mit denen benutzerdefinierte Daten für ein Element im Postfach des Benutzers verwaltet werden.Custom properties, which manage custom data for an item in a user's mailbox.

Beide gewähren Zugriff auf benutzerdefinierte Daten, auf die nur über Ihr Outlook-Add-In zugegriffen werden kann, jede Methode speichert die Daten jedoch getrennt voneinander, d. h. Benutzerdefinierte Eigenschaften können nicht auf über Roamingeinstellungen gespeicherten Daten zugreifen und umgekehrt. Die Daten werden auf dem Server für dieses Postfach gespeichert und es kann in nachfolgenden Outlook-Sitzungen in allen Formfaktoren auf diese zugegriffen werden, die das Outlook-Add-In unterstützt.Both of these give access to custom data that is only accessible by your Outlook add-in, but each method stores the data separately from the other. That is, the data stored through roaming settings is not accessible by custom properties, and vice versa. The data is stored on the server for that mailbox, and is accessible in subsequent Outlook sessions on all the form factors that the add-in supports.

Benutzerdefinierte Daten pro Postfach: RoamingeinstellungenCustom data per mailbox: roaming settings

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.You can specify data specific to a user's Exchange mailbox using the RoamingSettings object. Examples of such data include the user's personal data and preferences. Your mail add-in can access roaming settings when it roams on any device it's designed to run on (desktop, tablet, or smartphone).

Änderungen an diesen Daten werden in einer speicherinterne Kopie der Einstellungen für die aktuelle Outlook-Sitzung gespeichert. Sie müssen alle Roamingeinstellungen nach dem Aktualisieren explizit speichern, damit sie zur Verfügung stehen, sobald der Benutzer Ihr Outlook-Add-In das nächste Mal auf demselben oder einem anderen unterstützten Gerät öffnet.Changes to this data are stored on an in-memory copy of those settings for the current Outlook session. You should explicitly save all the roaming settings after updating them so that they will be available the next time the user opens your add-in, on the same or any other supported device.

Format der RoamingeinstellungenRoaming settings format

Die Daten in einem Objekt des Typs RoamingSettings werden als serialisierte JSON-Zeichenfolge (JavaScript Object Notation) gespeichert.The data in a RoamingSettings object is stored as a serialized JavaScript Object Notation (JSON) string.

Im Folgenden finden Sie ein Beispiel für die Struktur. Hierbei wird vorausgesetzt, dass es drei definierte Roamingeinstellungen mit den Namen add-in_setting_name_0, add-in_setting_name_1 und add-in_setting_name_2 gibt.The following is an example of the structure, assuming there are three defined roaming settings named add-in_setting_name_0, add-in_setting_name_1, and 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 RoamingeinstellungenLoading roaming settings

Ein E-Mail-Add-In lädt in der Regel die Roamingeinstellungen im Office.initialize-Ereignishandler.A mail add-in typically loads roaming settings in the Office.initialize event handler. Im folgenden JavaScript-Codebeispiel wird gezeigt, wie Sie vorhandene Roamingeinstellungen laden und die Werte der beiden Einstellungen customerName und customerBalance abrufen:The following JavaScript code example shows how to load existing roaming settings and get the values of 2 settings, customerName and customerBalance:

var _mailbox;
var _settings;
var _customerName;
var _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 RoamingeinstellungCreating or assigning a roaming setting

Ausgehend vom vorherigen Beispiel veranschaulicht die folgende JavaScript-Funktion setAddInSetting, wie die RoamingSettings.set-Methode verwendet wird, um eine Einstellung namens cookie mit dem heutigen Datum festzulegen. Anschließend behält sie die Daten mit der RoamingSettings.saveAsync-Methode, um alle Roamingeinstellungen erneut auf dem Server zu speichern.Continuing with the preceding example, the following JavaScript function, setAddInSetting, shows how to use the RoamingSettings.set method to set a setting named cookie with today's date, and persist the data by using the RoamingSettings.saveAsync method to save all the roaming settings back to the server.

Die set-Methode erstellt die Einstellung, wenn die Einstellung nicht bereits vorhanden sind, und weist der Einstellung den angegebenen Wert zu.The set method creates the setting if the setting does not already exist, and assigns the setting to the specified value. Die Methode saveAsync speichert Roamingeinstellungen asynchron.The saveAsync method saves roaming settings asynchronously. In diesem Codebeispiel wird die Rückrufmethode saveMyAddInSettingsCallback an saveAsync übergeben.This code sample passes a callback method, saveMyAddInSettingsCallback, to saveAsync. Nach Abschluss des asynchronen Aufrufs wird saveMyAddInSettingsCallback mit einem einzigen Parameter (asyncResult) aufgerufen.When the asynchronous call finishes, saveMyAddInSettingsCallback is called by using one parameter, asyncResult. Dieser Parameter ist ein AsyncResult-Objekt, das das Ergebnis und die Details zu dem asynchronen Aufruf enthält.This parameter is an AsyncResult object that contains the result of and any details about the asynchronous call. Sie können den optionalen userContext-Parameter verwenden, um jegliche Zustandsinformationen von dem asynchronen Aufruf an die Rückruffunktion zu übergeben.You can use the optional userContext parameter to pass any state information from the asynchronous call to the callback function.

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

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

Entfernen einer RoamingeinstellungRemoving a roaming setting

Als Fortsetzung der vorherigen Beispiele wird mit der JavaScript-Funktion removeAddInSetting veranschaulicht, wie Sie mit der RoamingSettings.remove-Methode die cookie-Einstellung entfernen und alle Roamingeinstellungen wieder auf dem Exchange-Server speichern.Also extending the preceding examples, the following JavaScript function, removeAddInSetting, shows how to use the RoamingSettings.remove method to remove the cookie setting and save all the roaming settings back to the Exchange Server.

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

Benutzerdefinierte Daten pro Element in einem Postfach: benutzerdefinierte EigenschaftenCustom data per item in a mailbox: custom properties

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. Auf diese Weise wird sichergestellt, dass beim zweiten Öffnen der Nachricht durch den Benutzer Ihr Mail-Add-In nicht zum zweiten Mal vorschlägt, den Termin zu erstellen.You can specify data specific to an item in the user's mailbox using the CustomProperties object. For example, your mail add-in could categorize certain messages and note the category using a custom property messageCategory. Or, if your mail add-in creates appointments from meeting suggestions in a message, you can use a custom property to track each of these appointments. This ensures that if the user opens the message again, your mail add-in doesn't offer to create the appointment a second time.

Ähnlich wie bei Roamingeinstellungen werden die Änderungen an benutzerdefinierten Eigenschaften in speicherinternen Kopien der Eigenschaften für die aktuelle Outlook-Sitzung gespeichert. Um sicherzustellen, dass diese benutzerdefinierten Eigenschaften in der nächsten Sitzung zur Verfügung stehen, verwenden Sie CustomProperties.saveAsync.Similar to roaming settings, changes to custom properties are stored on in-memory copies of the properties for the current Outlook session. To make sure these custom properties will be available in the next session, use CustomProperties.saveAsync.

Auf diese für Add-Ins oder Elemente spezifischen benutzerdefinierten Eigenschaften kann nur mithilfe des Objekts CustomProperties zugegriffen werden. Diese Eigenschaften weichen von den benutzerdefinierten MAPI-basierten UserProperties im Outlook-Objektmodell und den erweiterten Eigenschaften in den Exchange-Webdiensten ab. Mit dem Outlook-Objektmodell, EWS oder REST kann nicht direkt auf CustomProperties zugegriffen werden. Informationen zum Zugriff auf CustomProperties mit EWS oder REST finden Sie im Abschnitt Abrufen von custom properties mit EWS oder REST.These add-in-specific, item-specific custom properties can only be accessed by using the CustomProperties object. These properties are different from the custom, MAPI-based UserProperties in the Outlook object model, and extended properties in Exchange Web Services (EWS). You cannot directly access CustomProperties by using the Outlook object model, EWS, or REST. To learn how to access CustomProperties using EWS or REST, see the section Get custom properties using EWS or REST.

Verwenden benutzerdefinierter EigenschaftenUsing custom properties

Bevor Sie benutzerdefinierte Eigenschaften verwenden können, müssen Sie sie durch Aufrufen der loadCustomPropertiesAsync-Methode laden.Before you can use custom properties, you must load them by calling the loadCustomPropertiesAsync method. Nachdem Sie den Eigenschaftenbehälter erstellt haben, können Sie mithilfe der Methoden set und get benutzerdefinierte Eigenschaften hinzufügen und abrufen.After you have created the property bag, you can use the set and get methods to add and retrieve custom properties. Sie müssen die saveAsync-Methode verwenden, um am Eigenschaftenbehälter vorgenommene Änderungen zu speichern.You must use the saveAsync method to save any changes that you make to the property bag.

Hinweis

Da Outlook für Mac keine benutzerdefinierten Eigenschaften zwischenspeichert, könnten Mail-Add-Ins in Outlook für Mac bei einem Ausfall des Benutzernetzwerks nicht auf deren benutzerdefinierte Eigenschaften zugreifen.Because Outlook for Mac doesn't cache custom properties, if the user's network goes down, mail add-ins in Outlook for Mac would not be able to access their custom properties.

Beispiel für benutzerdefinierte EigenschaftenCustom properties example

Im folgenden Beispiel wird ein einfacher Methodensatz für ein Outlook-Add-In veranschaulicht, in dem benutzerdefinierte Eigenschaften verwendet werden. Sie können dieses Beispiel als Ausgangspunkt für ein eigenes Mail-Add-In nutzen, in dem benutzerdefinierte Eigenschaften verwendet werden.The following example shows a simplified set of methods for an Outlook add-in that uses custom properties. You can use this example as a starting point for your add-in that uses custom properties.

Dieses Beispiel umfasst die folgenden Methoden:This example includes the following methods:

  • Office.initialize – Initialisiert das Add-In und lädt den benutzerdefinierten Eigenschaftenbehälter vom Exchange-Server.Office.initialize -- Initializes the add-in and loads the custom property bag from the Exchange server.

  • customPropsCallback – Ruft den vom Server zurückgegebenen benutzerdefinierten Eigenschaftenbehälter ab und speichert ihn zur späteren Verwendung.customPropsCallback -- Gets the custom property bag that is returned from the server and saves it for later use.

  • updateProperty – Legt eine bestimmte Eigenschaft fest oder aktualisiert sie und speichert die Änderung dann auf dem Server.updateProperty -- Sets or updates a specific property, and then saves the change to the server.

  • removeProperty – Entfernt eine bestimmte Eigenschaft aus dem Eigenschaftenbehälter und speichert die Entfernung dann auf dem Server.removeProperty -- Removes a specific property from the property bag, and then saves the removal to the server.

var _mailbox;
var _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() {
  var myProp = _customProps.get("myProp");
}

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

// Remove a custom property.
function removeProperty(name) {
  _customProps.remove(name);
  // Save all custom properties to server.
  _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 abrufenGet custom properties using EWS or REST

Um CustomProperties mit EWS oder REST abzurufen, sollten Sie zuerst den Namen der MAPI-basierten erweiterten Eigenschaft festlegen.To get CustomProperties using EWS or REST, you should first determine the name of its MAPI-based extended property. Sie können die Eigenschaft dann auf die gleiche Weise abrufen wie eine MAPI-basierte erweiterte Eigenschaft.You can then get that property in the same way you would get any MAPI-based extended property.

Erfahren Sie, wie benutzerdefinierte Eigenschaften in einem Element gespeichert werdenHow custom properties are stored on an item

Durch ein Add-In festgelegte benutzerdefinierte Eigenschaften entsprechen nicht normalen MAPI-basierten Eigenschaften.Custom properties set by an add-in are not equivalent to normal MAPI-based properties. Add-In-APIs serialisieren alle CustomProperties des Add-Ins als JSON-Nutzlast und speichern Sie in einer einzelnen MAPI-basierten erweiterten Eigenschaft, deren Name cecp-<app-guid> ist (<app-guid> ist die ID des Add-Ins), und die GUID des Eigenschaftensatzes ist {00020329-0000-0000-C000-000000000046}.Add-in APIs serialize all your add-in's CustomProperties as a JSON payload and then save them in a single MAPI-based extended property whose name is cecp-<app-guid> (<app-guid> is your add-in's ID) and property set GUID is {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.(For more information about this object, see MS-OXCEXT 2.2.5 Mail App Custom Properties.) You can then use EWS or REST to get this MAPI-based property.

Benutzerdefinierte Eigenschaften mit EWS abrufenGet custom properties using EWS

Ihr E-Mail-Add-In kann die MAPI-basierte erweiterte Eigenschaft CustomProperties mit dem EWS-Vorgang GetItem abrufen.Your mail add-in can get the CustomProperties MAPI-based extended property by using the EWS GetItem operation. Greifen Sie auf der Serverseite auf GetItem mithilfe eines Rückruftokens zu oder auf der Clientseite mithilfe der Methode mailbox.makeEwsRequestAsync.Access GetItem on the server side by using a callback token, or on the client side by using the mailbox.makeEwsRequestAsync method. Geben Sie in der GetItem-Anforderung die MAPI-basierte CustomProperties-Eigenschaft im Eigenschaftensatz mit den Angaben aus dem vorherigen Abschnitt Erfahren Sie, wie benutzerdefinierte Eigenschaften in einem Element gespeichert werden an.In the GetItem request, specify the CustomProperties MAPI-based property in its property set using the details provided in the preceding section How custom properties are stored on an item.

Das folgende Beispiel zeigt, wie Sie ein Element und seine benutzerdefinierten Eigenschaften abrufen.The following example shows how to get an item and its custom properties.

Wichtig

Ersetzen Sie im folgenden Beispiel <app-guid> durch die ID Ihres Add-Ins.In the following example, replace <app-guid> with your add-in's ID.

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.You can also get more custom properties if you specify them in the request string as other ExtendedFieldURI elements.

Abrufen von benutzerdefinierte Eigenschaften mit RESTGet custom properties using 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 your add-in, you can construct your REST query against messages and events to get the ones that already have custom properties. 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.In your query, you should include the CustomProperties MAPI-based property and its property set using the details provided in the section How custom properties are stored on an item.

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.The following example shows how to get all events that have any custom properties set by your add-in and ensure that the response includes the value of the property so you can apply further filtering logic.

Wichtig

Ersetzten Sie im folgenden Beispiel <app-guid> durch die ID Ihres Add-Ins.In the following example, replace <app-guid> with your add-in's ID.

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.For other examples that use REST to get single-value MAPI-based extended properties, see Get singleValueExtendedProperty.

Das folgende Beispiel zeigt, wie Sie ein Element und seine benutzerdefinierten Eigenschaften abrufen.The following example shows how to get an item and its custom properties. In der Rückruffunktion für die done-Methode enthält item.SingleValueExtendedProperties eine Liste der erforderlichen benutzerdefinierten Eigenschaften.In the callback function for the done method, item.SingleValueExtendedProperties contains a list of the requested custom properties.

Wichtig

Ersetzen Sie im folgenden Beispiel <app-guid> durch die ID Ihres Add-Ins.In the following example, replace <app-guid> with your add-in's ID.

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));
        }
    }
);

Siehe auchSee also