Office Add-in Model 为 Outlook Mail Add-in 提供的 JavaScript API 介绍

本文所讨论的 Mailbox API是指在 Mail Add-in 中可调用的 JavaScript API。开发者可以利用这些API 实现 Add-in 和 Outlook 的交互（数据读取与写入）。希望大家通过这个简单的介绍，认识到 Office Add-In Model 为开发者提供了多大程度和邮件打交道的能力，如果碰巧有正准备开发 Mail Add-in 的同学, 不妨快速扫下 API 列表，然后衡量下它们能不能支撑你完成自己的 Scenarios。

开始之前，需要明确几个问题：

本文中提到的Outlook是指: Outlook for Windows, Outlook for Mac, Outlook RT, OWA for Devices (OWA for Android phones, OWA for iPad, OWA for iPhone), 以及 Outlook Web App。其中 "Outlook rich clients" 是指 Outlook for Windows, Outlook for Mac and Outlook RT。其中, Outlook for Mac 仅仅在Outlook 读邮件模式下支持JavaScript API for Office。
Office.js 在 CDN 上 1.0 版本引用地址为https://appsforoffice.microsoft.com/lib/1.0/hosted/Office.js，1.1 版本地址为 https://appsforoffice.microsoft.com/lib/1.1/hosted/Office.js。关于如何引用它们到你的网页中，可参考 https://msdn.microsoft.com/en-us/library/office/dn221992.aspx。

如果需要了解 Mail Add-In 在 Office 平台上的支持情况，可参见 Office Apps 类型及平台支持。

JavaScript API for Outlook (Mailbox API)

本文将从 Object Model 的角度罗列出 Mail Add-in 中可以访问的 Object 以及它所提供的方法和属性。

Object Name

Object 描述

JavaScript调用方式

Office

表示Add-in的一个实例，它是调用其它API相关的object（如Context等）的入口。

Office

Office.js版本：

Introduced in v1.0

Last changed in v1.1

在如下 Outlook 模式中可用：

撰写邮件、读邮件

(Compose or read)

最低权限要求：

N/A

官方文档：

https://msdn.microsoft.com/en-us/library/office/fp142234.aspx

Context

Add-in的运行时环境信息，并提供调用关键Object上 API的入口

Office.context

Office.js版本：

Introduced in v1.0

在如下 Outlook 模式中可用：

撰写邮件、读邮件

(Compose or read)

最低权限要求：

N/A

官方文档：https://msdn.microsoft.com/EN-US/library/office/fp161104.aspx

Mailbox

为office add-in Object Model 提供访问入口

(Provides access to the app for Office object model for Microsoft Outlook 2013 and Microsoft Outlook Web App.)

Office.context.mailbox

Office.js版本：

Introduced in v1.0

在如下 Outlook 模式中可用：

撰写邮件、读邮件

(Compose or read)

最低权限要求：

ReadWriteMailbox, but some members accessible with lesser permissions

官方文档：

https://msdn.microsoft.com/EN-US/library/office/fp142162.aspx

UserProfile

用来获取通过当前邮件使用mailbox add-in的用户的信息，它有如下几个属性：

Property name	Description
displayName	The user name to use for display.
emailAddress	The user's SMTP email address.
timeZone	The user's local time zone

var userProfile =   Office.context.mailbox.userProfile;

var name =   userProfile.displayName;

Office.js版本：

Introduced in v1.0

在如下 Outlook 模式中可用：

撰写邮件、读邮件(Compose or read)

最低权限要求：

ReadItem

官方文档：

https://msdn.microsoft.com/en-us/library/office/fp161126.aspx

Item

获得激活当前add-in的邮件信息条目或约会条目，Office.context.mailbox.item 的返回值取决于当前查看的邮件条目类型。例如，如果当前邮件条目是信息条目，返回值为一个Message Object；如果是一个约会条目，返回值为一个 Appointment Object。

Item object 是一个base Object，其他的“表示特定条目的Object”（如Appointment和Message）都是它的扩展。

Appointment Object表示当前约会条目
Message Object 表示当前邮件信息
MeetingRequest Object 扩展了 Message Object，表示一个会议邀请。（The MeetingRequest object is returned as the item property of the Mailbox object. The MeetingRequest object extends the Message object. Represents a request to attend a meeting.）

注意: 下面介绍的 Office.context.mailbox.item

的子 Object 或方法，有些是与当前邮件类型相关的。例如同样是Office.context.mailbox.item，如果当前邮件条目为约会条目，则它有 requiredAttendees 属性，而邮件信息条目则会有 cc、to 等属性。

