Office.Mailbox interface

Ссылка

Пакет:: outlook

Предоставляет доступ к объектной модели надстройки Microsoft Outlook.

Ключевые свойства:

diagnostics: предоставляет диагностические сведения для надстройки Outlook.
item: предоставляет методы и свойства для доступа к сообщению или встрече в надстройке Outlook.
userProfile: предоставляет сведения о пользователе в надстройке Outlook.

Свойства

diagnostics	Предоставляет надстройке Outlook диагностические сведения. Содержит следующие элементы. `hostName` (string) — строка, представляющая имя приложения Office. Это должно быть одно из следующих значений: `Outlook`, `OutlookWebApp`, `OutlookIOS`или `OutlookAndroid`. Примечание. Значение Outlook возвращается для классических клиентов Outlook (например, Windows и Mac). `hostVersion`(строка): строка, представляющая версию приложения Office или Exchange Server (например, "15.0.468.0"). Если почтовая надстройка запущена в Outlook на настольных или мобильных клиентах, `hostVersion` свойство возвращает версию приложения Outlook. В Outlook в Интернете свойство возвращает версию Exchange Server. `OWAView`(`MailboxEnums.OWAView` или строка): перечисление (или строковый литерал), представляющее текущее представление Outlook в Интернете. Если приложение не Outlook в Интернете, доступ к этому свойству приведет к неопределенному значению. Outlook в Интернете имеет три представления (`OneColumn` - отображаются, когда экран узкий, `TwoColumns` - отображаются, когда экран шире, и `ThreeColumns` - отображаются при ширине экрана), которые соответствуют ширине экрана и окна, а также количеству отображаемых столбцов. Дополнительные сведения см. в разделе Office.Diagnostics.
ewsUrl	Получает URL-адрес конечной точки веб-служб Exchange (EWS) для этой учетной записи электронной почты.
item	Элемент почтового ящика. В зависимости от контекста, в котором была открыта надстройка, тип элемента может отличаться. Если вы хотите видеть IntelliSense только для определенного типа или режима, приведите этот элемент к одному из следующих элементов: MessageCompose, MessageRead, AppointmentCompose, AppointmentRead Важно!`item` может иметь значение NULL, если надстройка поддерживает закрепление области задач. Дополнительные сведения об обработке см. в разделе Реализация закрепляемой области задач в Outlook.
masterCategories	Возвращает объект , предоставляющий методы для управления категориями master списке, связанном с почтовым ящиком.
restUrl	Возвращает URL-адрес конечной точки REST для этой учетной записи электронной почты. Для вызова элемента в режиме чтения приложение должно иметь разрешение на чтение элемента , указанное в манифесте `restUrl` . В режиме создания необходимо вызвать `saveAsync` метод , прежде чем использовать `restUrl` элемент . Для вызова `saveAsync` метода приложение должно иметь разрешения на чтение и запись элементов. Однако в сценариях делегирования или общего доступа вместо этого следует использовать `targetRestUrl` свойство объекта SharedProperties (введено в наборе требований 1.8). Дополнительные сведения см. в статье Общие папки и общий почтовый ящик .
userProfile	Сведения о пользователе, связанном с почтовым ящиком. Сюда входят тип учетной записи, отображаемое имя, адрес электронной почты и часовой пояс. Дополнительные сведения см. в разделе Office.UserProfile.

Методы

