Office.Mailbox interface

参考

包:: outlook

提供对Microsoft Outlook 外接程序对象模型的访问权限。

键属性：

diagnostics ：向 Outlook 加载项提供诊断信息。
item ：提供用于在 Outlook 外接程序中访问邮件或约会的方法和属性。
userProfile ：提供有关 Outlook 外接程序中用户的信息。

注解

最低权限级别：受限

适用的 Outlook 模式：Compose或读取

示例

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` (字符串) ：表示 Office 应用程序名称的字符串。它应为以下值之一：`Outlook`、`newOutlookWindows`、`OutlookWebApp`、 `OutlookIOS`或。`OutlookAndroid` 注意：Windows 上的 Outlook (经典) 和 Mac 上返回“Outlook”值。 `hostVersion` (字符串) ：表示 Office 应用程序或Exchange Server (版本的字符串，例如“15.0.468.0”) 。如果邮件加载项在 Outlook on Windows (经典) 、Mac 或移动设备中运行，则 `hostVersion` 属性将返回 Outlook 客户端的版本。在 Outlook 网页版和新的 Outlook on Windows 中，属性返回Exchange Server的版本。 `OWAView` `MailboxEnums.OWAView` (或字符串) ：表示Outlook 网页版当前视图的枚举 (或字符串文本) 。如果未Outlook 网页版应用程序，则访问此属性会导致未定义。 Outlook 网页版有三种视图，`OneColumn` (在屏幕较窄时显示; `TwoColumns` 当屏幕较宽`ThreeColumns`时显示;当屏幕较宽时显示;当屏幕宽) （对应于屏幕和窗口的宽度）以及可显示的列数时显示。有关详细信息，请参阅 Office.Diagnostics。
ewsUrl	获取此电子邮件帐户的 Exchange Web Services (EWS) 终点的 URL。
item	邮箱项。根据打开加载项的上下文，项类型可能会有所不同。如果只想查看特定类型或模式的 IntelliSense，请将此项转换为以下项之一： MessageCompose、 MessageRead、 AppointmentCompose、 AppointmentRead 重要说明：在邮件上调用 `Office.context.mailbox.item` 时，请注意，必须打开 Outlook 客户端中的阅读窗格。有关如何配置阅读窗格的指南，请参阅使用和配置阅读窗格预览邮件。 `item` 如果加载项支持固定任务窗格，可以为 null。有关如何处理的详细信息，请参阅在 Outlook 中实现可固定的任务窗格。
userProfile	有关与邮箱关联的用户的信息。这包括其帐户类型、显示名称、电子邮件地址和时区。有关详细信息，请参阅 Office.UserProfile

方法

convertToLocalClientTime(timeValue)	获取包含以本地客户端时间表示的时间信息的字典。 Outlook 客户端使用的时区因平台而异。 Windows 上的 Outlook (经典) 和 Mac 上的 Outlook 使用客户端计算机时区。 Outlook 网页版和新的 Windows 版 Outlook 使用 Exchange 管理员 Center (EAC) 上设置的时区。应对日期和时间值进行处理，以便用户界面上显示的值始终与用户预期的时区一致。在 Outlook on Windows (经典) 和 Mac 中， `convertToLocalClientTime` 该方法返回一个字典对象，其值设置为客户端计算机时区。在 Outlook 网页版和新的 Outlook on Windows 中，`convertToLocalClientTime`该方法返回一个字典对象，其值设置为 EAC 中指定的时区。
convertToUtcClientTime(input)	`Date`从包含时间信息的字典中获取对象。方法 `convertToUtcClientTime` 将包含本地日期和时间 `Date` 的字典转换为具有本地日期和时间的正确值的对象。
displayAppointmentForm(itemId)	显示现有日历约会。方法 `displayAppointmentForm` 在桌面上的新窗口中打开现有的日历约会。在 Outlook on Mac 中，可以使用此方法显示不属于定期系列的单个约会，或显示定期系列的主约会。但是，无法显示序列的实例，因为无法访问属性 (包括定期序列实例的项 ID) 。在 Outlook 网页版和新的 Outlook on Windows 中，仅当窗体正文小于或等于 32K 个字符时，此方法才会打开指定的窗体。如果指定的项目标识符未标识现有约会，则会在客户端计算机或设备上打开一个空白窗格，并且不会返回错误消息。
displayMessageForm(itemId)	显示现有邮件。方法 `displayMessageForm` 在桌面上的新窗口中打开现有消息。在 Outlook 网页版和新的 Outlook on Windows 中，仅当窗体正文小于或等于 32K 个字符时，此方法才会打开指定的窗体。如果指定的项标识符未标识现有消息，则客户端计算机上不会显示任何消息，并且不会返回错误消息。
displayNewAppointmentForm(parameters)	显示用于新建日历约会的表单。 `displayNewAppointmentForm` 方法打开可让用户新建约会或会议的窗体。如果指定了参数，将使用参数的内容自动填充约会窗体字段。在 Outlook 网页版和新的 Outlook on Windows 中，此方法始终显示包含与会者字段的窗体。如果未将任何与会者指定为输入参数，该方法将显示带有 “保存 ”按钮的窗体。如果已指定与会者，窗体将包含与会者和“发送”按钮。在 Outlook on Windows (经典) 和 Mac 中，如果在、`optionalAttendees` 或参数中`requiredAttendees`指定了任何与会者或`resources`资源，此方法将显示带有“发送”按钮的会议窗体。如果未指定任何收件人，此方法将显示一个包含“保存并关闭”按钮的约会窗体。如果任何参数超过指定大小限制，或者指定了未知参数名称，则会引发异常。
getCallbackTokenAsync(callback, userContext)	获取一个字符串，其中包含用于从 Exchange Server 获取附件或项目的令牌。 `getCallbackTokenAsync` 方法进行异步调用，从托管用户邮箱的 Exchange Server 获取非跳转令牌。回调令牌的生存期为 5 分钟。令牌在属性中 `asyncResult.value` 以字符串的形式返回。
getUserIdentityTokenAsync(callback, userContext)	获取用于标识用户和 Office 外接程序的令牌。令牌在属性中 `asyncResult.value` 以字符串的形式返回。
makeEwsRequestAsync(data, callback, userContext)	在托管用户邮箱的 Exchange 服务器上向 Exchange Web Services 发出异步请求 (EWS) 服务。 `makeEwsRequestAsync` 方法代表加载项将 EWS 请求发送到 Exchange。

属性详细信息

diagnostics

将诊断信息提供给 Outlook 外接程序。

包含以下成员。

hostName (字符串) ：表示 Office 应用程序名称的字符串。它应为以下值之一：Outlook、newOutlookWindows、OutlookWebApp、 OutlookIOS或。OutlookAndroid 注意：Windows 上的 Outlook (经典) 和 Mac 上返回“Outlook”值。
hostVersion (字符串) ：表示 Office 应用程序或Exchange Server (版本的字符串，例如“15.0.468.0”) 。如果邮件加载项在 Outlook on Windows (经典) 、Mac 或移动设备中运行，则 hostVersion 属性将返回 Outlook 客户端的版本。在 Outlook 网页版和新的 Outlook on Windows 中，属性返回Exchange Server的版本。
OWAView MailboxEnums.OWAView (或字符串) ：表示Outlook 网页版当前视图的枚举 (或字符串文本) 。如果未Outlook 网页版应用程序，则访问此属性会导致未定义。 Outlook 网页版有三种视图，OneColumn (在屏幕较窄时显示; TwoColumns 当屏幕较宽ThreeColumns时显示;当屏幕较宽时显示;当屏幕宽) （对应于屏幕和窗口的宽度）以及可显示的列数时显示。

有关详细信息，请参阅 Office.Diagnostics。

diagnostics: Diagnostics;

属性值

Office.Diagnostics

注解

最低权限级别： 读取项

适用的 Outlook 模式：Compose或读取

从邮箱要求集 1.5 开始，还可以使用 Office.context.诊断属性获取类似信息。

示例

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

获取此电子邮件帐户的 Exchange Web Services (EWS) 终点的 URL。

ewsUrl: string;

属性值

string

注解

[ API set： Mailbox 1.1 ]

最低权限级别： 读取项

适用的 Outlook 模式：Compose或读取

重要说明：

应用必须具有在其清单中指定的 读取项 权限，才能在读取模式下调用 ewsUrl 成员。
在撰写模式下，必须先调用方法， saveAsync 然后才能使用 ewsUrl 成员。你的应用必须具有 读取/写入项 权限才能调用 saveAsync 方法。
Android 版或 iOS 版 Outlook 不支持此属性。有关 Outlook mobile 中支持的 API 的详细信息，请参阅移动设备上的 Outlook 中支持的 Outlook JavaScript API。
远程服务可使用 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

userProfile

有关与邮箱关联的用户的信息。这包括其帐户类型、显示名称、电子邮件地址和时区。

有关详细信息，请参阅 Office.UserProfile

userProfile: UserProfile;

属性值

Office.UserProfile

方法详细信息

convertToLocalClientTime(timeValue)

获取包含以本地客户端时间表示的时间信息的字典。

Outlook 客户端使用的时区因平台而异。 Windows 上的 Outlook (经典) 和 Mac 上的 Outlook 使用客户端计算机时区。 Outlook 网页版和新的 Windows 版 Outlook 使用 Exchange 管理员 Center (EAC) 上设置的时区。应对日期和时间值进行处理，以便用户界面上显示的值始终与用户预期的时区一致。

在 Outlook on Windows (经典) 和 Mac 中， convertToLocalClientTime 该方法返回一个字典对象，其值设置为客户端计算机时区。在 Outlook 网页版和新的 Outlook on Windows 中，convertToLocalClientTime该方法返回一个字典对象，其值设置为 EAC 中指定的时区。

convertToLocalClientTime(timeValue: Date): LocalClientTime;

参数

timeValue: Date

Date 对象。

Office.LocalClientTime

注解

最低权限级别： 读取项

适用的 Outlook 模式：Compose或读取

convertToUtcClientTime(input)

Date从包含时间信息的字典中获取对象。

方法 convertToUtcClientTime 将包含本地日期和时间 Date 的字典转换为具有本地日期和时间的正确值的对象。

convertToUtcClientTime(input: LocalClientTime): Date;

参数

input: Office.LocalClientTime

要转换的本地时间值。

Date

包含以 UTC 表示的时间的 Date 对象。

注解

最低权限级别： 读取项

适用的 Outlook 模式：Compose或读取

示例

// 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 on Mac 中，可以使用此方法显示不属于定期系列的单个约会，或显示定期系列的主约会。但是，无法显示序列的实例，因为无法访问属性 (包括定期序列实例的项 ID) 。

在 Outlook 网页版和新的 Outlook on Windows 中，仅当窗体正文小于或等于 32K 个字符时，此方法才会打开指定的窗体。

如果指定的项目标识符未标识现有约会，则会在客户端计算机或设备上打开一个空白窗格，并且不会返回错误消息。

displayAppointmentForm(itemId: string): void;

参数

itemId: string

现有日历约会的 Exchange Web 服务 (EWS) 标识符。

void

注解

[ API set： Mailbox 1.1 ]

最低权限级别： 读取项

适用的 Outlook 模式：Compose或读取

重要提示：Android 版或 iOS 版 Outlook 不支持此方法。有关 Outlook mobile 中支持的 API 的详细信息，请参阅移动设备上的 Outlook 中支持的 Outlook JavaScript API。

示例

// 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 在桌面上的新窗口中打开现有消息。

在 Outlook 网页版和新的 Outlook on Windows 中，仅当窗体正文小于或等于 32K 个字符时，此方法才会打开指定的窗体。

如果指定的项标识符未标识现有消息，则客户端计算机上不会显示任何消息，并且不会返回错误消息。

displayMessageForm(itemId: string): void;

参数

itemId: string

现有消息的 Exchange Web 服务 (EWS) 标识符。

void

注解

[ API set： Mailbox 1.1 ]

最低权限级别： 读取项

适用的 Outlook 模式：Compose或读取

重要说明：

Android 版或 iOS 版 Outlook 不支持此方法。有关 Outlook mobile 中支持的 API 的详细信息，请参阅移动设备上的 Outlook 中支持的 Outlook JavaScript API。
不要将 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 on Windows 中，此方法始终显示包含与会者字段的窗体。如果未将任何与会者指定为输入参数，该方法将显示带有 “保存 ”按钮的窗体。如果已指定与会者，窗体将包含与会者和“发送”按钮。

在 Outlook on Windows (经典) 和 Mac 中，如果在、optionalAttendees 或参数中requiredAttendees指定了任何与会者或resources资源，此方法将显示带有“发送”按钮的会议窗体。如果未指定任何收件人，此方法将显示一个包含“保存并关闭”按钮的约会窗体。

如果任何参数超过指定大小限制，或者指定了未知参数名称，则会引发异常。

displayNewAppointmentForm(parameters: AppointmentForm): void;

参数

parameters: Office.AppointmentForm

描述 AppointmentForm 新约会的。所有属性都是可选的。

void

注解

[ API set： Mailbox 1.1 ]

最低权限级别： 读取项

适用的 Outlook 模式：读取

示例

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

注解

[ API 集：全部支持读取模式;邮箱 1.3 引入了Compose模式支持 ]

最低权限级别： 读取项

适用的 Outlook 模式：Compose或读取

重要说明：

2024 年 10 月，所有Exchange Online租户的旧版 Exchange 用户标识和回调令牌默认处于关闭状态。这是 Microsoft“安全未来计划”的一部分，该计划为组织提供了应对当前威胁环境所需的工具。 Exchange 用户标识令牌仍适用于本地 Exchange。嵌套应用身份验证是今后令牌的建议方法。有关详细信息，请参阅我们的博客文章和常见问题解答页面。
可以将令牌和附件标识符或项标识符传递给外部系统。该系统使用该令牌作为持有者授权令牌来调用 Exchange Web Services (EWS) GetAttachment 或 GetItem 操作以返回附件或项目。例如，可以创建一个远程服务来从所选项获取附件。
getCallbackTokenAsync在读取模式下调用方法需要读取项的最低权限级别。
getCallbackTokenAsync在撰写模式下调用方法需要保存项目。方法 saveAsync 需要 读/写项的最低权限级别。
Android 版或 iOS 版 Outlook 不支持此方法。在移动客户端上的 Outlook 中运行的加载项中不支持 EWS 操作。有关 Outlook mobile 中支持的 API 的详细信息，请参阅移动设备上的 Outlook 中支持的 Outlook JavaScript API。
如果在 Outlook.com 或 Gmail 邮箱中加载加载项，则不支持此方法。
有关委托或共享方案的指导，请参阅共享文件夹和共享邮箱一文。

错误：

HTTPRequestFailure ：请求失败。请查看诊断对象，了解 HTTP 错误代码。
InternalServerError ：Exchange 服务器返回错误。请查看诊断对象，了解详细信息。
NetworkError ：用户不再连接到网络。请检查网络连接并重试。

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

注解

最低权限级别： 读取项

适用的 Outlook 模式：Compose或读取

重要说明：

2024 年 10 月，所有Exchange Online租户的旧版 Exchange 用户标识和回调令牌默认处于关闭状态。这是 Microsoft“安全未来计划”的一部分，该计划为组织提供了应对当前威胁环境所需的工具。 Exchange 用户标识令牌仍适用于本地 Exchange。嵌套应用身份验证是今后令牌的建议方法。有关详细信息，请参阅我们的博客文章和常见问题解答页面。
方法getUserIdentityTokenAsync返回一个令牌，可用于使用外部系统标识加载项和用户并对其进行身份验证。
如果在 Outlook.com 或 Gmail 邮箱中加载加载项，则不支持此方法。

错误：

HTTPRequestFailure ：请求失败。请查看诊断对象，了解 HTTP 错误代码。
InternalServerError ：Exchange 服务器返回错误。请查看诊断对象，了解详细信息。
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 服务器上向 Exchange Web Services 发出异步请求 (EWS) 服务。

makeEwsRequestAsync 方法代表加载项将 EWS 请求发送到 Exchange。

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

参数

data: any

EWS 请求。

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

方法完成后，使用单个参数 asyncResult（即 Office.AsyncResult 对象）调用在参数中callback传递的函数。 EWS 请求的 XML 响应在属性中 asyncResult.value 以字符串的形式提供。在 Outlook 网页版中，在 Windows (从版本 2303、内部版本 16225.10000) ) 开始的新 (和经典 (，在从版本 16.73 (23042601) ) 开始的 Mac (上，如果响应大小超过 5 MB，则会在属性中asyncResult.error返回错误消息。在早期版本的 Outlook on Windows (经典) 和 Mac 上，如果响应超过 1 MB，则返回错误消息。

userContext: any

可选。传递给异步方法的任何状态数据。

void

注解

[ API set： Mailbox 1.1 ]

最低权限级别： 读/写邮箱

适用的 Outlook 模式：Compose或读取

重要说明：

2024 年 10 月，所有Exchange Online租户的旧版 Exchange 用户标识和回调令牌默认处于关闭状态。这是 Microsoft“安全未来计划”的一部分，该计划为组织提供了应对当前威胁环境所需的工具。 Exchange 用户标识令牌仍适用于本地 Exchange。嵌套应用身份验证是今后令牌的建议方法。有关详细信息，请参阅我们的博客文章和常见问题解答页面。
若要使方法能够 makeEwsRequestAsync 发出 EWS 请求，服务器管理员必须在客户端访问服务器 EWS 目录上设置为 OAuthAuthenticationtrue 。
外接程序必须具有 读/写邮箱 权限才能使用 makeEwsRequestAsync 方法。有关使用 读/写邮箱 权限以及可以使用方法调用 makeEwsRequestAsync 的 EWS 操作的信息，请参阅指定邮件加载项对用户邮箱的访问权限。
如果外接程序需要访问文件夹关联项目或其 XML 请求必须指定 UTF-8 编码 (\<?xml version="1.0" encoding="utf-8"?\>) ，它必须使用 Microsoft Graph 或 REST API 来访问用户的邮箱。
Android 版或 iOS 版 Outlook 不支持此方法。有关 Outlook mobile 中支持的 API 的详细信息，请参阅移动设备上的 Outlook 中支持的 Outlook JavaScript API。
在 Gmail 邮箱中加载加载项时，不支持此方法。
在 makeEwsRequestAsync 版本 15.0.4535.1004 之前的 Outlook 版本中运行的外接程序中使用方法时，必须将编码值设置为 ISO-8859-1 (<?xml version="1.0" encoding="iso-8859-1"?>) 。若要确定 Outlook 客户端的版本，请使用 mailbox.diagnostics.hostVersion 属性。当加载项在 Outlook 网页版或 Windows 上的新 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, (result) => {
    console.log(result);
});

通过

Office.Mailbox interface

注解

示例

属性

方法

属性详细信息

diagnostics

属性值

注解

示例

ewsUrl

属性值

注解

示例

item

属性值

userProfile

属性值

方法详细信息

convertToLocalClientTime(timeValue)

参数

返回

注解

convertToUtcClientTime(input)

参数

返回

注解

示例

displayAppointmentForm(itemId)

参数

返回

注解

示例

displayMessageForm(itemId)

参数

返回

注解

示例

displayNewAppointmentForm(parameters)

参数

返回

注解

示例

getCallbackTokenAsync(callback, userContext)

参数

返回

注解

getUserIdentityTokenAsync(callback, userContext)

参数

返回

注解

示例

makeEwsRequestAsync(data, callback, userContext)

参数

返回

注解

示例

其他资源