Office.Mailbox interface

Ссылка

Пакет:: outlook

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

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

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

Office.onReady(() => {
    document.addEventListener('DOMContentLoaded', () => {
        // Get a reference to the mailbox and use it to add an event handler.
        const mailbox = Office.context.mailbox;
        mailbox.addHandlerAsync(Office.EventType.ItemChanged, loadNewItem, (result) => {
            if (result.status === Office.AsyncResultStatus.Failed) {
                // Handle error.
            }
        });
    });
});

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

    // Check that item isn't null.
    if (item !== null) {
        // Work with item. For example, define and call a function that
        // loads the properties of the newly selected item.
        loadProps(item);
    }
}

Свойства

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

Методы

addHandlerAsync(eventType, handler, options, callback)	Добавляет обработчик для поддерживаемого события. Примечание. События доступны только в реализации области задач. Поддерживаемые события см. в разделе События объектной модели почтовых ящиков.
addHandlerAsync(eventType, handler, callback)	Добавляет обработчик для поддерживаемого события. Примечание. События доступны только в реализации области задач. Поддерживаемые события см. в разделе События объектной модели почтовых ящиков.
convertToEwsId(id, restVersion)	Преобразует поддерживаемый идентификатор в формат веб-служб Exchange (EWS).
convertToLocalClientTime(timeValue)	Получает словарь, содержащий сведения о локальном времени клиента. Часовой пояс, используемый клиентом Outlook, зависит от платформы. Outlook в Windows (классической версии) и на Mac использует часовой пояс клиентского компьютера. Outlook в Интернете и новый Outlook в Windows используют часовой пояс, заданный в Центре Администратор Exchange (EAC). Значения даты и времени должны обрабатываться таким образом, чтобы значения, отображаемые в интерфейсе пользователя, всегда согласовывались с часовым поясом, ожидаемым пользователем. В Outlook для Windows (классическая версия) и на Mac метод возвращает объект словаря со значениями, `convertToLocalClientTime` заданными часовой поясом клиентского компьютера. В Outlook в Интернете и новом Outlook для Windows метод возвращает объект словаря со значениями часового пояса, `convertToLocalClientTime` указанного в EAC.
convertToRestId(id, restVersion)	Преобразует поддерживаемый идентификатор в формат REST.
convertToUtcClientTime(input)	`Date` Получает объект из словаря, содержащего сведения о времени. Метод `convertToUtcClientTime` преобразует словарь, содержащий локальную дату и время, в `Date` объект с правильными значениями для локальной даты и времени.
displayAppointmentForm(itemId)	Отображает имеющуюся встречу из календаря. Метод `displayAppointmentForm` открывает существующую встречу в календаре в новом окне на рабочем столе. В Outlook для Mac этот метод можно использовать для отображения одной встречи, которая не является частью повторяющегося ряда, или master встречи повторяющегося ряда. Однако вы не можете отобразить экземпляр ряда, так как не удается получить доступ к свойствам (включая идентификатор элемента) экземпляров повторяющегося ряда. В Outlook в Интернете и outlook в Windows этот метод открывает указанную форму только в том случае, если текст формы меньше или равен 32 КБ символов. Если указанный идентификатор элемента не идентифицирует существующую встречу, на клиентском компьютере или устройстве откроется пустая панель, и сообщение об ошибке не возвращается.
displayAppointmentFormAsync(itemId, options, callback)	Отображает имеющуюся встречу из календаря. Метод `displayAppointmentFormAsync` открывает новое окно на компьютере или диалоговое окно на мобильном устройстве, содержащее сведения календаря о существующей встрече. В Outlook для Mac этот метод можно использовать для отображения одной встречи, которая не является частью повторяющегося ряда, или master встречи повторяющегося ряда. Однако вы не можете отобразить экземпляр ряда, так как не удается получить доступ к свойствам (включая идентификатор элемента) экземпляров повторяющегося ряда. В Outlook в Интернете и outlook в Windows этот метод открывает указанную форму только в том случае, если текст формы меньше или равен 32 КБ символов. Если указанный идентификатор элемента не идентифицирует существующую встречу, на клиентском компьютере или устройстве откроется пустая панель, и сообщение об ошибке не возвращается. Примечание. Этот метод не поддерживается в Outlook для iOS или Android.
displayAppointmentFormAsync(itemId, callback)	Отображает имеющуюся встречу из календаря. Метод `displayAppointmentFormAsync` открывает новое окно на компьютере или диалоговое окно на мобильном устройстве, содержащее сведения календаря о существующей встрече. В Outlook для Mac этот метод можно использовать для отображения одной встречи, которая не является частью повторяющегося ряда, или master встречи повторяющегося ряда. Однако вы не можете отобразить экземпляр ряда, так как не удается получить доступ к свойствам (включая идентификатор элемента) экземпляров повторяющегося ряда. В Outlook в Интернете и outlook в Windows этот метод открывает указанную форму только в том случае, если текст формы меньше или равен 32 КБ символов. Если указанный идентификатор элемента не идентифицирует существующую встречу, на клиентском компьютере или устройстве откроется пустая панель, и сообщение об ошибке не возвращается. Примечание. Этот метод не поддерживается в Outlook для iOS или Android.
displayMessageForm(itemId)	Отображает имеющееся сообщение. Метод `displayMessageForm` открывает существующее сообщение в новом окне на рабочем столе. В Outlook в Интернете и outlook в Windows этот метод открывает указанную форму только в том случае, если текст формы меньше или равен 32 КБ символов. Если указанный идентификатор элемента не идентифицирует существующее сообщение, сообщение не будет отображаться на клиентском компьютере и сообщение об ошибке не возвращается.
displayMessageFormAsync(itemId, options, callback)	Отображает имеющееся сообщение. Метод `displayMessageFormAsync` открывает новое окно на компьютере или диалоговое окно на мобильном устройстве, содержащее существующее сообщение. В Outlook в Интернете и outlook в Windows этот метод открывает указанную форму только в том случае, если текст формы меньше или равен 32 КБ символов. Если указанный идентификатор элемента не идентифицирует существующее сообщение, сообщение не будет отображаться на клиентском компьютере, и сообщение об ошибке не возвращается. Не используйте `displayMessageForm` метод или `displayMessageFormAsync` с itemId, который представляет встречу. `displayAppointmentForm` Используйте метод или `displayAppointmentFormAsync` для отображения существующей встречи, а `displayNewAppointmentForm` также `displayNewAppointmentFormAsync` для отображения формы для создания новой встречи. Примечание. Этот метод не поддерживается в Outlook для iOS или Android.
displayMessageFormAsync(itemId, callback)	Отображает имеющееся сообщение. Метод `displayMessageFormAsync` открывает новое окно на компьютере или диалоговое окно на мобильном устройстве, содержащее существующее сообщение. В Outlook в Интернете и outlook в Windows этот метод открывает указанную форму только в том случае, если текст формы меньше или равен 32 КБ символов. Если указанный идентификатор элемента не идентифицирует существующее сообщение, сообщение не будет отображаться на клиентском компьютере, и сообщение об ошибке не возвращается. Не используйте `displayMessageForm` метод или `displayMessageFormAsync` с itemId, который представляет встречу. `displayAppointmentForm` Используйте метод или `displayAppointmentFormAsync` для отображения существующей встречи, а `displayNewAppointmentForm` также `displayNewAppointmentFormAsync` для отображения формы для создания новой встречи. Примечание. Этот метод не поддерживается в Outlook для iOS или Android.
displayNewAppointmentForm(parameters)	Отображает форму для создания новой встречи в календаре. Метод `displayNewAppointmentForm` открывает форму, в которой пользователь может создать встречу или собрание. Если параметры заданы, поля формы встречи автоматически заполняются их содержимым. В Outlook в Интернете и новом Outlook в Windows этот метод всегда отображает форму с полем участников. Если вы не укажете участников в качестве входных аргументов, метод отображает форму с кнопкой Сохранить . Если вы укажете участников, форма будет включать участников и кнопку Отправить. Если в Outlook в Windows (классической) и на Mac указать участников или ресурсы в `requiredAttendees`параметре , `optionalAttendees`или `resources` , этот метод отображает форму собрания с кнопкой Отправить . Если не указать получателей, этот метод отобразит форму встречи с кнопкой Сохранить и закрыть. Если параметры превышают указанные ограничения размера или если указано неизвестное имя параметра, вызывается исключение.
displayNewAppointmentFormAsync(parameters, options, callback)	Отображает форму для создания новой встречи в календаре. Метод `displayNewAppointmentFormAsync` открывает форму, в которой пользователь может создать встречу или собрание. Если параметры заданы, поля формы встречи автоматически заполняются их содержимым. В Outlook в Интернете и новом Outlook в Windows этот метод всегда отображает форму с полем участников. Если вы не укажете участников в качестве входных аргументов, метод отображает форму с кнопкой Сохранить. Если вы укажете участников, форма будет включать участников и кнопку Отправить. Если в Outlook в Windows (классической) и на Mac указать участников или ресурсы в `requiredAttendees`параметре , `optionalAttendees`или `resources` , этот метод отображает форму собрания с кнопкой Отправить . Если не указать получателей, этот метод отобразит форму встречи с кнопкой Сохранить и закрыть. Если параметры превышают указанные ограничения размера или если указано неизвестное имя параметра, вызывается исключение. Примечание. Этот метод не поддерживается в Outlook для iOS или Android.
displayNewAppointmentFormAsync(parameters, callback)	Отображает форму для создания новой встречи в календаре. Метод `displayNewAppointmentFormAsync` открывает форму, в которой пользователь может создать встречу или собрание. Если параметры заданы, поля формы встречи автоматически заполняются их содержимым. В Outlook в Интернете и новом Outlook в Windows этот метод всегда отображает форму с полем участников. Если вы не укажете участников в качестве входных аргументов, метод отображает форму с кнопкой Сохранить. Если вы укажете участников, форма будет включать участников и кнопку Отправить. Если в Outlook в Windows (классической) и на Mac указать участников или ресурсы в `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` .
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, newOutlookWindows, OutlookWebApp, OutlookIOSили OutlookAndroid. Примечание. Значение "Outlook" возвращается для Outlook в Windows (классической) и на Mac.
hostVersion(строка): строка, представляющая версию приложения Office или Exchange Server (например, "15.0.468.0"). Если почтовая надстройка работает в Outlook в Windows (классической), на Mac или на мобильных устройствах, hostVersion свойство возвращает версию клиента Outlook. В Outlook в Интернете и новом Outlook в Windows свойство возвращает версию 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

