• 發行項

本文章是由機器翻譯。

Microsoft Office

探索 JavaScript API for Office：郵件應用程式

Angela Chu Chu

下載代碼示例

這篇文章是深入看看用於辦公室，可用的支援的 Outlook 和 Outlook Web App 的郵件應用程式的 API 的部分為重點的 JavaScript API 的第四部分。你應該對辦公室應用程式的一些一般理解。如果有疑問，閱讀適用于開發人員中心文檔頁，"用於 Office 應用程式的概述"（bit.ly/12nBWHG)，將使你在正確的道路上。這一系列，"探索新 JavaScript API 為辦公室"的第 1 部分 (msdn.microsoft.com/magazine/jj891051），提供的物件模型，已作為根物件的 Office 物件的高級別概述。郵箱物件，掛在 Office.coNtext，從提供的郵件應用程式特定的功能在物件模型中，大部分的進入點，這是我拿討論。

這篇文章的關鍵點： 是什麼，作為開發人員，你可以用用於辦公室的 JavaScript API 在郵件應用程式中。我還提供了線上配套的文章，我走過一個示例郵件應用程式，在完成與原始程式碼， msdn.microsoft.com/magazine/dn205107。現在，我將討論的辦公室，從開始的一些更基本的常用技巧，然後移到更高級的概念，JavaScript API 的各種功能。

JavaScript API 為辦公室的基本特徵

郵箱物件提供對使用者設定檔，使用者的當前選定項的訪問，形成對這一專案，顯示和子集的 Exchange Web 服務 （EWS） 專案和郵箱中的資料夾進行操作。專案物件表示選定的郵件或約會專案。通過該物件，您可以進一步訪問內置屬性、 自訂屬性和該專案的附件。

控制啟動基於專案類型你可以在要確定何時啟動郵件應用程式的清單中定義規則。目前由使用者選擇並由 Mailbox.item 指定的項可以是郵件 （包括會議邀請、 回應和取消） 或約會的物件。根據您的情況，您可以限制郵件應用程式來啟動，只有特定類型的專案。以下 XML 示例顯示 ItemIs 啟動規則限制郵件應用程式來只為郵件啟動：

<Rule xsi:type="ItemIs" ItemType="Message" />

為 Office 使用 JavaScript API，您可以使用項目類型屬性來驗證選定的項的類型：

Office.context.mailbox.item.itemType

專案存取權限和屬性郵件應用程式所提供的基本功能之一訪問當前選定的項和其內置的屬性。

下面的 JavaScript 示例顯示如何訪問選定的項和其內置屬性、 主題：

// The initialize function is required for all apps.
Office.initialize = function () {
  // Check for the DOM to load.
$(document).ready(function () {
    var item = Office.context.mailbox.item;
    var subject = item.subject;
    // Continue processing the subject.
});
}

知名實體Exchange Server識別某些實體，無論是否使用實體來啟動郵件應用程式可用。 Outlook 和 Outlook Web App 中提取這些實體，如果他們在主題或正文選定項的存在，並且使它們可通過下面的 JavaScript API 方法：

  • getEntities 方法
  • getEntitiesByType(entityType) 方法
  • getFilteredEntitiesByName(name) 方法

支援的實體包括位址、 連絡人、 電子郵件地址和更多。

請注意 Outlook 和 Outlook Web 應用程式中提取只中英文無論您的應用程式清單中指定的預設區域設置的字串。 他們不能提取實體已發送郵件資料夾中。 然後他們可以提取會議建議在郵件中，但不是在約會。

獲取匹配的結果中的上下文啟動你可以指定取決於正則運算式匹配 (ItemHasRegularExpressionMatch 規則) 的啟動規則或實體匹配 (ItemHasKnownEntity 規則) 中選定的項。 可以使用下面的方法來獲得的正則運算式匹配。 這些方法是父項物件，可以是郵件或約會上可用：

  • getRegExMatches 方法
  • getRegExMatchesByName(name) 方法

知名實體一節中列出的方法可用於獲取特定實體的匹配項。 請注意你總是可以使用這些方法來獲得任何實體匹配，無論您使用的郵件應用程式的啟動規則的類型。

例子以下是 ItemHasRegularExpressionMatch 規則，名為 VideoURL，如果選定的項是一個消息和郵件正文包含一個視頻在 youtube 上的 URL，將啟動郵件應用程式的一個示例：

<Rule xsi:type="RuleCollection" Mode="And">
  <Rule xsi:type="ItemIs" ItemType="Message"/>
  <Rule xsi:type="ItemHasRegularExpressionMatch"
    RegExName="VideoURL"
    RegExValue="http://www\.youtube\.com/watch\?v=[a-zA-Z0-9_-]{11}"
    PropertyName="Body"/>
</Rule>

下面的 JavaScript 的代碼示例演示如何使用 Item.getRegExMatches 方法來獲得前面的 VideoURL 正則運算式的匹配：

Office.initialize = function () {
  // Check for the DOM to load.
$(document).ready(function () {
    // Get an array of string matches for the regular expression VideoURL,
    // as specified in the manifest.
var matches = Office.context.mailbox.item.getRegExMatches().VideoURL;
    // Continue processing the matches for the regular expression.
});
}

以下是 ItemHasKnownEntity 規則，啟動郵件應用程式，如果位址是本主題中的示例或消息的正文：

<Rule xsi:type="RuleCollection" Mode="And">
  <Rule xsi:type="ItemIs" ItemType="Message"/>
  <Rule xsi:type="ItemHasKnownEntity" EntityType="Address" />
</Rule>

下面的 JavaScript 的代碼示例演示如何使用 getEntitiesByType 方法獲取的是郵政位址主題或當前所選郵件的正文中的字串陣列：

Office.initialize = function () {
  // Check for the DOM to load.
$(document).ready(function () {
    var item = Office.context.mailbox.item;
    // Get an array of strings that represent postal
    // addresses in the current item.
var addresses = item.getEntitiesByType(
      Office.MailboxEnums.EntityType.Address);
    // Continue processing the array of addresses.
});
}

基於上下文的啟動郵件應用程式 — — 特別是正則運算式匹配或知名實體的存在 — — 是功能強大，可以進行調試的複雜。 在看到 MSDN 庫條、"故障排除郵件應用程式啟動，" bit.ly/11C0H30 如何調試解決啟動問題的提示。

資料存儲每個專案每個 App 自訂屬性的物件允許您在隨後的會話中作為該專案的自訂屬性存儲只有您的郵件應用程式可以訪問的特定專案的資料。 這種資料被表示為鍵-值對。 如果應用程式被設計為運行在多個 Outlook 用戶端和表單因素上的自訂屬性與支援的 Outlook 用戶端和表單因數一起漫遊。

可通過 Item.loadCustomPropertiesAysnc 方法將專案的自訂屬性。 這是採用作為參數的回檔方法的非同步方法。 在載入的自訂屬性時，他們可通過 asyncResult.value 屬性，它傳遞給回檔方法作為輸入參數。 圖 1 演示如何載入、 獲取、 設置和保存當前項的自訂屬性。

圖 1 為當前項工作具有自訂屬性

Office.initialize = function () {
  var mailbox = Office.context.mailbox;
  mailbox.item.loadCustomPropertiesAsync(customPropsCallback);
}
function customPropsCallback(asyncResult) {
  if (asyncResult.status == Office.AsyncResultStatus.Succeeded) {
    var customProps = asyncResult.value;
    var myProp = customProps.get("myProp");
    customProps.set("otherProp", "value");
    customProps.saveAsync(saveCallback);
  }
  else {
    write (asyncResult.error.message);
  }
}
function saveCallback(asyncResult) {
  // Callback method to save custom properties.
}

資料存儲每個郵箱每個 App RoamingSettings 物件允許您將您的郵件應用程式可以訪問為同一郵箱不管郵件應用程式運行在桌上型電腦、 平板電腦或智慧手機上的自訂資料存儲。 下面的 JavaScript 示例顯示了如何在郵件應用程式的初始化事件處理常式中獲取特定于郵箱的資料：

var _mailbox;
var _settings;
Office.initialize = function () {
  // Check for the DOM to load using the jQuery ready function.
$(document).ready(function () {
    // Initialize instance variables to access API objects.
_mailbox = Office.context.mailbox;
    _settings = Office.context.roamingSettings;
    // Continue with app-specific code.
});
}

使用者設定檔你可以訪問該使用者的設定檔使用 Office.coNtext.mailbox.userProfile 屬性。 通過使用者設定檔物件，您可以顯示名稱、 SMTP 位址並簽署了在使用者的本地時區。 下面的 JavaScript 的代碼示例演示如何訪問當前使用者登錄到 Outlook 或 Outlook Web App 的 UserProfile.emailAddress 屬性：

Office.initialize = function () {
  // Check for the DOM to load.
$(document).ready(function () {
    var userProfile = Office.context.mailbox.userProfile;
    var SMTPAddress = userProfile.emailAddress;
    // Continue with processing the user's SMTP address. 
  });
}

顯示 Outlook 表單在 Outlook 使用者可以指定表單在預設情況下顯示約會和消息。 辦公室 JavaScript API 中使用下面的方法，一個郵件應用程式可以顯示約會消息和分別使用的相同的表單，Outlook 將使用：

  • Mailbox.displayAppointmentForm(itemId)
  • Mailbox.displayMessageForm(itemId)

中的代碼圖 2 檢查，看看是否使用者已選定一個約會，並顯示它與 Outlook 預設約會表單。

圖 2 檢查看看如果使用者選擇了一個約會

var myOm;
var myItem;
Office.initialize = function () {
  $(document).ready(function () {
    myOm = Office.context.mailbox;
    // Get the selected item.
myItem = myOm.item;
    // Display the selected appointment.
displaySelectedAppointment();
  });
}
function displaySelectedAppointment() {
  // Display selected item only if the item is an appointment.
if (myitem.itemType == Office.MailboxEnums.ItemType.Appointment)
  {
    myOm.displayAppointmentForm(myItem.itemId);
  }
  else
  {
    // Handle condition as appropriate.
}
}

Mailbox.displayNewAppointmentForm 方法允許您將值分配給新的會議約會表單中的某些欄位，並顯示在使用者填寫約會中的表單。 調用此方法時，指定這些欄位為字串值對清單，如中所示圖 3。

圖 3 將值分配給新的約會表單中的特定欄位

var myOm;
Office.initialize = function () {
  $(document).ready(function () {
    myOm = Office.context.mailbox;
    // After the DOM is loaded, can display the
    // pre-populated new appointment form.
displayFormForNewAppointment();
  });
}
function displayFormForNewAppointment(){
  var formParameters =
  {
    "requiredAttendees" : ["wendy@contoso.com", "derek@contoso.com"],
    "optionalAttendees" : ["shane@contoso.com", "michael@contoso.com"],
    "start" : new Date("September 27, 2012 11:15:00"),
    "end" : new Date("("September 27, 2012 12:30:00"),
    "location" : "Conf room 200",
    "resources" : ['sound', 'lighting', 'recording'],
    "subject" : "Next rehearsal",
    "body" : "This is about the next rehearsal."
  }
  // Display a form to create an appointment with
  // the specified fields in the form.
myOm.displayNewAppointmentForm(formParameters);
}

向約會或消息顯示答覆表單的方法為您提供最多的空間用於自訂：

  • Appointment.displayReplyAllForm(htmlBody) 方法
  • Appointment.displayReplyForm(htmlBody) 方法
  • Message.displayReplyAllForm(htmlBody) 方法
  • Message.displayReplyForm(htmlBody) 方法

與每一種方法，您可以提供一個表示的答覆表單的 HTML 字串。 中的示例圖 4 顯示為郵件答覆所有表單。

圖 4 為全部回覆指定 HTML 形式為訊息項目

var myOm;
var myItem;
Office.initialize = function () {
  // Check for the DOM to load.
$(document).ready(function () {
    myOm = Office.context.mailbox;
    // Get the selected item.
myItem = myOm.item;
    // After the DOM is loaded, display
    // the reply form.
displayReply();
  });
}
function displayReply(){
  // Display a reply form to the sender and recipients only
  // if the selected item is a message.
if (myitem.itemType == Office.MailboxEnums.ItemType.Message) {
      myItem.displayReplyAllForm
      ("<html><head><head><body>This is the body of " +
       "the email reply.</body></html>");
  }
}

進階概念

獲取項附件郵件應用程式可以使用用於辦公室和 EWS 回檔權杖的 JavaScript API 來訪問當前所選的消息或任命該使用者的郵箱中的附件。使用回檔權杖允許在郵件應用程式的後端，伺服器端代碼 — — 或協力廠商 Web 服務 — — 打電話給 EWS 操作，GetAttachment，事實上要獲得特定的附件。

下面介紹一個郵件應用程式如何獲取附件 (這一過程也說明了圖 5）：

  1. 郵件應用程式使用 Mailbox.getCallbackTokenAsync 來請求回檔的標記、 使用 Item.attachments 來獲取有關所選的約會或郵件 （包括附件 Id），附件的中繼資料和使用 Mailbox.ewsUrl 獲取的 EWS 終結點的 URL 的當前電子郵件帳戶。
  2. 郵件應用程式將回檔權杖、 附件 Id 和 EWS 終結點的 URL 傳遞給伺服器端的代碼中。
  3. 該伺服器端代碼調用 EWS GetAttachment 操作以從該 Exchange 存儲區獲取實際的附件。


圖 5 從Exchange Server訪問附件的郵件應用程式

請注意伺服器端代碼應通過直接創建 EWS 請求訪問 EWS。您不能使用 Mailbox.makeEws­RequestAsync 方法來訪問 GetAttachment 操作。寫這篇文章，訪問附件支援如果在 Outlook Web App 上的郵件應用程式運行。如果在 Outlook 中的郵件應用運行該功能不可用。

請參見 MSDN 代碼示例中，"為辦公室的郵件應用程式：從 Exchange 伺服器中獲取附件"（bit.ly/11dG9fS)，例如，如何訪問郵件應用程式中的附件。

單一登入使用者權杖您的郵件應用程式可以使用常見的身份驗證的 Web 技術來進行身份驗證和授權使用者。如果您想要支援單一登入身份驗證為您的使用者在 Outlook 和 Outlook Web 應用程式，您可以通過調用 Mailbox.getUserIdentityTokenAsync 方法使用交換身份權杖。

單點登錄基於Exchange Server分配交換身份權杖Exchange Server上使用者的電子郵件帳戶。交換身份權杖包含多個欄位，其中有一個簽名驗證權杖，並代表 Exchange 電子郵件帳戶的唯一識別碼。

一般情況下，對使用者進行身份驗證的郵件應用程式可以與 Web 服務進行交互 — — 可以是郵件應用程式的伺服器端代碼 — — 或協力廠商 Web 服務，它使用其自己的身份提供程式 (IdP) 在系統中聯合的身份驗證使用者的身份。單點登錄問題的關鍵是 Web 服務維護的唯一 ID （從交換身份權杖） 和使用者標識 （這就是到國內流離失所者） 之間的映射。

圖 6 提供高級別描述的使用交換身份權杖進行身份驗證。

以下總結了該過程：

  1. 郵件應用程式調用 Mailbox.getUserIdentityTokenAsync 來請求交換身份權杖的使用者指定一個回檔方法，運行時非同步 get 操作完成。
  2. 回呼函數獲取交換身份權杖並將它傳遞給 Web 服務進行身份驗證。
  3. Web 服務獲取公開金鑰從Exchange Server來驗證該權杖。
  4. 根據是否使用者已簽名之前，Web 服務收益，如下所示：
    1. 如果是第一次使用者登錄到郵件應用程式，不事先存在映射為該帳戶和回應郵件應用程式來提示使用者輸入憑據的 Web 服務。在收到全權證書，郵件應用程式傳遞到 Web 服務。
    2. 服務然後創建提供的權杖，並從知名到國內流離失所者的憑據的使用者身份的唯一 ID 之間的映射。使用的憑據，該服務可以使使用者登錄。
    3. 在隨後的時間：當使用者從桌面、 平板電腦或智慧手機上的瀏覽器在 Outlook 或 Outlook Web App 中打開郵件應用程式時，必須執行以下步驟：
      1. 郵件應用程式調用 getUserIdentityTokenAsync 並在標記中獲取相同的唯一 ID
      2. 郵件應用程式將權杖傳遞給 Web 服務。
      3. Web 服務驗證該權杖。
      4. Web 服務然後查找映射表，查找使用者，並且授權訪問。


圖 6 使用交換身份權杖的身份驗證

一旦您驗證權杖，您可以保留登錄，即使當使用者打開郵件程式從另一宿主應用程式或設備的使用者。

身份驗證和驗證的詳細資訊是相當複雜的。你可以使用 EWS 託管 API 驗證庫簡化了過程。使用該驗證庫，Web 服務將創建物件、 提取和將標記放入物件、 驗證是否簽名是有效的和如果它是有效的然後放的唯一識別碼映射資料庫。

有關使用交換身份權杖的身份驗證的詳細資訊，請參閱以下適用于開發人員中心文檔：

有關代碼示例：

  • 您可以參考"為 Outlook 郵件應用程式：使用用戶端身份權杖"示例在 C# 中為 2012年的Visual Studio（bit.ly/ZxS85b) 的 C# 示例郵件應用程式和使用交換身份權杖進行身份驗證的 Web 服務。
  • 請參閱"outlook 郵件應用程式：驗證使用.NET 框架的用戶端身份權杖"(bit.ly/17j9FSZ) 為例，如何使用.NET 框架來驗證 Exchange 用戶端的身份權杖。

EWS 子集訪問使用 Mailbox.makeEwsRequestAsync 方法，郵件的應用程式可以訪問 EWS 操作以創建、 查找、 獲取、 更新、 移動或發送專案或資料夾中的一個子集。例如，您可以使用 CreateItem 操作創建約會、 郵件或連絡人。您可以使用 FindItem 操作來查找郵箱中的專案。並且你可以使用 SendItem 操作發送郵件或會議的邀請。受支援的操作子集適用于僅在使用者的郵箱。其他涉及到整個組織的 EWS 操作 — — 例如訪問全域通訊清單或逐一查看每個組織中的人員 — — 允許郵件應用程式。而且，因為支援的操作的子集是強大的郵件的應用程式必須請求讀/寫郵箱許可權在應用程式清單中，，只有管理員才可以安裝需要這種許可的郵件應用程式。

當調用 Mailbox.makeEwsRequestAsync 方法時，你要求 EWSExchange Server承載該使用者的郵箱上。在調用 makeEwsRequestAsync 之前, 指定以下參數為輸入的參數：

  • 資料參數：創建想要調用的 EWS 操作 XML SOAP 請求。
  • 回檔參數：一個回檔方法，將處理操作的回應。
  • 上下文中的參數:任何輸入資料的回檔方法。

當操作完成後時，辦事處框架的應用程式調用的回檔方法具有一個參數，是一個 AsyncResult 物件，類似于其他非同步方法時，你見過在這一系列的第一部分。回檔方法可以訪問非同步­Result.value 屬性來獲取 XML SOAP 回應，其中包含有關該操作的資料。回檔方法也可以訪問訪問通過上下文中參數中傳遞的任何其他輸入的參數的 AsyncResult.asyncCoNtext 屬性。回檔方法然後將分析的 XML 在 SOAP 回應中獲取資料的有關為其目的。

有關支援的 EWS 操作和進一步的細節的完整清單，請參見開發中心檔、"調用 Web 服務從郵件應用程式的 Outlook"(bit.ly/12jtH0z)。

有關演示如何調用 GetItem 操作的郵件應用程式的示例，請參閱"outlook 郵件應用程式：讓 EWS 請求"示例在 C# 中為 2012年的Visual Studio（bit.ly/Zv3hEQ)。

總結

包裝作為辦公室的 JavaScript API 的好四部分探索建設郵件應用程式，我探討了。在這以前的專欄文章系列和線上的伴侶本文的這一部分中，請參閱：

Angela Chu-Hatoun 作為一個軟體發展者開始和轉寫為她解釋軟體是如何工作的更大興趣。她 12 年來，一直在辦公室司一個程式師作家和有關為 Outlook 創建的辦公室和其他解決方案的應用程式的開發人員寫。她喜歡讀了有關當前事務、 園藝、 旅遊、 食品和時尚。

衷心感謝以下技術專家對本文的審閱：安德魯薩拉馬托夫 (Microsoft) 和Tim灣 (Microsoft)
Tim灣 2003 年畢業于加州理工學院和工程和應用科學學位。在過去的九年他一直在 Outlook 中的軟體發展人員。他做了大量 Outlook 2013 年以及以前的版本中的 Outlook 物件模型中的郵件應用程式功能。他期待著新功能和改進功能使全球範圍內為客戶。