Office.Mailbox interface 
提供对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 外接程序。 包含以下成员。 
 有关详细信息,请参阅 Office.Diagnostics。 | 
| ews | 获取此电子邮件帐户的 Exchange Web Services (EWS) 终点的 URL。 | 
| item | 邮箱项。 根据打开加载项的上下文,项类型可能会有所不同。 如果只想查看特定类型或模式的 IntelliSense,请将此项转换为以下项之一: MessageCompose、 MessageRead、 AppointmentCompose、 AppointmentRead 重要说明: 
 | 
| user | 有关与邮箱关联的用户的信息。 这包括其帐户类型、显示名称、电子邮件地址和时区。 有关详细信息,请参阅 Office.UserProfile | 
方法
| convert | 获取包含以本地客户端时间表示的时间信息的字典。 Outlook 客户端使用的时区因平台而异。 Windows 上的 Outlook (经典) 和 Mac 上的 Outlook 使用客户端计算机时区。 Outlook 网页版和新的 Windows 版 Outlook 使用 Exchange 管理员 Center (EAC) 上设置的时区。 应对日期和时间值进行处理,以便用户界面上显示的值始终与用户预期的时区一致。 在 Outlook on Windows (经典) 和 Mac 中,  | 
| convert | 
               方法  | 
| display | 显示现有日历约会。 方法  在 Outlook on Mac 中,可以使用此方法显示不属于定期系列的单个约会,或显示定期系列的主约会。 但是,无法显示序列的实例,因为无法访问属性 (包括定期序列实例的项 ID) 。 在 Outlook 网页版 和新的 Outlook on Windows 中,仅当窗体正文小于或等于 32K 个字符时,此方法才会打开指定的窗体。 如果指定的项目标识符未标识现有约会,则会在客户端计算机或设备上打开一个空白窗格,并且不会返回错误消息。 | 
| display | 显示现有邮件。 方法  在 Outlook 网页版 和新的 Outlook on Windows 中,仅当窗体正文小于或等于 32K 个字符时,此方法才会打开指定的窗体。 如果指定的项标识符未标识现有消息,则客户端计算机上不会显示任何消息,并且不会返回错误消息。 | 
| display | 显示用于新建日历约会的表单。 
               在 Outlook 网页版 和新的 Outlook on Windows 中,此方法始终显示包含与会者字段的窗体。 如果未将任何与会者指定为输入参数,该方法将显示带有 “保存 ”按钮的窗体。 如果已指定与会者,窗体将包含与会者和“发送”按钮。 在 Outlook on Windows (经典) 和 Mac 中,如果在 、 如果任何参数超过指定大小限制,或者指定了未知参数名称,则会引发异常。 | 
| get | 获取一个字符串,其中包含用于从 Exchange Server 获取附件或项目的令牌。 
               令牌在 属性中  | 
| get | 如果当前邮箱由 Microsoft Intune 管理,则返回 true。 | 
| get | 如果组织的 Intune 移动应用程序管理 (MAM) 策略 允许加载项从指定位置访问数据,则返回 true。 | 
| get | 如果组织的 Intune 移动应用程序管理 (MAM) 策略 允许外接程序将数据保存到指定位置,则返回 true。 | 
| get | 获取用于标识用户和 Office 外接程序的令牌。 令牌在 属性中  | 
| make | 在托管用户邮箱的 Exchange 服务器上向 Exchange Web Services 发出异步请求 (EWS) 服务。 
               | 
属性详细信息
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;属性值
注解
最低权限级别: 读取项
适用的 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
注解
最低权限级别: 读取项
适用的 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-for-exchange-on-premises/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;属性值
		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 对象。
返回
注解
最低权限级别: 读取项
适用的 Outlook 模式:Compose或读取
示例
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/90-other-item-apis/get-start-read.yaml
const time = Office.context.mailbox.item.start;
const localTime = Office.context.mailbox.convertToLocalClientTime(time);
console.log(`Appointment starts (local): ${localTime.month + 1}/${localTime.date}/${localTime.year}, ${localTime.hours}:${localTime.minutes}:${localTime.seconds}`);
		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
注解
最低权限级别: 读取项
适用的 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 = (document.getElementById("itemId") as HTMLInputElement).value;
Office.context.mailbox.displayAppointmentForm(itemId);
		displayMessageForm(itemId)
	   
	显示现有邮件。
方法 displayMessageForm 在桌面上的新窗口中打开现有消息。
在 Outlook 网页版 和新的 Outlook on Windows 中,仅当窗体正文小于或等于 32K 个字符时,此方法才会打开指定的窗体。
如果指定的项标识符未标识现有消息,则客户端计算机上不会显示任何消息,并且不会返回错误消息。
displayMessageForm(itemId: string): void;参数
- itemId
- 
				string 