Office.context.mailbox.item

Office.js版本：

Introduced in v1.0

Last changed in v1.3

在如下 Outlook 模式中可用：

撰写邮件、读邮件

(Compose or read)

最低权限要求：

ReadItem

官方文档：

https://msdn.microsoft.com/EN-US/library/office/fp142177.aspx

Message Object

https://msdn.microsoft.com/EN-US/library/office/fp161175.aspx

MeetingRequest Object

https://msdn.microsoft.com/EN-US/library/office/fp142237.aspx?f=255&MSPPError=-2147217396

Appointment Object

https://msdn.microsoft.com/EN-US/library/office/fp160964.aspx

AttachmentDetails

当前条目中包含的附件信息

Office.context.mailbox.item.attachments

Office.js版本：

Introduced in v1.0

在如下 Outlook 模式中可用：

读邮件

(Read)

最低权限要求：

ReadItem

官方文档：

https://msdn.microsoft.com/EN-US/library/office/jj984592.aspx

Body

当前信息或约会条目的正文内容

(该类型提供了针对邮件正文的方法，如setSelectedDataAsync)

Office.context.mailbox.item.body

Office.js版本：

Introduced in v1.1

Latest changed in v 1.3

在如下 Outlook 模式中可用：

撰写邮件

最低权限要求：

ReadItem

官方文档：

https://msdn.microsoft.com/EN-US/library/office/dn482486.aspx

Subject

提供用来获取和设置邮件主题的方法

(Provides methods to get and set the subject of a meeting or message)

在撰写邮件（Compose）模式下：

Office.context.mailbox.item.subject 返回邮件会议或邮件信息的Subject对象，它提供了两种方法----- setAsync 和 getAsync。

SetAsync发送通过向 Exchange server 异步发送请求设置邮件会议或邮件信息的主题。设置主题时，会overrides原有的主题，但是原来的“转发”、“Fwd：”、“Re：”将会保留。

getAsync则可用来获得邮件主题。

在读邮件（Read）模式下：

Office.context.mailbox.item.subject 返回邮件会议或者邮件信息的主题（字符串）

撰写邮件模式下：

SetAsync具体使用，请参照官方文档https://msdn.microsoft.com/en-us/library/office/dn482531.aspx。

getAsync官方文档：https://msdn.microsoft.com/en-us/library/office/dn482529.aspx。

读邮件模式下：

Office.context.mailbox.item.subject 返回邮件的主题（字符串）

Office.js版本：

Introduced in v1.1

在如下 Outlook 模式中可用：

撰写邮件、读邮件

(Compose or read)

最低权限要求：

ReadItem

官方文档：

https://msdn.microsoft.com/en-us/library/office/dn482528.aspx

Time

提供用于获取和设置会议起止时间的方法

仅仅适用于邮件会议或约会，即 Appointment才有start或end属性。

在撰写邮件（Compose）模式下：

Office.context.mailbox.item.start（或end）

返回一个Time object，Time 对象提供了方法用来获取或设置会议起（或止）的时间。

Method name

Description

getAsync

Gets the value of a start or end time.

setAsync

Sets the value of a start or end time.

在读邮件（Read）模式下：

Office.context.mailbox.item.start（或end）返回一个JavaScript Date object，表示会议的起（或止）的时间。

Office.context.mailbox.item.start

https://msdn.microsoft.com/en-us/library/office/fp161129.aspx

Office.context.mailbox.item.end

https://msdn.microsoft.com/en-us/library/office/fp142183.aspx

Office.js版本：

Introduced in v1.1

在如下 Outlook 模式中可用：

撰写邮件会议或约会（Compose）、读邮件会议或约会（Read）

最低权限要求：

ReadItem

官方文档：

https://msdn.microsoft.com/en-us/library/office/dn482538.aspx

CustomProperties

为某个特定的邮件条目提供自定义的属性集合

Office.context.mailbox.item.loadCustomPropertiesAsync()

Office.js版本：

Introduces in v1.0

在如下 Outlook 模式中可用：

？？？？

最低权限要求：

ReadItem

官方文档：

https://msdn.microsoft.com/EN-US/library/office/fp142138.aspx

RoamingSettings

用来存储per user，per add-in的custom settings

不同于CustomProperties，RoamingSettings中的值只能被创建该值的用户所访问，并且只能在被创建该值的add-in中访问到。

Setting的key是字符串类型的，value的类型则可以是string、number、boolean、null、object或者array。

RoamingSettings Object是作为Context对象的一部分自动加载的，当add-in被激活后，便可以通过访问 roamingSettings 来获得或设置其中的值。