addHandlerAsync(eventType, handler, options, callback)	Добавляет обработчик для поддерживаемого события. Примечание. События доступны только в реализации области задач. Поддерживаемые события см. в разделе События объектной модели почтовых ящиков.
addHandlerAsync(eventType, handler, callback)	Добавляет обработчик для поддерживаемого события. Примечание. События доступны только в реализации области задач. Поддерживаемые события см. в разделе События объектной модели почтовых ящиков.
convertToEwsId(id, restVersion)	Преобразует поддерживаемый идентификатор в формат веб-служб Exchange (EWS).
convertToLocalClientTime(timeValue)	Получает словарь, содержащий сведения о локальном времени клиента. Даты и время, используемые почтовым приложением для клиентов Outlook в Интернете или настольных компьютеров, могут использовать разные часовые пояса. Outlook использует часовой пояс клиентского компьютера; Outlook в Интернете использует часовой пояс, заданный в Центре Администратор Exchange (EAC). Значения даты и времени должны обрабатываться таким образом, чтобы значения, отображаемые в интерфейсе пользователя, всегда согласовывались с часовым поясом, ожидаемым пользователем. Если почтовое приложение работает в Outlook на классических клиентах, `convertToLocalClientTime` метод вернет объект словаря со значениями, заданными часовой поясом клиентского компьютера. Если почтовое приложение работает в Outlook в Интернете, метод вернет объект словаря со значениями часового пояса, `convertToLocalClientTime` указанного в EAC.
convertToRestId(id, restVersion)	Преобразует поддерживаемый идентификатор в формат REST.
convertToUtcClientTime(input)	`Date` Получает объект из словаря, содержащего сведения о времени. Метод `convertToUtcClientTime` преобразует словарь, содержащий локальную дату и время, в `Date` объект с правильными значениями для локальной даты и времени.
displayAppointmentForm(itemId)	Отображает имеющуюся встречу из календаря. Метод `displayAppointmentForm` открывает существующую встречу в календаре в новом окне на рабочем столе. В Outlook для Mac этот метод можно использовать для отображения одной встречи, которая не является частью повторяющегося ряда, или master встречи повторяющегося ряда. Однако вы не можете отобразить экземпляр ряда, так как не удается получить доступ к свойствам (включая идентификатор элемента) экземпляров повторяющегося ряда. В Outlook в Интернете этот метод открывает указанную форму только в том случае, если текст формы меньше или равен 32 КБ символов. Если указанный идентификатор элемента не идентифицирует существующую встречу, на клиентском компьютере или устройстве откроется пустая панель, и сообщение об ошибке не возвращается.
displayAppointmentFormAsync(itemId, options, callback)	Отображает имеющуюся встречу из календаря. Метод `displayAppointmentFormAsync` открывает новое окно на компьютере или диалоговое окно на мобильном устройстве, содержащее сведения календаря о существующей встрече. В Outlook для Mac этот метод можно использовать для отображения одной встречи, которая не является частью повторяющегося ряда, или master встречи повторяющегося ряда. Однако вы не можете отобразить экземпляр ряда, так как не удается получить доступ к свойствам (включая идентификатор элемента) экземпляров повторяющегося ряда. В Outlook в Интернете этот метод открывает указанную форму только в том случае, если текст формы меньше или равен 32 КБ символов. Если указанный идентификатор элемента не идентифицирует существующую встречу, на клиентском компьютере или устройстве откроется пустая панель, и сообщение об ошибке не возвращается. Примечание. Этот метод не поддерживается в Outlook для iOS или Android.
displayAppointmentFormAsync(itemId, callback)	Отображает имеющуюся встречу из календаря. Метод `displayAppointmentFormAsync` открывает новое окно на компьютере или диалоговое окно на мобильном устройстве, содержащее сведения календаря о существующей встрече. В Outlook для Mac этот метод можно использовать для отображения одной встречи, которая не является частью повторяющегося ряда, или master встречи повторяющегося ряда. Однако вы не можете отобразить экземпляр ряда, так как не удается получить доступ к свойствам (включая идентификатор элемента) экземпляров повторяющегося ряда. В Outlook в Интернете этот метод открывает указанную форму только в том случае, если текст формы меньше или равен 32 КБ символов. Если указанный идентификатор элемента не идентифицирует существующую встречу, на клиентском компьютере или устройстве откроется пустая панель, и сообщение об ошибке не возвращается. Примечание. Этот метод не поддерживается в Outlook для iOS или Android.
displayMessageForm(itemId)	Отображает имеющееся сообщение. Метод `displayMessageForm` открывает существующее сообщение в новом окне на рабочем столе. В Outlook в Интернете этот метод открывает указанную форму только в том случае, если текст формы меньше или равен 32 КБ символов. Если указанный идентификатор элемента не идентифицирует существующее сообщение, сообщение не будет отображаться на клиентском компьютере и сообщение об ошибке не возвращается.
displayMessageFormAsync(itemId, options, callback)	Отображает имеющееся сообщение. Метод `displayMessageFormAsync` открывает новое окно на компьютере или диалоговое окно на мобильном устройстве, содержащее существующее сообщение. В Outlook в Интернете этот метод открывает указанную форму только в том случае, если текст формы меньше или равен 32 КБ символов. Если указанный идентификатор элемента не идентифицирует существующее сообщение, сообщение не будет отображаться на клиентском компьютере, и сообщение об ошибке не возвращается. Не используйте `displayMessageForm` метод или `displayMessageFormAsync` с itemId, который представляет встречу. `displayAppointmentForm` Используйте метод или `displayAppointmentFormAsync` для отображения существующей встречи, а `displayNewAppointmentForm` также `displayNewAppointmentFormAsync` для отображения формы для создания новой встречи. Примечание. Этот метод не поддерживается в Outlook для iOS или Android.
displayMessageFormAsync(itemId, callback)	Отображает имеющееся сообщение. Метод `displayMessageFormAsync` открывает новое окно на компьютере или диалоговое окно на мобильном устройстве, содержащее существующее сообщение. В Outlook в Интернете этот метод открывает указанную форму только в том случае, если текст формы меньше или равен 32 КБ символов. Если указанный идентификатор элемента не идентифицирует существующее сообщение, сообщение не будет отображаться на клиентском компьютере, и сообщение об ошибке не возвращается. Не используйте `displayMessageForm` метод или `displayMessageFormAsync` с itemId, который представляет встречу. `displayAppointmentForm` Используйте метод или `displayAppointmentFormAsync` для отображения существующей встречи, а `displayNewAppointmentForm` также `displayNewAppointmentFormAsync` для отображения формы для создания новой встречи. Примечание. Этот метод не поддерживается в Outlook для iOS или Android.
displayNewAppointmentForm(parameters)	Отображает форму для создания новой встречи в календаре. Метод `displayNewAppointmentForm` открывает форму, в которой пользователь может создать встречу или собрание. Если параметры заданы, поля формы встречи автоматически заполняются их содержимым. В Outlook в Интернете этот метод всегда отображает форму с полем участников. Если вы не укажете участников в качестве входных аргументов, метод отображает форму с кнопкой Сохранить . Если вы укажете участников, форма будет включать участников и кнопку Отправить. Если в расширенном клиенте Outlook и Outlook RT указать участников или ресурсы в `requiredAttendees`параметре , `optionalAttendees`или `resources` , этот метод отображает форму собрания с кнопкой Отправить . Если не указать получателей, этот метод отобразит форму встречи с кнопкой Сохранить и закрыть. Если параметры превышают указанные ограничения размера или если указано неизвестное имя параметра, вызывается исключение.
displayNewAppointmentFormAsync(parameters, options, callback)	Отображает форму для создания новой встречи в календаре. Метод `displayNewAppointmentFormAsync` открывает форму, в которой пользователь может создать встречу или собрание. Если параметры заданы, поля формы встречи автоматически заполняются их содержимым. В Outlook в Интернете этот метод всегда отображает форму с полем участников. Если вы не укажете участников в качестве входных аргументов, метод отображает форму с кнопкой Сохранить. Если вы укажете участников, форма будет включать участников и кнопку Отправить. Если в расширенном клиенте Outlook и Outlook RT указать участников или ресурсы в `requiredAttendees`параметре , `optionalAttendees`или `resources` , этот метод отображает форму собрания с кнопкой Отправить . Если не указать получателей, этот метод отобразит форму встречи с кнопкой Сохранить и закрыть. Если параметры превышают указанные ограничения размера или если указано неизвестное имя параметра, вызывается исключение. Примечание. Этот метод не поддерживается в Outlook для iOS или Android.
displayNewAppointmentFormAsync(parameters, callback)	Отображает форму для создания новой встречи в календаре. Метод `displayNewAppointmentFormAsync` открывает форму, в которой пользователь может создать встречу или собрание. Если параметры заданы, поля формы встречи автоматически заполняются их содержимым. В Outlook в Интернете этот метод всегда отображает форму с полем участников. Если вы не укажете участников в качестве входных аргументов, метод отображает форму с кнопкой Сохранить. Если вы укажете участников, форма будет включать участников и кнопку Отправить. Если в расширенном клиенте Outlook и Outlook RT указать участников или ресурсы в `requiredAttendees`параметре , `optionalAttendees`или `resources` , этот метод отображает форму собрания с кнопкой Отправить . Если не указать получателей, этот метод отобразит форму встречи с кнопкой Сохранить и закрыть. Если параметры превышают указанные ограничения размера или если указано неизвестное имя параметра, вызывается исключение. Примечание. Этот метод не поддерживается в Outlook для iOS или Android.
displayNewMessageForm(parameters)	Отображает форму для создания нового сообщения. Метод `displayNewMessageForm` открывает форму, которая позволяет пользователю создать новое сообщение. Если указаны параметры, поля формы сообщения автоматически заполняются содержимым параметров. Если параметры превышают указанные ограничения размера или если указано неизвестное имя параметра, вызывается исключение.
displayNewMessageFormAsync(parameters, options, callback)	Отображает форму для создания нового сообщения. Метод `displayNewMessageFormAsync` открывает форму, которая позволяет пользователю создать новое сообщение. Если указаны параметры, поля формы сообщения автоматически заполняются содержимым параметров. Если параметры превышают указанные ограничения размера или если указано неизвестное имя параметра, вызывается исключение.
displayNewMessageFormAsync(parameters, callback)	Отображает форму для создания нового сообщения. Метод `displayNewMessageFormAsync` открывает форму, которая позволяет пользователю создать новое сообщение. Если указаны параметры, поля формы сообщения автоматически заполняются содержимым параметров. Если параметры превышают указанные ограничения размера или если указано неизвестное имя параметра, вызывается исключение.
getCallbackTokenAsync(options, callback)	Возвращает строку, содержащую маркер, используемый для вызова REST API или веб-служб Exchange (EWS). Метод `getCallbackTokenAsync` совершает асинхронный вызов, чтобы получить непрозрачный токен с сервера Exchange Server, на котором размещен почтовый ящик пользователя. Время существования маркера обратного вызова составляет 5 минут. Маркер возвращается в виде строки в свойстве `asyncResult.value` .
getCallbackTokenAsync(callback, userContext)	Получает строку, содержащую маркер, используемый для получения вложения или элемента с Exchange Server. Метод `getCallbackTokenAsync` совершает асинхронный вызов, чтобы получить непрозрачный токен с сервера Exchange Server, на котором размещен почтовый ящик пользователя. Время существования маркера обратного вызова составляет 5 минут. Маркер возвращается в виде строки в свойстве `asyncResult.value` .
getSelectedItemsAsync(options, callback)	Возвращает выбранные сообщения, для которых надстройка может активировать и выполнять операции. Надстройка может активироваться не более чем для 100 сообщений одновременно. Дополнительные сведения о множественном выборе элементов см. в статье Активация надстройки Outlook для нескольких сообщений.
getSelectedItemsAsync(callback)	Возвращает выбранные сообщения, для которых надстройка может активировать и выполнять операции. Надстройка может активироваться не более чем для 100 сообщений одновременно. Дополнительные сведения о множественном выборе элементов см. в статье Активация надстройки Outlook для нескольких сообщений.
getUserIdentityTokenAsync(callback, userContext)	Получает маркер, идентифицирующий пользователя и надстройку Office. Маркер возвращается в виде строки в свойстве `asyncResult.value` .
makeEwsRequestAsync(data, callback, userContext)	Выполняет асинхронный запрос к службе веб-служб Exchange (EWS) на сервере Exchange Server, на котором размещен почтовый ящик пользователя. Метод `makeEwsRequestAsync` отправляет запрос EWS от имени надстройки в Exchange.
removeHandlerAsync(eventType, options, callback)	Удаляет обработчиков для поддерживаемого типа события. Примечание. События доступны только в реализации области задач. Поддерживаемые события см. в разделе События объектной модели почтовых ящиков.
removeHandlerAsync(eventType, callback)	Удаляет обработчиков для поддерживаемого типа события. Примечание. События доступны только в реализации области задач. Поддерживаемые события см. в разделе События объектной модели почтовых ящиков.

