Arduino Yun 筆記：測試呼叫 Temboo 的 Gmailv2 與 Spreadsheets choreos 功能

Arduino Yún 名稱中的 "Yún" 正是中文的 "雲" ，也就是特別強調在雲端應用的整合能力，所以除了 Yun 本身已具備的連網功能之外，更透過與 Temboo 的合作，很方便的就能夠連接許多目前相當普遍的雲端服務，如：Google、Facebook、Twitter、Yahoo Weather、Dropbox ... 等。

Temboo 平台提供了數十種連接雲端服務的 Choreos，
Choreo 是指呼叫每個特定雲端服務的可重複使用程式碼，用以簡化程式開發工作。同時在最新版本的 Arduino IDE 中，也已經預載了 Temboo 程式庫，結合 Choreo 很容易的就能夠實現 Arduino Yun 在雲端的整合應用。

(圖片來源：arduino.cc)

在 Temboo  網站中提供有 12 個 Arduino Yun 連接雲端服務的範例，同時在 Arduino IDE 的  File - Examples - Temboo - Arduino Yun 中也有相對應的範例程式，這些都是相當好的參考資源。

(圖片來源：Temboo.com)

本次的測試是以 Arduino Yun 在 Sketch 中使用 Bridge 以及 Temboo 程式庫 呼叫 Temboo 的 Gmailv2 與 Google Spreadsheets 兩個 Choreos 功能，將 Arduino 端的資訊透過 Gmail 傳送至指定信箱 以及 存放到 Google 試算表中。

以下是過程的相關記錄：

Arduino Yun 呼叫 Temboo Choreo 的步驟與方式： 

A. 設定 Temboo 帳號的認證憑證：
使用 Temboo 服務需要先申請 Temboo 帳號，Temboo 主要為付費服務，同時也有每月限制呼叫 250 次的免費方案，目前則有一個限期一個月免費體驗 Enterprise Plan 的優惠方案。
接著建立 Application 並產生 Application Key 作為請求呼叫 Choreos 的憑證。

※ 在 Arduino sketch 中設定 Temboo 帳號憑證的方式如下：

• 先建立一個 Temboo Choreo 的 client 物件：
  TembooChoreo   choreo_obj;
• 接著啟動 Temboo Choreo client 物件：
  choreo_obj.begin();
• 再設定 Temboo 帳號憑證：
  choreo_obj.setAccountName("Temboo帳號");
  choreo_obj.setAppKeyName("Application名稱");
  choreo_obj.setAppKey("Application Key");

B. 設定所要呼叫的 Choreo：
Temboo 依據功能類型以 Bundles 方式將每個雲端服務所有的 Choreos 分類整理成樹狀結構的 Choreo Library，指定所要呼叫 Choreo 的方式也就是依據 Choreo 在 Library 中的路徑位置來設定。

以本次測試的 Gmailv2 與 Google Spreadsheets 兩個 Choreos 為例， 在 Arduino sketch 中會呼叫  setChoreo("Chroeo 路徑") 函式，並分別以兩個 Choreos 的路徑作為參數 ：

1. 以 Google Gmailv2 傳送郵件：
   choreo_obj.setChoreo("/Library/Google/Gmailv2/Messages/SendMessage");
2. 增加一筆資料到 Google Spreadsheets：
   choreo_obj.setChoreo("/Library/Google/Spreadsheets/AppendRow");

C. 輸入呼叫 Choreo 所需要的資訊：
呼叫每一個 Choreo 所對應 Web service 都有所需要輸入的資料欄位，包含：雲端服務的認證憑證 與  Web service 所要求的資訊。

每個資料欄位都是以 Key - Value 方式設定，在 Arduino sketch 中，每個資料欄位會以呼叫 addInput("Key name", "Value") 函式方式傳送。

在 Temboo 網站中的每個 Choreo 頁面包含有所需要輸入的資料欄位資訊，Choreo 頁面可以由 Temboo 首頁左側上方的 Search Library 搜尋功能尋找，或展開瀏覽下方的 Choreo Library 樹狀結構。

以本次所測試的 Gmailv2 與 Google Spreadsheets 兩個 Choreos 為例，兩個 Choreo 頁面的輸入欄位資訊 與 Arduino sketch 呼叫函式的方式分別如下：

※  Google -Gmailv2 - Messages - SendMessage Choreo ：

上圖中 Choreo 頁面為呼叫 Gmailv2 傳送郵件的 Web service 所需輸入的欄位，其中前三個欄位 (ClientID、ClientSecret、RefreshToken) 為 Google Gmailv2 Web services 的認證憑證資訊，取得方式可以參考 Temboo "Google . Gmailv2" bundle 頁面中的 SETUP INSTRUCTIONS 說明。

※ 在 Arduino sketch 中呼叫函式的程式碼如下：
choreo_obj.addInput("ClientID", "你的 Google client ID");

choreo_obj.addInput("ClientSecret", "你的 Google client 密碼");

choreo_obj.addInput("RefreshToken", "重新取得 Google access token 的 Token");

choreo_obj.addInput("From", "寄送使用的郵件信箱");

choreo_obj.addInput("MessageBody", "郵件內容");

choreo_obj.addInput("Subject", "郵件主旨");

choreo_obj.addInput("To", "收件人郵件信箱");


※ Google - Spreadsheets - AppendRow Choreo：

上圖 Choreo 頁面為呼叫 增加一筆資料到 Google 試算表 的 Web service 所需輸入的欄位，其中前三個欄位 (ClientID、ClientSecret、RefreshToken) 為 Google Spreadsheets Web services 的認證憑證資訊，取得方式可以參考 Temboo "Google . Spreadsheets" bundle 頁面中的 SETUP INSTRUCTIONS 說明。

※ 在 Arduino sketch 中呼叫函式的程式碼如下：
choreo_obj.addInput("ClientID", "你的 Google client ID");

choreo_obj.addInput("ClientSecret", "你的 Google client 密碼");

choreo_obj.addInput("RefreshToken", "重新取得 Google access token 的 Token");

choreo_obj.addInput("RowData", "一筆以逗點分隔成多個項目的資料");

choreo_obj.addInput("SpreadsheetTitle", "Google 試算表的名稱");

D. 執行 Choreo 並等候執行結果：

最後呼叫 choreo_obj.run() 函式，執行 Choreo 以送出對 Google 請求執行 Gmailv2 與 AppendRow 的 Web services 並等候回傳的執行結果，相關的 Arduino Sketch 程式碼如下：

unsigned int returnCode = choreo_obj.run();
if (returnCode == 0) {
  Serial.println("Success !");
  }
else {
  while (choreo_obj.available()) {
      char c = choreo_obj.read();
      Serial.print(c);
  }
}
choreo_obj.close();

Your Arduino Yún comes loaded with Temboo