现有消息的 Exchange Web 服务 (EWS) 标识符。
返回
void
注解
最低权限级别: 读取项
适用的 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 = (document.getElementById("itemId") as HTMLInputElement).value;
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
注解
最低权限级别: 读取项
重要提示: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-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或读取
重要说明:
- 旧版 Exchange 令牌已弃用。 默认情况下,大多数Exchange Online租户已关闭旧版 Exchange 用户标识和回调令牌。 管理员可以在 2025 年 6 月之前为租户和外接程序重新启用旧令牌。 2025 年 10 月,所有租户的旧令牌将完全关闭。 这是 Microsoft“安全未来计划”的一部分,该计划为组织提供了应对当前威胁环境所需的工具。 Exchange 用户标识令牌仍适用于本地 Exchange。 建议使用嵌套应用身份验证 (NAA) 来使用令牌。 有关详细信息,请参阅 常见问题解答页。 
- 可以将令牌和附件标识符或项标识符传递给外部系统。 该系统使用该令牌作为持有者授权令牌来调用 Exchange Web Services (EWS) GetAttachment 或 GetItem 作以返回附件或项目。 例如,可以创建一个远程服务来 从所选项获取附件。 
- getCallbackTokenAsync在读取模式下调用 方法需要读取项的最低权限级别。
- getCallbackTokenAsync在撰写模式下调用 方法需要保存项目。 方法- saveAsync需要 读/写项的最低权限级别。
- Android 版或 iOS 版 Outlook 不支持此方法。 在移动客户端上的 Outlook 中运行的加载项中不支持 EWS作。 有关 Outlook mobile 中支持的 API 的详细信息,请参阅移动设备上的 Outlook 中支持的 Outlook JavaScript API。 
- 如果在 Outlook.com 或 Gmail 邮箱中加载加载项,则不支持此方法。 
- 有关委托或共享方案的指导,请参阅 共享文件夹和共享邮箱 一文。 
错误:
如果调用失败,请使用 asyncResult.诊断 属性查看有关错误的详细信息。
- GenericTokenError: An internal error has occurred.- 在Exchange Online环境中,由于 Outlook 外接程序的旧 Exchange 令牌已关闭而无法检索令牌时,会发生此错误。 建议将 NAA 用作加载项的单一登录解决方案。 有关如何实现 NAA 的指南,请参阅 常见问题解答页。
- HTTPRequestFailure: The request has failed. Please look at the diagnostics object for the HTTP error code.
- InternalServerError: The Exchange server returned an error. Please look at the diagnostics object for more information.- 在Exchange Online环境中,由于 Outlook 外接程序的旧 Exchange 令牌已关闭而无法检索令牌时,会发生此错误。 建议将 NAA 用作加载项的单一登录解决方案。 有关如何实现 NAA 的指南,请参阅 常见问题解答页。
- NetworkError: The user is no longer connected to the network. Please check your network connection and try again.
		getIsIdentityManaged()
	  
	如果当前邮箱由 Microsoft Intune 管理,则返回 true。
getIsIdentityManaged(): boolean;返回
boolean
如此 如果当前邮箱由 Microsoft Intune 管理。
注解
最低权限级别: 读取项
适用的 Outlook 模式:Compose、读取
重要提示:此方法仅在 Android 版 Outlook 和 iOS 中受支持,从版本开始 4.2443.0.To 了解有关移动设备上 Outlook 支持的 API 的详细信息,请参阅 移动设备上的 Outlook 支持的 Outlook JavaScript API。
错误:
- 
              MAMServiceNotAvailable:客户端无法提取移动应用程序管理 (MAM) 策略。
示例
// Checks if the mailbox is managed by Microsoft Intune.
const isIdentityManaged = Office.context.mailbox.getIsIdentityManaged();
console.log(`Intune-managed mailbox: ${isIdentityManaged}`);
		getIsOpenFromLocationAllowed(openLocation)
	     
	如果组织的 Intune 移动应用程序管理 (MAM) 策略 允许加载项从指定位置访问数据,则返回 true。
getIsOpenFromLocationAllowed(openLocation: MailboxEnums.OpenLocation): boolean;参数
- openLocation
- Office.MailboxEnums.OpenLocation
外接程序尝试从其访问数据的位置。
返回
boolean
如果组织的 Intune MAM 策略允许加载项访问指定位置的数据,则其值为 True。
注解
最低权限级别: 读取项
适用的 Outlook 模式:Compose、读取
重要提示:从版本 4.2443.0 开始,此方法仅在 Android 版 Outlook 和 iOS 中受支持。 若要详细了解移动设备上的 Outlook 支持的 API,请参阅移动设备上的 Outlook 支持的 Outlook JavaScript API。
错误:
- InvalidOpenLocationInput:指定位置的值无效。
- MAMServiceNotAvailable:客户端无法提取 MAM 策略。
示例
// Checks if the add-in can access data from the device's photo library.
const isOpenFromPhotoLibraryAllowed = Office.context.mailbox.getIsOpenFromLocationAllowed(Office.MailboxEnums.OpenLocation.PhotoLibrary);
if (isOpenFromPhotoLibraryAllowed) {
    console.log("Access to the photo library is allowed.");
    // Do something.
} else {
    console.log("Access to the photo library isn't allowed.");
}
		getIsSaveToLocationAllowed(saveLocation)
	    
	如果组织的 Intune 移动应用程序管理 (MAM) 策略 允许外接程序将数据保存到指定位置,则返回 true。