Сведения о свойстве

diagnostics

Предоставляет надстройке Outlook диагностические сведения.

Содержит следующие элементы.

hostName (string) — строка, представляющая имя приложения Office. Это должно быть одно из следующих значений: Outlook, OutlookWebApp, OutlookIOSили OutlookAndroid. Примечание. Значение Outlook возвращается для классических клиентов Outlook (например, Windows и Mac).
hostVersion(строка): строка, представляющая версию приложения Office или Exchange Server (например, "15.0.468.0"). Если почтовая надстройка запущена в Outlook на настольных или мобильных клиентах, hostVersion свойство возвращает версию приложения Outlook. В Outlook в Интернете свойство возвращает версию Exchange Server.
OWAView(MailboxEnums.OWAView или строка): перечисление (или строковый литерал), представляющее текущее представление Outlook в Интернете. Если приложение не Outlook в Интернете, доступ к этому свойству приведет к неопределенному значению. Outlook в Интернете имеет три представления (OneColumn - отображаются, когда экран узкий, TwoColumns - отображаются, когда экран шире, и ThreeColumns - отображаются при ширине экрана), которые соответствуют ширине экрана и окна, а также количеству отображаемых столбцов.

Дополнительные сведения см. в разделе Office.Diagnostics.

diagnostics: Diagnostics;

Значение свойства

Office.Diagnostics

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/get-diagnostic-information.yaml

// This function gets a mailbox's diagnostic information, such as Outlook client and version, and logs it to the console.
const diagnostics = Office.context.mailbox.diagnostics;
console.log(`Client application: ${diagnostics.hostName}`);
console.log(`Client version: ${diagnostics.hostVersion}`);

switch (diagnostics.OWAView) {
  case undefined:
    console.log("Current view (Outlook on the web only): Not applicable. An Outlook desktop client is in use.");
    break;
  case Office.MailboxEnums.OWAView.OneColumnNarrow:
    console.log("Current view (Outlook on the web only): Viewed from an older generation mobile phone");
    break;
  case Office.MailboxEnums.OWAView.OneColumn:
    console.log("Current view (Outlook on the web only): Viewed from a newer generation mobile phone");
    break;
  case Office.MailboxEnums.OWAView.TwoColumns:
    console.log("Current view (Outlook on the web only): Viewed from a tablet");
    break;
  case Office.MailboxEnums.OWAView.ThreeColumns:
    console.log("Current view (Outlook on the web only): Viewed from a desktop computer");
    break;
}

ewsUrl

Получает URL-адрес конечной точки веб-служб Exchange (EWS) для этой учетной записи электронной почты.

ewsUrl: string;

Значение свойства

string

Для вызова элемента в режиме чтения приложение должно иметь разрешение на чтение элемента , указанное в манифесте ewsUrl .
В режиме создания необходимо вызвать saveAsync метод , прежде чем использовать ewsUrl элемент . Для вызова saveAsync метода приложение должно иметь разрешения на чтение и запись элементов.
Это свойство не поддерживается в Outlook для Android или iOS. Дополнительные сведения о поддерживаемых API в Outlook Mobile см. в статье API JavaScript Для Outlook, поддерживаемые в Outlook на мобильных устройствах.
Удаленная служба может использовать значение ewsUrl, чтобы выполнять вызовы EWS для почтового ящика пользователя. Например, можно создать удаленную службу для получения вложений из выбранного элемента.

Примеры

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

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

console.log("REST URL: " + Office.context.mailbox.restUrl);
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
console.log("REST item ID: " + restId);

const ewsId2 = Office.context.mailbox.convertToEwsId(restId, Office.MailboxEnums.RestVersion.v2_0);
console.log("EWS ID (from REST ID): " + ewsId2);

item

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

MessageCompose, MessageRead, AppointmentCompose, AppointmentRead