// Get the EWS URL and EWS item ID.
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);

// Convert the EWS item ID to a REST-formatted ID.
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
console.log("REST item ID: " + restId);

// Convert the REST-formatted ID back to an EWS-formatted ID.
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

Важно!

При вызове Office.context.mailbox.item сообщения обратите внимание, что область чтения в клиенте Outlook должна быть включена. Инструкции по настройке области чтения см. в статье Использование и настройка области чтения для предварительного просмотра сообщений.
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: string;

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

string

Конечные точки REST Outlook версии 2.0 и бета-версии теперь устарели. Однако частные надстройки и надстройки, размещенные в AppSource, могут использовать службу REST до окончания расширенной поддержки Outlook 2019 14 октября 2025 г. Трафик из этих надстроек автоматически определяется для исключения. Это исключение также применяется к новым надстройкам, разработанным после 31 марта 2024 г. Хотя надстройки могут использовать службу REST до 2025 года, мы настоятельно рекомендуем перенести надстройки на использование Microsoft Graph. Рекомендации см. в статье Сравнение конечных точек REST API Microsoft Graph и Outlook.
Надстройка должна иметь разрешение на чтение элемента , указанное в манифесте, чтобы вызывать член в режиме restUrl чтения.
В режиме создания необходимо вызвать saveAsync метод , прежде чем использовать restUrl элемент . Для вызова saveAsync метода надстройка должна иметь разрешения на чтение и запись элемента. Однако в сценариях делегирования или общего доступа вместо этого следует использовать targetRestUrl свойство объекта SharedProperties (введено в наборе требований 1.8). Дополнительные сведения см. в статье Общие папки и общий почтовый ящик .

