Вы можете указать данные, специфичные для пользователя почтового ящика Exchange, с помощью объекта RoamingSettings. Примерами таких данных являются личные данные и предпочтения пользователя. Ваша почтовая надстройка может получить доступ к параметрам перемещения, когда перемещение происходит на любом из устройств, предназначенных для работы (настольный ПК, планшет или смартфон).
Изменения этих данных хранятся в памяти текущего сеанса Outlook. Вы должны явно сохранить все перемещаемые параметры после их обновления, чтобы они были доступны при следующем открытии надстройки пользователем на том же или любом другом поддерживаемом устройстве.
Важно!
Хотя API надстройки Outlook ограничивает доступ к этим параметрам только надстройке, которая их создала, эти параметры не должны считаться безопасным хранилищем. К ней могут обращаться другие службы, например Microsoft Graph. Они не должны использоваться для хранения конфиденциальной информации, такой как учетные данные пользователя или маркеры безопасности.
Данные в объекте 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.onReady . В следующем примере кода JavaScript показано, как загрузить существующие параметры роуминга и получить значения двух параметров: customerName и customerBalance.
let _mailbox;
let _settings;
let _customerName;
let _customerBalance;
Office.onReady((info) => {
if (info.host === Office.HostType.Outlook) {
// 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 Outlook session.
_settings.saveAsync(saveMyAddInSettingsCallback);
}
Попробуйте пример кода в Script Lab
Чтобы узнать, как создать объект RoamingSettings и управлять им, получите Script Lab для надстройки Outlook и опробуйте пример "Использование параметров надстройки". Дополнительные сведения о Script Lab см. в статье Изучение API JavaScript для Office с помощью Script Lab.
Вы также можете указать данные, характерные для элемента в почтовом ящике пользователя, используя объект CustomProperties. Например, ваша почтовая надстройка могла бы категоризировать некоторые сообщения и отмечать категорию с помощью настраиваемого свойства messageCategory. Либо, если ваша почтовая надстройка создает встречи из сообщений с предложениями о собрании, вы можете использовать настраиваемое свойство, чтобы отслеживать каждую из этих встреч. Это гарантирует, что если пользователь снова откроет сообщение, ваша почтовая надстройка не предложит создать встречу во второй раз.
Аналогично параметрам перемещения, изменения настраиваемых свойств хранятся в копии контейнера свойств для текущего сеанса Outlook. Чтобы убедиться, что эти настраиваемые свойства будут доступны в следующем сеансе, используйте CustomProperties.saveAsync.
Доступ к этим настраиваемым свойствам, зависящим от конкретного элемента, можно получить только с помощью CustomProperties объекта . Эти свойства отличаются от пользовательских свойств UserProperties на основе MAPI в объектной модели Outlook и расширенных свойств в веб-службах Exchange (EWS). Вы не можете получить прямой доступ CustomProperties с помощью объектной модели Outlook, EWS или Microsoft Graph. Сведения о том, как получить доступ CustomProperties с помощью Microsoft Graph или EWS, см. в разделе Получение пользовательских свойств с помощью Microsoft Graph или EWS.
Примечание.
Пользовательские свойства доступны только надстройке, создавшей их, и только через почтовый элемент, в котором они были сохранены. По этой причине свойства, заданные в режиме создания, не передаются получателям почтового элемента. При отправке сообщения или встречи с пользовательскими свойствами доступ к его свойствам можно получить из элемента в папке Отправленные . Чтобы разрешить получателям получать пользовательские данные, заданные надстройкой, рассмотрите возможность использования InternetHeaders .
Использование настраиваемых свойств
Перед использованием настраиваемых свойств необходимо загрузить их, вызвав метод loadCustomPropertiesAsync. После создания контейнера свойств можно использовать методы set и get для добавления и извлечения пользовательских свойств. Чтобы сохранить любые изменения, внесенные в контейнер свойств, необходимо использовать метод saveAsync.
Примечание.
При использовании пользовательских свойств в надстройках Outlook имейте в виду следующее:
- Outlook для Mac не кэшируют пользовательские свойства. Если сеть пользователя выйдет из строя, надстройки в Outlook на Mac не смогут получить доступ к своим пользовательским свойствам.
- В классической версии Outlook в Windows пользовательские свойства, сохраненные в режиме создания, сохраняются только после закрытия или вызова
Office.context.mailbox.item.saveAsync создаваемого элемента.
Попробуйте пример кода в Script Lab
Чтобы узнать, как создать объект CustomProperties и управлять им, получите Script Lab надстройки Outlook и опробуйте пример "Работа с пользовательскими свойствами элемента". Дополнительные сведения о Script Lab см. в статье Изучение API JavaScript для Office с помощью Script Lab.
Получение пользовательских свойств с помощью Microsoft Graph или EWS
Чтобы получить CustomProperties с помощью Microsoft Graph или EWS, необходимо сначала определить имя его расширенного свойства на основе MAPI. Затем можно получить это свойство способом, аналогичным используемому при получении любого расширенного свойства, основанного на интерфейсе MAPI.
Использование Microsoft Graph или EWS зависит от того, выполняется ли надстройка в Exchange Online или локальной среде Exchange.
Exchange Online.
В Exchange Online средах надстройка может создать запрос Microsoft Graph к сообщениям и событиям, чтобы получить те, которые уже имеют пользовательские свойства. В запрос следует включить свойство на основе MAPI CustomProperties и его набор свойств, используя сведения, указанные в разделе Хранение пользовательских свойств в элементе.
В следующем примере показано, как получить все события с пользовательскими свойствами, заданными надстройкой. Он также гарантирует, что ответ содержит значение свойства, чтобы можно было применить дальнейшую логику фильтрации.
Важно!
В приведенном ниже примере замените <app-guid> идентификатором своей надстройки.
GET https://graph.microsoft.com/v1.0/me/events?$filter=singleValueExtendedProperties/Any
(ep: ep/id eq 'String {00020329-0000-0000-C000-000000000046}
Name cecp-<app-guid>' and ep/value ne null)
&$expand=singleValueExtendedProperties($filter=id eq 'String
{00020329-0000-0000-C000-000000000046} Name cecp-<app-guid>')
Другие примеры получения расширенных свойств на основе MAPI с одним значением см. в разделе Получение singleValueLegacyExtendedProperty.
Локальная среда Exchange
В локальных средах Exchange почтовая надстройка может получить расширенное 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.
Способ хранения настраиваемых свойств в элементе
Пользовательские свойства, заданные надстройкой, не эквивалентны обычным свойствам на основе MAPI. API-интерфейсы надстроек сериализуют все надстройки CustomProperties в виде полезных данных JSON, а затем сохраняют их в одном расширенном свойстве на основе MAPI, имя которого — cecp-<app-guid> (<app-guid> — идентификатор надстройки), а guid набора свойств — {00020329-0000-0000-C000-000000000046}. (Дополнительные сведения об этом объекте см. в разделе Пользовательские свойства почтового приложения MS-OXCEXT 2.2.5.) Затем можно использовать Microsoft Grpah или EWS, чтобы получить это свойство на основе MAPI.
В следующей таблице описано сохраненное поведение пользовательских свойств в сообщениях для различных клиентов 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).