Важно!item может иметь значение NULL, если надстройка поддерживает закрепление области задач. Дополнительные сведения об обработке см. в разделе Реализация закрепляемой области задач в Outlook.

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

Значение свойства

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

masterCategories

Возвращает объект , предоставляющий методы для управления категориями master списке, связанном с почтовым ящиком.

masterCategories: MasterCategories;

Значение свойства

Office.MasterCategories

Примеры

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

Возвращает URL-адрес конечной точки REST для этой учетной записи электронной почты.

Для вызова элемента в режиме чтения приложение должно иметь разрешение на чтение элемента , указанное в манифесте restUrl .

В режиме создания необходимо вызвать saveAsync метод , прежде чем использовать restUrl элемент . Для вызова saveAsync метода приложение должно иметь разрешения на чтение и запись элементов.

Однако в сценариях делегирования или общего доступа вместо этого следует использовать targetRestUrl свойство объекта SharedProperties (введено в наборе требований 1.8). Дополнительные сведения см. в статье Общие папки и общий почтовый ящик .

restUrl: string;

Значение свойства

string

Примеры

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

Office.context.mailbox.getCallbackTokenAsync({ isRest: true }, function (result) {
    const ewsId = Office.context.mailbox.item.itemId;
    const token = result.value;
    const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
    const getMessageUrl = Office.context.mailbox.restUrl + '/v2.0/me/messages/' + restId;
            
    const xhr = new XMLHttpRequest();
    xhr.open('GET', getMessageUrl);
    xhr.setRequestHeader("Authorization", "Bearer " + token);
    xhr.onload = function (e) {
        console.log(this.response);
    }
    xhr.send();
});

...

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

console.log("REST URL: " + Office.context.mailbox.restUrl);
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
console.log("REST item ID: " + restId);

const ewsId2 = Office.context.mailbox.convertToEwsId(restId, Office.MailboxEnums.RestVersion.v2_0);
console.log("EWS ID (from REST ID): " + ewsId2);

userProfile

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

Дополнительные сведения см. в разделе Office.UserProfile.

userProfile: UserProfile;

Значение свойства

Office.UserProfile

Сведения о методе

addHandlerAsync(eventType, handler, options, callback)

Добавляет обработчик для поддерживаемого события. Примечание. События доступны только в реализации области задач.

Поддерживаемые события см. в разделе События объектной модели почтовых ящиков.

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

Параметры

eventType: Office.EventType | string

Событие, которое должно вызвать обработчик.

handler: any

Функция для обработки события. Функция должна принимать один параметр, представляющий собой объектный литерал. Свойство type параметра будет соответствовать параметру, eventType переданного в addHandlerAsync.

options: Office.AsyncContextOptions

Предоставляет возможность сохранения данных контекста любого типа без изменений для использования в обратном вызове.

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

Необязательный параметр. После завершения метода функция, переданная в callback параметре, вызывается с одним параметром типа Office.AsyncResult.

Возвращаемое значение

void

Примеры

Office.initialize = function (reason) {
    $(document).ready(function () {
        Office.context.mailbox.addHandlerAsync(
            Office.EventType.ItemChanged,
            loadNewItem,
            function (result) {
                if (result.status === Office.AsyncResultStatus.Failed) {
                    // Handle error.
                }
            });
    });
};

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

    // Check that item is not null.
    if (item !== null) {
        // Work with item, e.g., define and call function that
        // loads the properties of the newly selected item.
        loadProps(item);
    }
}

addHandlerAsync(eventType, handler, callback)

Поддерживаемые события см. в разделе События объектной модели почтовых ящиков.

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

Параметры

eventType: Office.EventType | string

Событие, которое должно вызвать обработчик.

handler: any

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

Возвращаемое значение

void

convertToEwsId(id, restVersion)

Преобразует поддерживаемый идентификатор в формат веб-служб Exchange (EWS).

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

Параметры

id: string

Идентификатор для преобразования в формат EWS. Эта строка может быть идентификатором элемента, отформатированным для интерфейсов REST API Outlook, или идентификатором беседы, полученным из Office.context.mailbox.item.conversationId.

restVersion: Office.MailboxEnums.RestVersion | string

Значение, определяющее версию REST API для Outlook, которая используется для извлечения идентификатора элемента.

Возвращаемое значение

string

Этот метод не поддерживается в Outlook для Android или в iOS. Дополнительные сведения о поддерживаемых API в Outlook Mobile см. в статье API JavaScript Для Outlook, поддерживаемые в Outlook на мобильных устройствах.
Идентификаторы элементов, полученные через REST API (например, Outlook Mail API или Microsoft Graph), используют формат, отличный от формата, используемого EWS. Метод convertToEwsId преобразовывает идентификатор в формате REST в формат EWS.

Примеры

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

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

console.log("REST URL: " + Office.context.mailbox.restUrl);
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
console.log("REST item ID: " + restId);

const ewsId2 = Office.context.mailbox.convertToEwsId(restId, Office.MailboxEnums.RestVersion.v2_0);
console.log("EWS ID (from REST ID): " + ewsId2);

convertToLocalClientTime(timeValue)

Получает словарь, содержащий сведения о локальном времени клиента.

Даты и время, используемые почтовым приложением для клиентов Outlook в Интернете или настольных компьютеров, могут использовать разные часовые пояса. Outlook использует часовой пояс клиентского компьютера; Outlook в Интернете использует часовой пояс, заданный в Центре Администратор Exchange (EAC). Значения даты и времени должны обрабатываться таким образом, чтобы значения, отображаемые в интерфейсе пользователя, всегда согласовывались с часовым поясом, ожидаемым пользователем.

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

convertToLocalClientTime(timeValue: Date): LocalClientTime;

Параметры

timeValue: Date

Объект Date.

Возвращаемое значение

Office.LocalClientTime

convertToRestId(id, restVersion)

Преобразует поддерживаемый идентификатор в формат REST.

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

Параметры

id: string

Идентификатор для преобразования в формат REST. Эта строка может быть идентификатором элемента, отформатированным для EWS, который обычно извлекается из Office.context.mailbox.item.itemId, идентификатором беседы, полученным из Office.context.mailbox.item.conversationId, или идентификатором ряда, полученным из Office.context.mailbox.item.seriesId.

restVersion: Office.MailboxEnums.RestVersion | string

Значение , указывающее версию REST API Outlook, используемую с преобразованным идентификатором.

Возвращаемое значение

string

Этот метод не поддерживается в Outlook для Android или в iOS. Дополнительные сведения о поддерживаемых API в Outlook Mobile см. в статье API JavaScript Для Outlook, поддерживаемые в Outlook на мобильных устройствах.
Идентификаторы элементов, полученные через веб-службы Exchange (EWS) или через itemId свойство, используют формат, отличный от формата, используемого REST API (например , OUTLOOK Mail API или Microsoft Graph). Метод convertToRestId преобразовывает идентификатор в формате EWS в формат REST.

