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.
userProfile	Сведения о пользователе, связанном с почтовым ящиком. Сюда входят тип учетной записи, отображаемое имя, адрес электронной почты и часовой пояс. Дополнительные сведения см. в разделе Office.UserProfile.

Методы

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 КБ символов. Если указанный идентификатор элемента не идентифицирует существующую встречу, на клиентском компьютере или устройстве откроется пустая панель, и сообщение об ошибке не возвращается.
displayMessageForm(itemId)	Отображает имеющееся сообщение. Метод `displayMessageForm` открывает существующее сообщение в новом окне на рабочем столе. В Outlook в Интернете этот метод открывает указанную форму только в том случае, если текст формы меньше или равен 32 КБ символов. Если указанный идентификатор элемента не идентифицирует существующее сообщение, сообщение не будет отображаться на клиентском компьютере и сообщение об ошибке не возвращается.
displayNewAppointmentForm(parameters)	Отображает форму для создания новой встречи в календаре. Метод `displayNewAppointmentForm` открывает форму, в которой пользователь может создать встречу или собрание. Если параметры заданы, поля формы встречи автоматически заполняются их содержимым. В Outlook в Интернете этот метод всегда отображает форму с полем участников. Если вы не укажете участников в качестве входных аргументов, метод отображает форму с кнопкой Сохранить . Если вы укажете участников, форма будет включать участников и кнопку Отправить. Если в расширенном клиенте Outlook и Outlook RT указать участников или ресурсы в `requiredAttendees`параметре , `optionalAttendees`или `resources` , этот метод отображает форму собрания с кнопкой Отправить . Если не указать получателей, этот метод отобразит форму встречи с кнопкой Сохранить и закрыть. Если параметры превышают указанные ограничения размера или если указано неизвестное имя параметра, вызывается исключение.
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.

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

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

userProfile

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

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

userProfile: UserProfile;

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

Office.UserProfile

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

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

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

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

getCallbackTokenAsync(callback, userContext)

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

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

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

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

Параметры

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

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

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

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

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

Office.Mailbox interface

Комментарии

Свойства

Методы

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

diagnostics

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

Комментарии

Примеры

ewsUrl

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

Комментарии

Примеры

item

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

userProfile

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

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

convertToEwsId(id, restVersion)

Параметры

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

Комментарии

Примеры

convertToLocalClientTime(timeValue)

Параметры

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

Комментарии

convertToRestId(id, restVersion)

Параметры

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

Комментарии

Примеры

convertToUtcClientTime(input)

Параметры

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

Комментарии

Примеры

displayAppointmentForm(itemId)

Параметры

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

Комментарии

Примеры

displayMessageForm(itemId)

Параметры

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

Комментарии

Примеры

displayNewAppointmentForm(parameters)

Параметры

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

Комментарии

Примеры

getCallbackTokenAsync(callback, userContext)

Параметры

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

Комментарии

Примеры

getUserIdentityTokenAsync(callback, userContext)

Параметры

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

Комментарии

Примеры

makeEwsRequestAsync(data, callback, userContext)

Параметры

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

Комментарии

Примеры

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

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