Примеры

// Get the URL of the REST endpoint.
const restUrl = Office.context.mailbox.restUrl;
console.log(`REST API URL: ${restUrl}`);

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.onReady(() => {
    document.addEventListener('DOMContentLoaded', () => {
        // Get a reference to the mailbox and use it to add an event handler.
        const mailbox = Office.context.mailbox;
        mailbox.addHandlerAsync(Office.EventType.ItemChanged, loadNewItem, (result) => {
            if (result.status === Office.AsyncResultStatus.Failed) {
                // Handle error.
            }
        });
    });
});

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

    // Check that item isn't null.
    if (item !== null) {
        // Work with item. For example, define and call a 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

В октябре 2024 г. устаревшие удостоверения пользователя Exchange и маркеры обратного вызова будут отключены по умолчанию для всех клиентов Exchange Online. Это часть инициативы Майкрософт по обеспечению безопасности в будущем, которая предоставляет организациям средства, необходимые для реагирования на текущую среду угроз. Маркеры удостоверений пользователей Exchange по-прежнему будут работать в локальной среде Exchange. Проверка подлинности вложенных приложений — это рекомендуемый подход к токенам в будущем. Дополнительные сведения см. в записи блога и на странице часто задаваемых вопросов.
Этот метод не поддерживается в Outlook для Android или в iOS. Дополнительные сведения о поддерживаемых API в Outlook Mobile см. в статье API JavaScript Для Outlook, поддерживаемые в Outlook на мобильных устройствах.
Идентификаторы элементов, полученные через REST 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

// Get the EWS URL and EWS item ID.
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);

// Convert the EWS item ID to a REST-formatted ID.
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
console.log("REST item ID: " + restId);