Примеры

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

Office.context.mailbox.getCallbackTokenAsync({ isRest: true }, function (result) {
    const ewsId = Office.context.mailbox.item.itemId;
    const token = result.value;
    const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
    const getMessageUrl = Office.context.mailbox.restUrl + '/v2.0/me/messages/' + restId;
            
    const xhr = new XMLHttpRequest();
    xhr.open('GET', getMessageUrl);
    xhr.setRequestHeader("Authorization", "Bearer " + token);
    xhr.onload = function (e) {
        console.log(this.response);
    }
    xhr.send();
});

...

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

console.log("REST URL: " + Office.context.mailbox.restUrl);
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
console.log("REST item ID: " + restId);

const ewsId2 = Office.context.mailbox.convertToEwsId(restId, Office.MailboxEnums.RestVersion.v2_0);
console.log("EWS ID (from REST ID): " + ewsId2);

convertToUtcClientTime(input)

Date Получает объект из словаря, содержащего сведения о времени.

Метод convertToUtcClientTime преобразует словарь, содержащий локальную дату и время, в Date объект с правильными значениями для локальной даты и времени.

convertToUtcClientTime(input: LocalClientTime): Date;

Параметры

input: Office.LocalClientTime

Значение локального времени для преобразования.

Возвращаемое значение

Date

Объект Date со временем в формате UTC.

Примеры

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

Отображает имеющуюся встречу из календаря.

Метод displayAppointmentForm открывает существующую встречу в календаре в новом окне на рабочем столе.

В Outlook для Mac этот метод можно использовать для отображения одной встречи, которая не является частью повторяющегося ряда, или master встречи повторяющегося ряда. Однако вы не можете отобразить экземпляр ряда, так как не удается получить доступ к свойствам (включая идентификатор элемента) экземпляров повторяющегося ряда.

В Outlook в Интернете этот метод открывает указанную форму только в том случае, если текст формы меньше или равен 32 КБ символов.

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

displayAppointmentForm(itemId: string): void;

Параметры

itemId: string

Идентификатор веб-служб Exchange для существующей встречи в календаре.

Возвращаемое значение

void

Важно! Этот метод не поддерживается в Outlook для Android или iOS. Дополнительные сведения о поддерживаемых API в Outlook Mobile см. в статье API JavaScript Для Outlook, поддерживаемые в Outlook на мобильных устройствах.

Примеры

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

Отображает имеющуюся встречу из календаря.

Метод displayAppointmentFormAsync открывает новое окно на компьютере или диалоговое окно на мобильном устройстве, содержащее сведения календаря о существующей встрече.

Примечание. Этот метод не поддерживается в Outlook для iOS или Android.

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

Параметры

itemId: string

Идентификатор веб-служб Exchange для существующей встречи в календаре.

options: Office.AsyncContextOptions

Литерал объекта, содержащий одно или несколько следующих свойств:- asyncContext: разработчики могут предоставить любой объект, к которому они хотят получить доступ в функции обратного вызова.

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

Необязательный параметр. После завершения метода функция, переданная в callback параметре, вызывается с одним параметром Office.AsyncResult , asyncResultкоторый является объектом .

Возвращаемое значение

void

Примеры

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

Отображает имеющуюся встречу из календаря.

Примечание. Этот метод не поддерживается в Outlook для iOS или Android.

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

Параметры

itemId: string

Идентификатор веб-служб Exchange для существующей встречи в календаре.

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

Возвращаемое значение

void

displayMessageForm(itemId)

Отображает имеющееся сообщение.

Метод displayMessageForm открывает существующее сообщение в новом окне на рабочем столе.

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

displayMessageForm(itemId: string): void;

Параметры

itemId: string

Идентификатор веб-служб Exchange для существующего сообщения.

Возвращаемое значение

void

Этот метод не поддерживается в Outlook для Android или в iOS. Дополнительные сведения о поддерживаемых API в Outlook Mobile см. в статье API JavaScript Для Outlook, поддерживаемые в Outlook на мобильных устройствах.
Не используйте displayMessageForm с itemId, который представляет встречу. Используйте метод displayAppointmentForm, чтобы отобразить сведения о существующей встрече, а метод displayNewAppointmentForm— для отображения формы создания встречи.

Примеры

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

Отображает имеющееся сообщение.

Метод displayMessageFormAsync открывает новое окно на компьютере или диалоговое окно на мобильном устройстве, содержащее существующее сообщение.

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

Не используйте displayMessageForm метод или displayMessageFormAsync с itemId, который представляет встречу. displayAppointmentForm Используйте метод или displayAppointmentFormAsync для отображения существующей встречи, а displayNewAppointmentForm также displayNewAppointmentFormAsync для отображения формы для создания новой встречи.

Примечание. Этот метод не поддерживается в Outlook для iOS или Android.

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

Параметры

itemId: string

Идентификатор веб-служб Exchange для существующего сообщения.

options: Office.AsyncContextOptions

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

Возвращаемое значение

void

Примеры

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

Отображает имеющееся сообщение.

Примечание. Этот метод не поддерживается в Outlook для iOS или Android.

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

Параметры

itemId: string

Идентификатор веб-служб Exchange для существующего сообщения.

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

Возвращаемое значение

void

displayNewAppointmentForm(parameters)

Отображает форму для создания новой встречи в календаре.

Метод displayNewAppointmentForm открывает форму, в которой пользователь может создать встречу или собрание. Если параметры заданы, поля формы встречи автоматически заполняются их содержимым.

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

Если в расширенном клиенте Outlook и Outlook RT указать участников или ресурсы в requiredAttendeesпараметре , optionalAttendeesили resources , этот метод отображает форму собрания с кнопкой Отправить . Если не указать получателей, этот метод отобразит форму встречи с кнопкой Сохранить и закрыть.

Если параметры превышают указанные ограничения размера или если указано неизвестное имя параметра, вызывается исключение.

displayNewAppointmentForm(parameters: AppointmentForm): void;

Параметры

parameters: Office.AppointmentForm

Объект AppointmentForm , описывающий новое назначение. Все свойства являются необязательными.

Возвращаемое значение

void

Примеры

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

Отображает форму для создания новой встречи в календаре.

Метод displayNewAppointmentFormAsync открывает форму, в которой пользователь может создать встречу или собрание. Если параметры заданы, поля формы встречи автоматически заполняются их содержимым.

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

Примечание. Этот метод не поддерживается в Outlook для iOS или Android.

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

Параметры

parameters: Office.AppointmentForm

Объект AppointmentForm , описывающий новое назначение. Все свойства являются необязательными.

