Просмотр и изменение метаданных для надстройки Outlook

Статья
02/29/2024

Для управления пользовательскими данными в настройке Outlook можно использовать следующее:

параметры перемещения, которые управляют пользовательскими данными для почтового ящика пользователя;
настраиваемые свойства, которые управляют пользовательскими данными для элемента в почтовом ящике пользователя.

Оба метода предоставляют доступ к пользовательским данным, доступным только надстройке Outlook, но каждый метод хранит данные отдельно от другого. То есть данные, хранящиеся с помощью перемещаемых параметров, недоступны для пользовательских свойств, и наоборот. Перемещаемые параметры хранятся в почтовом ящике пользователя, а пользовательские свойства — в сообщении или встрече. Сохраненные данные доступны в последующих сеансах Outlook для всех форм-факторов, поддерживаемых надстройкой.

Пользовательские данные на один почтовый ящик: параметры перемещения

Вы можете указать данные, специфичные для пользователя почтового ящика Exchange, с помощью объекта RoamingSettings. Примерами таких данных являются личные данные и предпочтения пользователя. Ваша почтовая надстройка может получить доступ к параметрам перемещения, когда перемещение происходит на любом из устройств, предназначенных для работы (настольный ПК, планшет или смартфон).

Изменения этих данных хранятся в памяти текущего сеанса Outlook. Вы должны явно сохранить все перемещаемые параметры после их обновления, чтобы они были доступны при следующем открытии надстройки пользователем на том же или любом другом поддерживаемом устройстве.

Формат параметров перемещения

Данные в объекте RoamingSettings хранятся в виде сериализованной строки нотации объектов JavaScript (JSON).

Ниже приведен пример структуры, предполагающий наличие трех определенных перемещаемых параметров с именами add-in_setting_name_0, add-in_setting_name_1и 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"
}

Загрузка параметров перемещения

Надстройка почты обычно загружает параметры перемещения в обработчик событий Office.initialize. В следующем примере кода JavaScript показано, как загрузить существующие параметры роуминга и получить значения двух параметров: customerName и customerBalance.

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

Создание или назначение параметра перемещения

В приведенном выше примере следующая функция JavaScript , показывает, setAddInSettingкак использовать метод RoamingSettings.set для задания параметра с именем cookie с текущей датой и сохранения данных с помощью метода RoamingSettings.saveAsync для сохранения всех перемещаемых параметров в почтовом ящике пользователя.

Метод set создает параметр, если параметр еще не существует, и присваивает ему указанное значение. Метод saveAsync асинхронно сохраняет перемещаемые параметры. В этом примере кода функция saveMyAddInSettingsCallbackобратного вызова передается saveAsyncв . После завершения saveMyAddInSettingsCallback асинхронного вызова вызывается с помощью одного параметра asyncResult. Этот параметр является объектом AsyncResult, который содержит результат и все сведения об асинхронном вызове. Необязательный параметр userContext можно использовать для передачи сведений о состоянии из асинхронного вызова в функцию обратного звонка.

// 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.
  }
}

Удаление параметра перемещения

Кроме того, в расширении предыдущих примеров следующая функция JavaScript, , показывает, removeAddInSettingкак использовать метод RoamingSettings.remove для удаления cookie параметра и сохранения всех перемещаемых параметров в почтовом ящике.

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

Пользовательские данные для каждого элемента в почтовом ящике: пользовательские свойства

Вы также можете указать данные, характерные для элемента в почтовом ящике пользователя, используя объект CustomProperties. Например, ваша почтовая надстройка могла бы категоризировать некоторые сообщения и отмечать категорию с помощью настраиваемого свойства messageCategory. Либо, если ваша почтовая надстройка создает встречи из сообщений с предложениями о собрании, вы можете использовать настраиваемое свойство, чтобы отслеживать каждую из этих встреч. Это гарантирует, что если пользователь снова откроет сообщение, ваша почтовая надстройка не предложит создать встречу во второй раз.