// Convert the REST-formatted ID back to an EWS-formatted ID.
const ewsId2 = Office.context.mailbox.convertToEwsId(restId, Office.MailboxEnums.RestVersion.v2_0);
console.log("EWS ID (from REST ID): " + ewsId2);

convertToLocalClientTime(timeValue)

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

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

В Outlook для Windows (классическая версия) и на Mac метод возвращает объект словаря со значениями, convertToLocalClientTime заданными часовой поясом клиентского компьютера. В Outlook в Интернете и новом Outlook для Windows метод возвращает объект словаря со значениями часового пояса, 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 (например , 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/ids-and-urls.yaml

// Get the EWS URL and EWS item ID.
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);

// Convert the EWS item ID to a REST-formatted ID.
const restId = Office.context.mailbox.convertToRestId(ewsId, Office.MailboxEnums.RestVersion.v2_0);
console.log("REST item ID: " + restId);

// Convert the REST-formatted ID back to an EWS-formatted ID.
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 в Интернете и outlook в Windows этот метод открывает указанную форму только в том случае, если текст формы меньше или равен 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 в Windows этот метод всегда отображает форму с полем участников. Если вы не укажете участников в качестве входных аргументов, метод отображает форму с кнопкой Сохранить . Если вы укажете участников, форма будет включать участников и кнопку Отправить.

Если в Outlook в Windows (классической) и на Mac указать участников или ресурсы в 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 в Windows этот метод всегда отображает форму с полем участников. Если вы не укажете участников в качестве входных аргументов, метод отображает форму с кнопкой Сохранить. Если вы укажете участников, форма будет включать участников и кнопку Отправить.

Примечание. Этот метод не поддерживается в 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 в Windows этот метод всегда отображает форму с полем участников. Если вы не укажете участников в качестве входных аргументов, метод отображает форму с кнопкой Сохранить. Если вы укажете участников, форма будет включать участников и кнопку Отправить.

Примечание. Этот метод не поддерживается в 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 : указывает тип вложения. Требуемые значения: file для вложенного файла или item для вложенного элемента.

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

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

attachments.isInline : используется только в том случае, если для типа вложения задано значение 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: "https://i.imgur.com/9S36xvA.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: "https://i.imgur.com/9S36xvA.jpg",
        isInline: true
      }
    ]
  },
  (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. Проверка подлинности вложенных приложений — это рекомендуемый подход к токенам в будущем. Дополнительные сведения см. в записи блога и на странице часто задаваемых вопросов.
Конечные точки REST Outlook версии 2.0 и бета-версии теперь устарели. Однако частные надстройки и надстройки, размещенные в AppSource, могут использовать службу REST до окончания расширенной поддержки Outlook 2019 14 октября 2025 г. Трафик из этих надстроек автоматически определяется для исключения. Это исключение также применяется к новым надстройкам, разработанным после 31 марта 2024 г. Хотя надстройки могут использовать службу REST до 2025 года, мы настоятельно рекомендуем перенести надстройки на использование Microsoft Graph. Рекомендации см. в статье Сравнение конечных точек REST API Microsoft Graph и Outlook.
Этот метод не поддерживается, если вы загружаете надстройку в почтовый ящик Outlook.com или Gmail.
Этот метод поддерживается только в режиме чтения в 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 : пользователь больше не подключен к сети. Проверьте сетевое подключение и повторите попытку.

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 на мобильных устройствах.
Этот метод не поддерживается, если вы загружаете надстройку в почтовый ящик Outlook.com или Gmail.
Инструкции по сценариям делегирования или общего доступа см. в статье Общие папки и общие почтовые ящики .

Ошибки:

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((result) => {
    if (result.status === Office.AsyncResultStatus.Failed) {
        console.error(`Token retrieval failed with message: ${result.error.message}`);
        return;
    }

    console.log(result.value);
});

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 возвращает маркер, который можно использовать для идентификации и проверки подлинности надстройки и пользователя во внешней системе.
Этот метод не поддерживается, если вы загружаете надстройку в почтовый ящик Outlook.com или Gmail.

Ошибки:

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((result) => {
    if (result.status === Office.AsyncResultStatus.Failed) {
        console.error(`Token retrieval failed with message: ${result.error.message}`)
        return;
    }

    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 в Windows (классической) и на Mac возвращается сообщение об ошибке, если размер ответа превышает 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 в Windows. Чтобы определить клиент 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, (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.context.mailbox.removeHandlerAsync(Office.EventType.OfficeThemeChanged, (asyncResult) => {
    if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        console.error("Failed to remove event handler: " + asyncResult.error.message);
        return;
    }

    console.log("Event handler removed successfully.");
});

Поделиться через

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)

Параметры

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

Комментарии

Примеры