options: Office.AsyncContextOptions

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

Возвращаемое значение

void

Примеры

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

Отображает форму для создания новой встречи в календаре.

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

Примечание. Этот метод не поддерживается в Outlook для iOS или Android.

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

Параметры

parameters: Office.AppointmentForm

Объект AppointmentForm , описывающий новое назначение. Все свойства являются необязательными.

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

Возвращаемое значение

void

displayNewMessageForm(parameters)

Отображает форму для создания нового сообщения.

Метод displayNewMessageForm открывает форму, которая позволяет пользователю создать новое сообщение. Если указаны параметры, поля формы сообщения автоматически заполняются содержимым параметров.

displayNewMessageForm(parameters: any): void;

Параметры

parameters: any

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

toRecipients: массив строк, содержащий адреса электронной почты, или массив, содержащий объект EmailAddressDetails для каждого из получателей в строке Кому . Массив может включать не более 100 записей.

ccRecipients: массив строк, содержащий адреса электронной почты, или массив, содержащий объект EmailAddressDetails для каждого из получателей в строке Копия . Массив может включать не более 100 записей.

bccRecipients: массив строк, содержащий адреса электронной почты, или массив, содержащий объект EmailAddressDetails для каждого из получателей в строке ск . Массив может включать не более 100 записей.

subject: строка, содержащая тему сообщения. Максимальное количество символов в строке — 255.

htmlBody: текст сообщения в формате HTML. Максимальный размер содержимого сообщения — 32 КБ.

attachments: массив объектов JSON, которые являются вложенными файлами или элементами.

attachments.type: указывает тип вложения. Должен быть файлом для вложения файла или элементом для вложения элемента.

attachments.name: строка, содержащая имя вложения длиной до 255 символов.

attachments.url: используется только в том случае, если для параметра type задано значение file. Универсальный код ресурса (URI) расположения файла. Важно! Эта ссылка должна быть общедоступной, без необходимости проверки подлинности с помощью Exchange Online серверов. Однако в локальной среде Exchange ссылка может быть доступна в частной сети при условии, что для нее не требуется дополнительная проверка подлинности.

attachments.isInline: используется только в том случае, если для параметра type задано значение file. Если задано значение true, это означает, что вложение будет отображаться в тексте сообщения и не должно отображаться в списке вложений.

attachments.itemId: используется, только если для типа задано значение item. Идентификатор элемента EWS существующего сообщения электронной почты, которое вы хотите вложить в новое сообщение. Это строка длиной до 100 символов.

Возвращаемое значение

void

Примеры

// 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: "http://www.cutestpaw.com/wp-content/uploads/2011/11/Cute-Black-Dogs-s.jpg",
      isInline: true
    }
  ]
});

displayNewMessageFormAsync(parameters, options, callback)

Отображает форму для создания нового сообщения.

Метод displayNewMessageFormAsync открывает форму, которая позволяет пользователю создать новое сообщение. Если указаны параметры, поля формы сообщения автоматически заполняются содержимым параметров.

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

Параметры

parameters: any

subject: строка, содержащая тему сообщения. Максимальное количество символов в строке — 255.

htmlBody: текст сообщения в формате HTML. Максимальный размер содержимого сообщения — 32 КБ.

attachments: массив объектов JSON, которые являются вложенными файлами или элементами.

attachments.name: строка, содержащая имя вложения длиной до 255 символов.

options: Office.AsyncContextOptions

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

Возвращаемое значение

void

Примеры

// 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: "http://www.cutestpaw.com/wp-content/uploads/2011/11/Cute-Black-Dogs-s.jpg",
        isInline: true
      }
    ]
  },
  function(asyncResult) {
    console.log(JSON.stringify(asyncResult));
  }
);

displayNewMessageFormAsync(parameters, callback)

Отображает форму для создания нового сообщения.

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

Параметры

parameters: any

subject: строка, содержащая тему сообщения. Максимальное количество символов в строке — 255.

htmlBody: текст сообщения в формате HTML. Максимальный размер содержимого сообщения — 32 КБ.

attachments: массив объектов JSON, которые являются вложенными файлами или элементами.

attachments.name: строка, содержащая имя вложения длиной до 255 символов.

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

Возвращаемое значение

void

getCallbackTokenAsync(options, callback)

Возвращает строку, содержащую маркер, используемый для вызова REST API или веб-служб Exchange (EWS).

Метод getCallbackTokenAsync совершает асинхронный вызов, чтобы получить непрозрачный токен с сервера Exchange Server, на котором размещен почтовый ящик пользователя. Время существования маркера обратного вызова составляет 5 минут.

Маркер возвращается в виде строки в свойстве asyncResult.value .

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

Параметры

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

Литерал объекта, содержащий одно или несколько следующих свойств:- isRest: определяет, будет ли предоставленный маркер использоваться для REST API Outlook или веб-служб Exchange. Значение по умолчанию — false. asyncContext: любые данные состояния, передаваемые в асинхронный метод.

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

После завершения метода функция, переданная в параметре обратного вызова, вызывается с одним параметром типа Office.AsyncResult. Маркер возвращается в виде строки в свойстве asyncResult.value . При наличии ошибки свойства asyncResult.error и asyncResult.diagnostics могут предоставлять дополнительные сведения.

Возвращаемое значение

void

В октябре 2024 г. устаревшие удостоверения пользователя Exchange и маркеры обратного вызова будут отключены по умолчанию для всех клиентов Exchange Online. Это часть инициативы Майкрософт по обеспечению безопасности в будущем, которая предоставляет организациям средства, необходимые для реагирования на текущую среду угроз. Маркеры удостоверений пользователей Exchange по-прежнему будут работать в локальной среде Exchange. Проверка подлинности вложенных приложений — это рекомендуемый подход к токенам в будущем. Дополнительные сведения см. в записи блога и на странице часто задаваемых вопросов.
Этот метод поддерживается только в режиме чтения в Outlook для Android и iOS. Дополнительные сведения о поддерживаемых API в Outlook Mobile см. в статье API JavaScript Для Outlook, поддерживаемые в Outlook на мобильных устройствах.
Операции EWS не поддерживаются в надстройках, работающих в Outlook для iOS и Android. Маркер REST всегда возвращается в мобильных клиентах Outlook, даже если options.isRest для параметра задано значение false.
getCallbackTokenAsync Для вызова метода в режиме чтения требуется минимальный уровень разрешений для чтения элемента.
getCallbackTokenAsync Вызов метода в режиме создания требует сохранения элемента. Для saveAsync метода требуется минимальный уровень разрешений для чтения и записи элемента.
Инструкции по сценариям делегирования или общего доступа см. в статье Общие папки и общие почтовые ящики .

Маркеры REST