getIsSaveToLocationAllowed(saveLocation: MailboxEnums.SaveLocation): boolean;参数
- saveLocation
- Office.MailboxEnums.SaveLocation
外接程序尝试保存数据的位置。
返回
boolean
如此 如果组织的 Intune MAM 策略允许外接程序将数据保存到指定位置。
注解
最低权限级别: 读取项
适用的 Outlook 模式:Compose、读取
重要提示:从版本 4.2443.0 开始,此方法仅在 Android 版 Outlook 和 iOS 中受支持。 若要详细了解移动设备上的 Outlook 支持的 API,请参阅移动设备上的 Outlook 支持的 Outlook JavaScript API。
错误:
- InvalidSaveLocationInput:指定位置的值无效。
- MAMServiceNotAvailable:客户端无法提取 MAM 策略。
示例
// Checks if the add-in can save data to SharePoint.
const isSaveToSharePointAllowed = Office.context.mailbox.getIsSaveToLocationAllowed(Office.MailboxEnums.SaveLocation.SharePoint);
if (isSaveToSharePointAllowed) {
    console.log("Saving to SharePoint is allowed.");
    // Do something.
} else {
    console.log("Saving to SharePoint isn't allowed.");
}
		getUserIdentityTokenAsync(callback, userContext)
	     
	获取用于标识用户和 Office 外接程序的令牌。
令牌在 属性中 asyncResult.value 以字符串的形式返回。
getUserIdentityTokenAsync(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
注解
最低权限级别: 读取项
适用的 Outlook 模式:Compose或读取
重要说明:
- 旧版 Exchange 令牌已弃用。 默认情况下,大多数Exchange Online租户已关闭旧版 Exchange 用户标识和回调令牌。 管理员可以在 2025 年 6 月之前为租户和外接程序重新启用旧令牌。 2025 年 10 月,所有租户的旧令牌将完全关闭。 这是 Microsoft“安全未来计划”的一部分,该计划为组织提供了应对当前威胁环境所需的工具。 Exchange 用户标识令牌仍适用于本地 Exchange。 建议使用嵌套应用身份验证 (NAA) 来使用令牌。 有关详细信息,请参阅 常见问题解答页。 
- 方法 - getUserIdentityTokenAsync返回一个令牌,可用于使用外部系统标识加载项和用户并对其进行身份验证。
- 如果在 Outlook.com 或 Gmail 邮箱中加载加载项,则不支持此方法。 
错误:
如果调用失败,请使用 asyncResult.诊断 属性查看有关错误的详细信息。
- GenericTokenError: An internal error has occurred.- 在Exchange Online环境中,由于 Outlook 外接程序的旧 Exchange 令牌已关闭而无法检索令牌时,会发生此错误。 建议将 NAA 用作加载项的单一登录解决方案。 有关如何实现 NAA 的指南,请参阅 常见问题解答页。
- HTTPRequestFailure: The request has failed. Please look at the diagnostics object for the HTTP error code.
- InternalServerError: The Exchange server returned an error. Please look at the diagnostics object for more information.- 在Exchange Online环境中,由于 Outlook 外接程序的旧 Exchange 令牌已关闭而无法检索令牌时,会发生此错误。 建议将 NAA 用作加载项的单一登录解决方案。 有关如何实现 NAA 的指南,请参阅 常见问题解答页。
- NetworkError: The user is no longer connected to the network. Please check your network connection and try again.
示例
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-for-exchange-on-premises/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
注解
最低权限级别: 读/写邮箱
适用的 Outlook 模式:Compose或读取
重要说明:
- 旧版 Exchange 令牌已弃用。 默认情况下,大多数Exchange Online租户已关闭旧版 Exchange 用户标识和回调令牌。 管理员可以在 2025 年 6 月之前为租户和外接程序重新启用旧令牌。 2025 年 10 月,所有租户的旧令牌将完全关闭。 这是 Microsoft“安全未来计划”的一部分,该计划为组织提供了应对当前威胁环境所需的工具。 Exchange 用户标识令牌仍适用于本地 Exchange。 建议使用嵌套应用身份验证 (NAA) 来使用令牌。 有关详细信息,请参阅 常见问题解答页。 
- 若要使 方法能够 - makeEwsRequestAsync发出 EWS 请求,服务器管理员必须在客户端访问服务器 EWS 目录上设置为- OAuthAuthentication- true。
- 外接程序必须具有 读/写邮箱 权限才能使用 - 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属性。
示例
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/85-tokens-for-exchange-on-premises/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);
});