（The settings created by using the methods of the RoamingSettings object are saved per app and per user. That is, they are available only to the app that created them, and only from the user's mail box in which they are saved.）

The RoamingSettings object is automatically loaded as part of the Context object, and is available by calling the roamingSettings property of that object when the add-in is activated. The developer is responsible for calling the saveAsync method after adding or deleting settings to save the settings in the user's mailbox.

// 从setting中获得值：

_settings = Office.context.roamingSettings;

_customerName = _settings.get("customerName");

// 添加新的key/value pair：

_settings.set("cookie", Date());

_settings.saveAsync(saveMyAppSettingsCallback);

更多的实例，请参考官方文档https://msdn.microsoft.com/en-us/library/office/fp161171.aspx。

Office.js版本：

Introduced in v1.0

在如下 Outlook 模式中可用：

撰写邮件、读邮件(Compose or read)

最低权限要求：

Restricted

官方文档：

https://msdn.microsoft.com/en-us/library/office/jj220079.aspx

Entities

Exchange Server 2013 server在邮件信息或约会中找到的entity集合，包括addresses，contacts，emailAddresses等等。

Entity集合中包含的内容详见下文中另一个表格

getEntities()

Entity 的识别依赖于自然语言的识别，而后者又要基于大量数据做机器学习才能做到，总的来说，entity的识别结果并不完全准确，识别的成功率很大程度上依赖于邮件中包含的特定语境信息。

Office.js版本：

Introduced in v1.0

在如下 Outlook 模式中可用：

读邮件

(Read)

最低权限要求：

ReadItem but some properties accessible with Restricted.

官方文档：

https://msdn.microsoft.com/EN-US/library/office/fp160984.aspx

Location

该Object为会议或约会地点提供了get和set方法

Office.context.mailbox.item.location

Office.js版本：

Introduced in v1.1

在如下 Outlook 模式中可用：

撰写邮件

(Compose)

最低权限要求：

ReadItem

官方文档：

https://msdn.microsoft.com/EN-US/library/office/dn482502.aspx

Recipients

利用该Object可以取得或者设置收件人。

如下Object的列出的各属性值均是Recipients 类型。

Object

Properties

Appointment

Message

var addressesToBeAdded = {

   {

      "displayName":"Graham   Durkin",

       "emailAddress":"gdurkin@contoso.com"

   },

   {

      "displayName" : "Donnie   Weinberg",

      "emailAddress" :   "dweinberg@contoso.com"

   }

}；

Office.context.mailbox.item.cc.addAsync(addressesToBeAdded, callback);

Office.js版本：

Introduced in v1.1

在如下 Outlook 模式中可用：

撰写邮件

(Compose)

最低权限要求：

ReadItem

官方文档：

https://msdn.microsoft.com/en-us/library/office/dn482517.aspx

Diagnostics

提供用于troubleshooting的信息

Office.context.mailbox.diagnostics

Office.js版本：

Introduced in V1.0

在如下 Outlook 模式中可用：

撰写邮件、读邮件

(Compose or read)

最低权限要求：

ReadItem

官方文档：

https://msdn.microsoft.com/EN-US/library/office/jj715287.aspx

Error

异步数据操作出错时的返回信息

(Provides specific information about an error that occurred during an asynchronous data operation.)

asyncResult.error

Office.js版本：

Intro in v1.0

Changed in v1.1

在如下 Outlook 模式中可用：

最低权限要求：N/A

官方文档：

https://msdn.microsoft.com/EN-US/library/office/fp161033.aspx

EmailAddressDetails

邮件地址详细信息

(该 Object 只是几个字段的封装，并不提供API调用)

Recipients.addAsync 方法可接受 EmailAddressDetails 类型的数组

Office.js版本：

Introduced in v1.0

在如下 Outlook 模式中可用：

撰写邮件、读邮件

(Compose or read)

最低权限要求：

ReadItem

官方文档：

https://msdn.microsoft.com/EN-US/library/office/fp161105.aspx

EmailUser

基于Exchange Server 2013 的邮箱服务器上的邮箱账号（Represents an email account on an Exchange Server 2013 server.）

(该类型只是几个字段的封装，并不提供API调用)

Office.js版本：

Introduced in v1.0

在如下 Outlook 模式中可用：

读邮件

（Read）

最低权限要求：

ReadItem

官方文档：

https://msdn.microsoft.com/EN-US/library/office/fp142187.aspx

Entities Object —— Exchange Server 可以根据邮件内容检测出地理位置、邮箱地址、联系人信息、任务分配信息等，我们可以利用 Office.context.mailbox.item.getEntities() 取出来这样一组信息集合，集合中包括如下几种类型的属性：