Аналогично параметрам перемещения, изменения настраиваемых свойств хранятся в копии контейнера свойств для текущего сеанса Outlook. Чтобы убедиться, что эти настраиваемые свойства будут доступны в следующем сеансе, используйте CustomProperties.saveAsync.

Доступ к этим настраиваемым свойствам, зависящим от конкретного элемента, можно получить только с помощью CustomProperties объекта . Эти свойства отличаются от пользовательских свойств UserProperties на основе MAPI в объектной модели Outlook и расширенных свойств в веб-службах Exchange (EWS). Вы не можете получить прямой доступ CustomProperties с помощью объектной модели Outlook, EWS или REST. Сведения о том, как получить доступ CustomProperties с помощью EWS или REST, см. в разделе Получение пользовательских свойств с помощью EWS или REST.

Примечание.

Пользовательские свойства доступны только надстройке, создавшей их, и только через почтовый элемент, в котором они были сохранены. По этой причине свойства, заданные в режиме создания, не передаются получателям почтового элемента. При отправке сообщения или встречи с пользовательскими свойствами доступ к его свойствам можно получить из элемента в папке Отправленные . Чтобы разрешить получателям получать пользовательские данные, заданные надстройкой, рассмотрите возможность использования InternetHeaders .

Использование настраиваемых свойств

Перед использованием настраиваемых свойств необходимо загрузить их, вызвав метод loadCustomPropertiesAsync. После создания контейнера свойств можно использовать методы set и get для добавления и извлечения пользовательских свойств. Чтобы сохранить любые изменения, внесенные в контейнер свойств, необходимо использовать метод saveAsync.

Примечание.

При использовании пользовательских свойств в надстройках Outlook имейте в виду следующее:

Outlook для Mac не кэшируют пользовательские свойства. Если сеть пользователя выйдет из строя, надстройки в Outlook на Mac не смогут получить доступ к своим пользовательским свойствам.
В Outlook в Windows пользовательские свойства, сохраненные в режиме создания, сохраняются только после закрытия создаваемого элемента или после Office.context.mailbox.item.saveAsync вызова.

Пример пользовательских свойств

В следующем примере показан упрощенный набор функций и методов для надстройки Outlook, которая использует пользовательские свойства. Этот пример можно использовать в качестве отправной точки для создания надстройки, использующей настраиваемые свойства.

Этот пример включает следующие функции и методы.

Office.initialize: инициализирует надстройку и загружает контейнер настраиваемых свойств с сервера Exchange Server.
customPropsCallback — возвращает контейнер настраиваемых свойств, возвращенный сервером, и сохраняет его локально для последующего использования.
updateProperty — задает или обновляет определенное свойство, а затем сохраняет изменения в локальном контейнере свойств.
removeProperty — удаляет определенное свойство из контейнера свойств, а затем сохраняет эти изменения.

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.
  }
}

Просмотр настраиваемых свойств с помощью EWS или REST

Чтобы получить объект CustomProperties с помощью EWS или REST, необходимо сначала определить имя его расширенного свойства, основанного на интерфейсе MAPI. Затем можно получить это свойство способом, аналогичным используемому при получении любого расширенного свойства, основанного на интерфейсе MAPI.

Способ хранения настраиваемых свойств в элементе

Пользовательские свойства, заданные надстройкой, не эквивалентны обычным свойствам на основе MAPI. API-интерфейсы надстроек сериализуют все надстройки CustomProperties в виде полезных данных JSON, а затем сохраняют их в одном расширенном свойстве на основе MAPI, имя которого — cecp-<app-guid> (<app-guid> — идентификатор надстройки), а guid набора свойств — {00020329-0000-0000-C000-000000000046}. (Дополнительные сведения об этом объекте см. в статье MS-OXCEXT 2.2.5 Настраиваемые свойства почтового приложения). Затем можно использовать EWS или REST, чтобы получить это свойство, основанное на интерфейсе MAPI.