При запросе маркера REST (options.isRest = true) полученный маркер не будет работать для проверки подлинности вызовов EWS. Маркер будет ограничен в область доступом только для чтения к текущему элементу и его вложениям, если надстройка не указала разрешение на чтение и запись почтового ящика в манифесте. Если указано разрешение на чтение и запись почтового ящика , полученный маркер предоставит доступ на чтение и запись для почты, календаря и контактов, включая возможность отправки почты.

С помощью свойства restUrl надстройка должна определить правильный URL-адрес для вызовов REST API.

Этот API работает для следующих областей.

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

Маркеры EWS

При запросе маркера EWS (options.isRest = false) полученный маркер не будет работать для проверки подлинности вызовов REST API. Область действия маркера будет ограничена доступом к текущему элементу.

С помощью свойства ewsUrl надстройка должна определить правильный URL-адрес для вызовов EWS.

Во внешнюю систему можно передать как маркер, так и идентификатор вложения или идентификатор элемента. Эта система использует маркер в качестве маркера авторизации носителя для вызова операции GetAttachment веб-служб Exchange (EWS) или операции GetItem для возврата вложения или элемента. Например, можно создать удаленную службу для получения вложений из выбранного элемента.

Ошибки:

HTTPRequestFailure: сбой запроса. Просмотрите объект диагностики для кода ошибки HTTP.
InternalServerError: сервер Exchange Server вернул ошибку. Для получения дополнительных сведений просмотрите объект диагностики.
NetworkError: пользователь больше не подключен к сети. Проверьте сетевое подключение и повторите попытку.

Примеры

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

Office.context.mailbox.getCallbackTokenAsync({ isRest: true }, function (result) {
    const ewsId = Office.context.mailbox.item.itemId;
    const token = result.value;
    const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
    const getMessageUrl = Office.context.mailbox.restUrl + '/v2.0/me/messages/' + restId;
            
    const xhr = new XMLHttpRequest();
    xhr.open('GET', getMessageUrl);
    xhr.setRequestHeader("Authorization", "Bearer " + token);
    xhr.onload = function (e) {
        console.log(this.response);
    }
    xhr.send();
});

getCallbackTokenAsync(callback, userContext)

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

Маркер возвращается в виде строки в свойстве asyncResult.value .

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

Параметры

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

userContext: any

Необязательный параметр. Данные о состоянии, передаваемые в асинхронный метод.

Возвращаемое значение

void

В октябре 2024 г. устаревшие удостоверения пользователя Exchange и маркеры обратного вызова будут отключены по умолчанию для всех клиентов Exchange Online. Это часть инициативы Майкрософт по обеспечению безопасности в будущем, которая предоставляет организациям средства, необходимые для реагирования на текущую среду угроз. Маркеры удостоверений пользователей Exchange по-прежнему будут работать в локальной среде Exchange. Проверка подлинности вложенных приложений — это рекомендуемый подход к токенам в будущем. Дополнительные сведения см. в записи блога и на странице часто задаваемых вопросов.
Во внешнюю систему можно передать как маркер, так и идентификатор вложения или идентификатор элемента. Эта система использует маркер в качестве маркера авторизации носителя для вызова операции GetAttachment веб-служб Exchange (EWS) или GetItem для возврата вложения или элемента. Например, можно создать удаленную службу для получения вложений из выбранного элемента.
getCallbackTokenAsync Для вызова метода в режиме чтения требуется минимальный уровень разрешений для чтения элемента.
getCallbackTokenAsync Вызов метода в режиме создания требует сохранения элемента. Для saveAsync метода требуется минимальный уровень разрешений для чтения и записи элемента.
Этот метод не поддерживается в Outlook для Android или в iOS. Операции EWS не поддерживаются в надстройках, работающих в мобильных клиентах Outlook. Дополнительные сведения о поддерживаемых API в Outlook Mobile см. в статье API JavaScript Для Outlook, поддерживаемые в Outlook на мобильных устройствах.
Инструкции по сценариям делегирования или общего доступа см. в статье Общие папки и общие почтовые ящики .

Ошибки:

HTTPRequestFailure: сбой запроса. Просмотрите объект диагностики для кода ошибки HTTP.
InternalServerError: сервер Exchange Server вернул ошибку. Для получения дополнительных сведений просмотрите объект диагностики.
NetworkError: пользователь больше не подключен к сети. Проверьте сетевое подключение и повторите попытку.

Примеры

// 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(function (result) {
    if (result.status !== Office.AsyncResultStatus.Succeeded) {
        console.error(`Token retrieval failed with message: ${result.error.message}`);
    } else {
        console.log(result.value);
    }
});

getSelectedItemsAsync(options, callback)

Возвращает выбранные сообщения, для которых надстройка может активировать и выполнять операции. Надстройка может активироваться не более чем для 100 сообщений одновременно. Дополнительные сведения о множественном выборе элементов см. в статье Активация надстройки Outlook для нескольких сообщений.

getSelectedItemsAsync(options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<SelectedItemDetails[]>) => void): void;

Параметры

options: Office.AsyncContextOptions

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

После завершения метода функция, переданная в callback параметре, вызывается с одним параметром Office.AsyncResult , asyncResultкоторый является объектом . Свойства выбранных сообщений, такие как идентификатор элемента и тема, возвращаются в виде массива объектов SelectedItemDetails в свойстве asyncResult.value . Объекты в массиве следуют в том порядке, в котором были выбраны сообщения.

Возвращаемое значение

void

getSelectedItemsAsync(callback)

getSelectedItemsAsync(callback: (asyncResult: Office.AsyncResult<SelectedItemDetails[]>) => void): void;

Параметры

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

Возвращаемое значение

void

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/get-message-properties.yaml

// Retrieves the selected messages' properties and logs them to the console.
Office.context.mailbox.getSelectedItemsAsync((asyncResult) => {
  if (asyncResult.status === Office.AsyncResultStatus.Failed) {
    console.log(asyncResult.error.message);
    return;
  }

  asyncResult.value.forEach((message) => {
    console.log(`Item ID: ${message.itemId}`);
    console.log(`Subject: ${message.subject}`);
    console.log(`Item type: ${message.itemType}`);
    console.log(`Item mode: ${message.itemMode}`);
  });
});

getUserIdentityTokenAsync(callback, userContext)

Получает маркер, идентифицирующий пользователя и надстройку Office.

Маркер возвращается в виде строки в свойстве asyncResult.value .

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

Параметры

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

userContext: any

Необязательный параметр. Данные о состоянии, передаваемые в асинхронный метод.

Возвращаемое значение

void