Object Name

Object 描述

JavaScript调用方式

Contacts

Exchange Server 2013 服务在邮件信息或约会条目中找到的联系人数组。

Office.context.mailbox.item.getEntities().contacts;

Office.js版本：

Introduced in v1.0

在如下 Outlook 模式中可用：

读邮件(Read)

最低权限要求：

Restricted

官方文档：

https://msdn.microsoft.com/EN-US/library/office/fp142242.aspx

MeetingSuggestion

Exchange Server 2013 服务在邮件信息或约会条目中找到的会议提议

(Represents a suggested meeting found in an item.)

Office.context.mailbox.item.getEntities().meetingSuggestions;

Office.context.mailbox.item.getEntitiesByType

(Office.MailboxEnums.EntityType.MeetingSuggestion).meetingSuggestions;

Office.js版本：

Intro in1.0

在如下 Outlook 模式中可用：

读邮件(Read)

最低权限要求：

ReadItem

官方文档：

https://msdn.microsoft.com/EN-US/library/office/fp142141.aspx

PhoneNumber

Exchange Server 2013 服务在邮件信息或约会条目中找到的电话号码

Represents a phone number identified in an item.

Office.context.mailbox.item.getEntities().phoneNumbers;

Office.js版本：

Introduced in v1.0

在如下 Outlook 模式中可用：

读邮件(Read)

最低权限要求：

Restricted

官方文档：

https://msdn.microsoft.com/en-us/library/office/fp142244.aspx

TaskSuggestion

Exchange Server 2013 服务在邮件信息或约会条目中找到的任务分配建议

Office.context.mailbox.item.getEntities().taskSuggestions;

Office.context.mailbox.item.

getEntitiesByType(EntityType.TaskSuggestion).taskSuggestions;

PropertyName

Description

assignees

返回一个EmailUser 类型的数组，每个元素代表检测出的任务建议中的任务执行者。

taskString

返回检测出的任务建议(字符串)

Office.js版本：

Introduced in v1.0

在如下 Outlook 模式中可用：

读邮件(Read)

最低权限要求：

ReadItem

官方文档：

https://msdn.microsoft.com/en-us/library/office/fp160979.aspx

addresses

Exchange Server 2013 服务在邮件信息或约会条目中找到的地理位置

To be recognized as an address, the string must contain a United States postal address that has at least a subset of the elements of a street number, street name, city, state, and zip code.

Office.context.mailbox.item.getEntities().addresses;

Office.js版本：

Introduced in v1.0

在如下 Outlook 模式中可用：

读邮件(Read)

最低权限要求：

Restricted

官方文档：

https://msdn.microsoft.com/EN-US/library/office/fp160959.aspx

emailAddresses

Exchange Server 2013 服务在邮件信息或约会条目中找到的SMTP邮件地址。

Office.context.mailbox.item.getEntities().emailAddresses；

Office.js版本：

Introduced in v1.0

在如下 Outlook 模式中可用：

读邮件(Read)

最低权限要求：

ReadItem

官方文档：

https://msdn.microsoft.com/EN-US/library/office/fp161123.aspx

urls

Exchange Server 2013 服务在邮件信息或约会条目中找到的internet URL.

Office.context.mailbox.item.getEntities().urls；

Office.js版本：

Introduced in v1.0

在如下 Outlook 模式中可用：

读邮件(Read)

最低权限要求：

Restricted

官方文档：

https://msdn.microsoft.com/EN-US/library/office/fp142254.aspx

Office 邮件应用（Mail Add-in) 的权限分级

根据对邮箱内容不同程度的读写，将Office 邮件应用对邮箱的访问权限分为以下几个级别： Restricted, ReadItem, ReadWriteItem, or ReadWriteMailbox。

一般来讲，Add-In涉及的场景将决定我们使用哪些API，相应的会影响到我们应该为自己的 Add-In赋予什么样的权限（通过add-In的manifest来设定，详情参考https://msdn.microsoft.com/zh-cn/library/office/fp161087.aspx）。

参考资料

Referencing the JavaScript API for Office library from its content delivery network (CDN) --- https://msdn.microsoft.com/en-us/library/office/dn221992.aspx
指定邮件应用程序对用户邮箱的访问权限 --- https://msdn.microsoft.com/zh-cn/library/office/fp161087.aspx
JavaScript API for Office --- https://msdn.microsoft.com/en-us/library/office/fp142185.aspx

转载请注明出处：http://www.cnblogs.com/simpeng/p/4733504.html,作者：simpeng。谢谢！