Просмотр настраиваемых свойств с помощью EWS

Ваша почтовая надстройка может получить расширенное CustomProperties свойство на основе MAPI с помощью операции GetItem EWS. Доступ GetItem на стороне сервера с помощью маркера обратного вызова или на стороне клиента с помощью метода mailbox.makeEwsRequestAsync . В запросе укажите CustomProperties свойство на основе MAPI в его наборе свойств, используя сведения, описанные в предыдущем разделе Как пользовательские свойства хранятся в элементе.GetItem

В приведенном ниже примере показано, как получить элемент и его настраиваемые свойства.

Важно!

В приведенном ниже примере замените <app-guid> идентификатором своей надстройки.

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

Также можно получить дополнительные настраиваемые свойства, если указать их в строке запроса как другие элементы ExtendedFieldURI.

Просмотр настраиваемых свойств с помощью REST

В своей надстройке можно создать запрос REST для получения сообщений и событий, уже имеющих настраиваемые свойства. В запрос нужно включить расширенное свойство на основе интерфейса MAPI CustomProperties и его набор свойств с помощью сведений, указанных в разделе Способ хранения настраиваемых свойств в элементе.

В приведенном ниже примере показано, как получить все события, которые содержат любые настраиваемые свойства, присвоенные вашей надстройкой, и обеспечить наличие в отклике значения свойства, чтобы в дальнейшем можно было применить логику фильтрации.

Важно!

В приведенном ниже примере замените <app-guid> идентификатором своей надстройки.

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>')

Другие примеры использования REST для получения однозначного расширенного свойства, основанного на интерфейсе MAPI, см. в статье Получение объекта singleValueExtendedProperty.

В приведенном ниже примере показано, как получить элемент и его настраиваемые свойства. В функции обратного вызова для метода done объект item.SingleValueExtendedProperties содержит список требуемых настраиваемых свойств.

Важно!

В приведенном ниже примере замените <app-guid> идентификатором своей надстройки.

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

Поведение платформы в сообщениях

В следующей таблице описано сохраненное поведение пользовательских свойств в сообщениях для различных клиентов Outlook.

Сценарий	Outlook для Windows	Outlook в Интернете и в новом клиенте Windows (предварительная версия)	Outlook для Mac
Создание новой версии	null	null	null
Ответить, ответить всем	null	null	null
Переслать	Загружает свойства родительского элемента	null	null
Отправленный элемент из новой композиции	null	null	null
Отправленный элемент из ответа или ответить всем	null	null	null
Отправленный элемент из пересылки	Удаляет свойства родительского объекта, если они не сохранены	null	null

Чтобы справиться с ситуацией в Outlook в Windows, выполните следующие действия:

Проверьте наличие существующих свойств при инициализации надстройки и сохраните их или очистите при необходимости.
При настройке настраиваемых свойств добавьте дополнительное свойство, чтобы указать, были ли добавлены пользовательские свойства в режиме чтения. Это поможет вам определить, было ли свойство создано в режиме создания или унаследовано от родительского.
Чтобы проверка, если пользователь пересылает сообщение или отвечает на сообщение, можно использовать item.getComposeTypeAsync (доступно из набора требований 1.10).

Просмотр и изменение метаданных для надстройки Outlook

Пользовательские данные на один почтовый ящик: параметры перемещения

Формат параметров перемещения

Загрузка параметров перемещения

Создание или назначение параметра перемещения

Удаление параметра перемещения

Пользовательские данные для каждого элемента в почтовом ящике: пользовательские свойства

Использование настраиваемых свойств

Пример пользовательских свойств

Просмотр настраиваемых свойств с помощью EWS или REST

Способ хранения настраиваемых свойств в элементе

Просмотр настраиваемых свойств с помощью EWS

Просмотр настраиваемых свойств с помощью REST

Поведение платформы в сообщениях

См. также

Обратная связь

Дополнительные ресурсы