В октябре 2024 г. устаревшие удостоверения пользователя Exchange и маркеры обратного вызова будут отключены по умолчанию для всех клиентов Exchange Online. Это часть инициативы Майкрософт по обеспечению безопасности в будущем, которая предоставляет организациям средства, необходимые для реагирования на текущую среду угроз. Маркеры удостоверений пользователей Exchange по-прежнему будут работать в локальной среде Exchange. Проверка подлинности вложенных приложений — это рекомендуемый подход к токенам в будущем. Дополнительные сведения см. в записи блога и на странице часто задаваемых вопросов.
Метод getUserIdentityTokenAsync возвращает маркер, который можно использовать для идентификации и проверки подлинности надстройки и пользователя во внешней системе.

Ошибки:

HTTPRequestFailure: сбой запроса. Просмотрите объект диагностики для кода ошибки HTTP.
InternalServerError: сервер Exchange Server вернул ошибку. Для получения дополнительных сведений просмотрите объект диагностики.
NetworkError: пользователь больше не подключен к сети. Проверьте сетевое подключение и повторите попытку.

Примеры

// 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(function (result) {
    if (result.status !== Office.AsyncResultStatus.Succeeded) {
        console.error(`Token retrieval failed with message: ${result.error.message}`);
    } else {
        console.log(result.value);
    }
});

makeEwsRequestAsync(data, callback, userContext)

Выполняет асинхронный запрос к службе веб-служб Exchange (EWS) на сервере Exchange Server, на котором размещен почтовый ящик пользователя.

Метод makeEwsRequestAsync отправляет запрос EWS от имени надстройки в Exchange.

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

Параметры

data: any

Запрос EWS.

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

После завершения метода функция, переданная в callback параметре, вызывается с одним параметром Office.AsyncResult , asyncResultкоторый является объектом . XML-ответ запроса EWS предоставляется в виде строки в свойстве asyncResult.value . В Outlook в Интернете, в Windows (начиная с версии 2303 (сборка 16225.10000)) и в Mac (начиная с версии 16.73 (23042601)), если размер ответа превышает 5 МБ, в свойстве возвращается сообщение об ошибкеasyncResult.error. В более ранних версиях классического клиента Outlook возвращается сообщение об ошибке, если размер ответа превышает 1 МБ.

userContext: any

Необязательный параметр. Данные о состоянии, передаваемые в асинхронный метод.

Возвращаемое значение

void

В октябре 2024 г. устаревшие удостоверения пользователя Exchange и маркеры обратного вызова будут отключены по умолчанию для всех клиентов Exchange Online. Это часть инициативы Майкрософт по обеспечению безопасности в будущем, которая предоставляет организациям средства, необходимые для реагирования на текущую среду угроз. Маркеры удостоверений пользователей Exchange по-прежнему будут работать в локальной среде Exchange. Проверка подлинности вложенных приложений — это рекомендуемый подход к токенам в будущем. Дополнительные сведения см. в записи блога и на странице часто задаваемых вопросов.
Чтобы включить makeEwsRequestAsync метод для выполнения запросов EWS, администратор сервера должен задать значение OAuthAuthenticationtrue в каталоге EWS сервера клиентского доступа .
Для использования метода надстройка должна иметь разрешение на чтение и запись почтового ящикаmakeEwsRequestAsync. Сведения об использовании разрешения на чтение и запись почтового ящика и операциях EWS, которые можно вызвать с помощью makeEwsRequestAsync метода , см . в разделе Указание разрешений для доступа почтовой надстройки к почтовому ящику пользователя.
Если надстройке требуется доступ к элементам, связанным с папкой, или в ее XML-запросе должна быть указана кодировка UTF-8 (\<?xml version="1.0" encoding="utf-8"?\>), она должна использовать Microsoft Graph или REST API для доступа к почтовому ящику пользователя.
Этот метод не поддерживается в Outlook для Android или в iOS. Дополнительные сведения о поддерживаемых API в Outlook Mobile см. в статье API JavaScript Для Outlook, поддерживаемые в Outlook на мобильных устройствах.
Этот метод не поддерживается при загрузке надстройки в почтовый ящик Gmail.
При использовании makeEwsRequestAsync метода в надстройках, работающих в Outlook версий, предшествующих версии 15.0.4535.1004, необходимо задать значение кодировки ISO-8859-1 (<?xml version="1.0" encoding="iso-8859-1"?>). Чтобы определить версию клиента Outlook, используйте mailbox.diagnostics.hostVersion свойство . Вам не нужно задавать значение кодирования, когда надстройка работает в Outlook в Интернете. Чтобы определить клиент Outlook, в котором выполняется надстройка, используйте mailbox.diagnostics.hostName свойство .

Примеры

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, function (result) {
    console.log(result);
});

removeHandlerAsync(eventType, options, callback)

Удаляет обработчиков для поддерживаемого типа события. Примечание. События доступны только в реализации области задач.

Поддерживаемые события см. в разделе События объектной модели почтовых ящиков.

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

Параметры

eventType: Office.EventType | string

Событие, которое должно отменить обработчик.

options: Office.AsyncContextOptions

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

Возвращаемое значение

void

removeHandlerAsync(eventType, callback)

Поддерживаемые события см. в разделе События объектной модели почтовых ящиков.

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

Параметры

eventType: Office.EventType | string

Событие, которое должно отменить обработчик.

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

Возвращаемое значение

void

Office.Mailbox interface

Комментарии

Свойства

Методы

Сведения о свойстве

diagnostics

Значение свойства

Комментарии

Примеры

ewsUrl

Значение свойства

Комментарии

Примеры

item

Значение свойства

masterCategories

Значение свойства

Комментарии

Примеры

restUrl

Значение свойства

Комментарии

Примеры

userProfile

Значение свойства

Сведения о методе

addHandlerAsync(eventType, handler, options, callback)

Параметры

Возвращаемое значение

Комментарии

Примеры

addHandlerAsync(eventType, handler, callback)

Параметры

Возвращаемое значение

Комментарии

convertToEwsId(id, restVersion)

Параметры

Возвращаемое значение

Комментарии

Примеры

convertToLocalClientTime(timeValue)

Параметры

Возвращаемое значение

Комментарии

convertToRestId(id, restVersion)

Параметры

Возвращаемое значение

Комментарии

Примеры

convertToUtcClientTime(input)

Параметры

Возвращаемое значение

Комментарии

Примеры

displayAppointmentForm(itemId)

Параметры

Возвращаемое значение

Комментарии

Примеры

displayAppointmentFormAsync(itemId, options, callback)

Параметры

Возвращаемое значение

Комментарии

Примеры

displayAppointmentFormAsync(itemId, callback)

Параметры

Возвращаемое значение

Комментарии

displayMessageForm(itemId)

Параметры

Возвращаемое значение

Комментарии

Примеры

displayMessageFormAsync(itemId, options, callback)

Параметры

Возвращаемое значение

Комментарии

Примеры

displayMessageFormAsync(itemId, callback)

Параметры