運用 Google Cloud Functions 強化 Gmail 收件匣的效用

1. 簡介

有數十億企業和個人使用 Gmail 和其他 G Suite 服務來溝通及處理資料。Google 提供的 G Suite API 可以協助您以程式輔助的方式存取這些服務中的資訊，而您可以使用 API 輕鬆將日常工作流程自動化。在本研究室中，您將建構強大的 Gmail 擴充功能，自動分類收到的郵件中的電子郵件，並將這些類別儲存在 Google 試算表中。這項擴充功能會使用 G Suite 的 RESTful API、Google Cloud Functions 和其他 Google Cloud Platform 服務。

建構目標

在本研究室中，您將建構及部署幾個已連線至 G Suite API 和其他 Google Cloud Platform 服務的 Cloud Functions。這些函式的作用如下：

  • 授予 Gmail 和 Google 試算表資料安全存取權
  • 擷取任何收到郵件的附加圖片
  • 使用 Cloud Vision API 將這些圖片分類
  • 在 Google 試算表中寫下這些類別、寄件者地址和附件名稱

學習目標

  • G Suite RESTful API 基本概念
  • Google Cloud Functions 和其他 Google Cloud Platform 服務的基本概念
  • 如何使用 Google Cloud Functions 透過程式存取 Gmail

軟硬體需求

  • 擁有 Gmail 和 Google 試算表存取權的 Google 帳戶。如果沒有 Google 帳戶，請在這裡建立。
  • 具備 JavaScript/Node.js 的基本知識。

2. 首要之務

啟用 API

在這個研究室中，您將使用下列 Google 產品/服務：

  • Google Cloud Functions
  • Google Cloud Pub/Sub
  • Google Cloud Vision API
  • Google Cloud Datastore
  • Gmail API
  • Google Sheets API

Google Cloud Functions

Google Cloud Functions 是 Google 的無伺服器函式即服務平台，可讓您以簡單且可擴充的方式執行個別的程式碼片段 (「函式」)。

如要啟用 Google Cloud Functions，請按一下畫面左上方的三橫線選單，開啟左側導覽側欄：

f457988e33594bb6.png

在導覽選單中找到「Cloud Functions」，然後按一下。按一下「啟用 API」，在專案中啟用 Google Cloud Functions。

Google Cloud Pub/Sub

Google Cloud Pub/Sub 是簡單且可擴充的資料處理和事件傳遞基礎。在本研究室中，資料中心是 Gmail 和 Google Cloud Functions 之間的傳送者。

如要啟用 Google Cloud Pub/Sub，請開啟左側導覽面板，找到「Pub/Sub」並點選該選項。按一下「啟用 API」，在專案中啟用 Google Cloud Pub/Sub。

Google Cloud Datastore

Google Cloud Datastore 是具擴充性與分散式的無伺服器資料庫。

如要啟用 Google Cloud Datastore，請在左側導覽欄中找到「Datastore」並按一下。在新頁面中按一下「Select Datastore Mode」。

98012c91fd4080d4.png

本研究室可以使用任何資料庫位置。按一下 [Create Database] (建立資料庫) 以啟用 Google Cloud Datastore；這項作業會在幾分鐘內完成。

Google Cloud Vision

Google Cloud Vision API 是功能強大的機器學習服務，可透過預先訓練模型從圖片中取得深入分析結果。

如要瞭解如何啟用 Google Cloud Vision API，請參閱以下操作說明。

啟用 Gmail API、Google Sheets API 和 Google Cloud Vision API

再次開啟左側導覽面板，找到 API 和服務。按一下「媒體庫」。在「搜尋 API 與」「服務」欄位，輸入 Gmail。在搜尋結果中選取「Gmail API」，然後按一下「啟用」。

返回「API Library」(API 程式庫) 頁面。搜尋並啟用 Google Sheets API。

重複相同程序。搜尋並啟用 Cloud Vision API。

開啟 Google Cloud Shell

在本研究室中，您將使用 Google Cloud Shell 執行大部分的作業。Cloud Shell 可讓您直接在瀏覽器中使用指令列存取 Google Cloud Platform 資源，因此您不必在本機電腦上管理資源。

如要開啟 Google Cloud Shell，請在頂端藍色橫條上點選「啟用 Cloud Shell」按鈕：

fd5c2925ca9cdfdd.png

畫面底部會顯示新面板：

34f498402e910802.png

按一下「Launch code editor」按鈕，啟動 Cloud Shell 程式碼編輯器：

10f8631ef48bed22.png

Cloud Shell 程式碼編輯器會在新視窗中開啟。

下載程式碼

在 Cloud Shell 中執行下列指令來複製專案：

git clone https://github.com/googlecodelabs/gcf-gmail-codelab.git

cd gcf-gmail-codelab

您應該會在 Cloud Shell 程式碼編輯器中看見新的資料夾 gcf-gmail-codelab。

3. 架構總覽

以下是本研究室的工作流程：

79c5d3e43f674b33.png

  1. 使用者設定 Gmail 推播通知：每當收件匣有新訊息時，Gmail 都會傳送通知至 Cloud Pub/Sub。
  2. Cloud Pub/Sub 會將新訊息通知傳送至 Google Cloud Functions。
  3. 收到新訊息通知時，Cloud Functions 執行個體會連線至 Gmail 並擷取新訊息。
  4. 如果郵件含有圖片附件，Cloud Functions 執行個體會呼叫 Cloud Vision API 來分析附件。
  5. Cloud Functions 執行個體會更新您選擇的 Google 試算表，用於指定訊息的傳送者和下載附件的位置。

4. 授權存取 Gmail

您必須先授權 Cloud 函式存取 Gmail，才能設定自動讀取電子郵件的 Cloud 函式。您必須向 Google 註冊 OAuth 用戶端，並建立相關聯的用戶端 ID。

註冊 OAuth 用戶端

在 Google Cloud 控制台的左側導覽選單中，找到「API 和」服務。按一下「OAuth 同意畫面」。

91b2a3bac30bb2c5.png

在「應用程式名稱」欄位中輸入名稱，例如「GCF + Gmail 程式碼研究室」。其他設定維持不變，然後向下捲動頁面並按一下「儲存」。

建立相關聯的用戶端 ID

切換至「Credentials」(憑證) 分頁。按一下「建立憑證」，然後選擇「OAuth 用戶端 ID」。選擇網頁應用程式類型並為其命名 (您可以在此使用 GCF + Gmail 程式碼研究室)，然後按一下「建立」。暫時將「限制」欄位留白。

記下彈出式視窗傳回的用戶端 ID 和用戶端密鑰。只要在網頁上點選您的客戶名稱，即可再次查看這些值：

1160d8027ea52d90.png

執行授權程序

在程式碼範例中，auth/index.js 指定兩個 Cloud Functions (auth_init 和 auth_callback)，這兩個函式會一起使用您剛建立的用戶端 ID 和用戶端密鑰，執行授權程序。

如要檢查程式碼，請在 Cloud Shell 程式碼編輯器中開啟 auth/index.js。

授權程序會傳回兩種權杖：「存取權杖」和「更新權杖」。

  • 存取權杖是短期的身分證明，可將資料範圍的存取權授予任何人。auth_callback 會在 Cloud Datastore 中儲存這些資料。
  • 更新權杖用於取得新的存取權杖，且使用壽命大幅延長。

一般來說，系統會將其加密，並/或與存取權杖分開儲存。

在 Cloud Shell 程式碼編輯器中編輯 auth/env_vars.yaml。將 YOUR-GOOGLE-CLIENT-ID 和 YOUR-GOOGLE-CLIENT-SECRET 替換為您自己的值。詳情請參閱前面的步驟。暫時維持 YOUR-GOOGLE-CLIENT-CALLBACK-URL 和 YOUR-PUBSUB-TOPIC 的值。

a2b4853c39a78bc6.png

編輯 auth/env_vars.yaml 後，請在 Cloud Shell 中執行下列指令，以部署 Cloud Functions：

cd ~
cd gcf-gmail-codelab/auth

# Deploy Cloud Function auth_init
gcloud functions deploy auth_init --runtime=nodejs8 --trigger-http --env-vars-file=env_vars.yaml

# Deploy Cloud Function auth_callback
gcloud functions deploy auth_callback --runtime=nodejs8 --trigger-http --env-vars-file=env_vars.yaml

部署 Cloud Functions 可能需要幾分鐘的時間。如果出現提示，請授予 Cloud SDK 安裝 Beta 版指令的權限。

接著前往 Google Cloud 控制台，然後點選左側導覽選單中的「Cloud Functions」。在 Cloud Functions 清單中按一下 auth_callback，然後切換至「Trigger」(觸發條件) 分頁標籤。

cb094bd341f9b299.png

45678a327c80e0f1.png

複製網頁上的網址。返回「Cloud Functions」頁面，按一下 Cloud Functions 清單中的 auth_init。在「一般」分頁中，按一下「編輯」。按一下「環境變數、網路、逾時等」，然後將 GOOGLE_CALLBACK_URL 的值替換成剛剛複製的網址。

939ca3bd38047282.png

按一下「Deploy」(部署) 以套用變更。請重複上述程序並更新 auth_callback。

最後開啟左側導覽選單，按一下「API 與」服務 >網域驗證。如要新增授權網域，請按一下「Add domain」(新增網域)。舉例來說，如果你先前複製的網址看起來像

https://us-central1-my-project.cloudfunctions.net/auth_callback

請將下列內容新增為授權網域：

us-central1-my-project.cloudfunctions.net

按下「新增網域」加以確認。

4348748f232ceb87.png

返回「Credentials」(憑證) 頁面。按一下 OAuth 用戶端的名稱，然後新增您複製的網址做為授權的重新導向 URI。按下 Enter 鍵即可確認操作。

移除網址中的 /auth_callback 部分，然後將其餘部分新增為「已授權的 JavaScript 來源」。舉例來說，如果您的網址看起來

https://us-central1-my-project.cloudfunctions.net/auth_callback

請將以下內容新增為來源：

https://us-central1-my-project.cloudfunctions.net/

159bad719432582c.png

按下 Enter 鍵確認操作，然後按一下「儲存」以套用變更。

5. 設定 Gmail 推播通知

如果授權程序成功，auth_callback 會自動呼叫 Gmail API 以設定推播通知。

如要接收 Gmail 推播通知，您必須建立 Pub/Sub 主題。主題訂閱者將自動收到來自 Gmail 的訊息通知。

如要建立 Pub/Sub 主題，請前往 Google Cloud 控制台，然後依序點選「Pub/Sub」>左側導覽選單中的「主題」。按一下「建立主題」。輸入主題名稱 (例如 gmail-watch)，然後按一下「建立」。此外，您必須授權 Gmail 傳送訊息至您的 Pub/Sub 主題：按一下剛剛建立主題的內容選單 (三個垂直排列的圓點)，然後選擇「權限」。按一下「新增成員」，將 gmail-api-push@system.gserviceaccount.com 指定為新成員，並向其授予 Pub/Sub >Pub/Sub 發布者；最後，按一下「儲存」即可套用變更。

更新 Cloud 函式「auth_callback」以指定要使用的 Pub/Sub 主題。按一下左側導覽選單中的「Cloud Functions」，然後選取 Cloud Functions 清單中的 auth_callback。在「一般」分頁中，按一下「編輯」。按一下「更多」，然後將 PUBSUB_TOPIC 的值替換為剛建立的 Pub/Sub 主題名稱。按一下「儲存」以套用變更。

您現在可以授權並設定 Gmail 推播通知。請等待新的變更完成，再返回「Cloud Functions」頁面，在 Cloud Functions 清單中選取 auth_init，然後切換至「Trigger」(觸發條件) 分頁。點選網址，系統會將您重新導向至「Sign-in with Google」(使用 Google 帳戶登入) 頁面：

348ab0a7e0c9cd03.png

使用您擁有的 Gmail 帳戶登入。凡是寄到帳戶收件匣的新郵件都會觸發推播通知。登入之後，您會看到以下頁面：

cfdad62fd02de004.png

點選「允許」即可授予存取權。「auth_callback」會完成授權程序、儲存存取權杖，並為您設定 Gmail 推播通知。這項程序完成後，瀏覽器應會顯示 Successfully set up Gmail push notifications 訊息。

本程式碼研究室會使用 @google-cloud/express-oauth2-handlers 套件，為您自動執行授權工作流程。詳情請參閱 GitHub 上的存放區。

6. 處理收到的訊息

如前所述，您建立的 Pub/Sub 主題的所有訂閱者都會在新訊息送達收件匣時收到通知。pubsub/index.js 會指定 Cloud 函式 watchGmailMessages。一旦以主題訂閱者的身分進行部署後，就會讀取新訊息、分類附加圖片，以及將這些類別匯出至 Google 試算表。

如要檢查程式碼，請在 Cloud Shell 程式碼編輯器中開啟 pubsub/index.js。

擷取訊息

Gmail 推播通知包括與該通知相關聯的電子郵件地址，以及記錄 ID。為求簡單起見，在這個程式碼研究室中，您只需在收到推播通知時要求 Gmail API 提供最新郵件即可。請改用記錄 ID 查詢訊息，以獲得更準確的結果。

// Look up the most recent message.
const listMessagesRes = await gmail.users.messages.list({
  userId: email,
  maxResults: 1
});
const messageId = listMessagesRes.messages[0].id;

// Get the message using the message ID.
const message = await gmail.users.messages.get({
  userId: email,
  id: messageId
});

return message;

分析圖片附件

如果訊息含有圖片附件，watchGmailMessages 會呼叫 Cloud Vision API 為圖片加上註解。在本程式碼研究室中，您將要求 Cloud Vision API 分類圖片並傳回多個圖片標記。例如，如果提供的是藍天的圖片，Cloud Vision API 可能會傳回 blue、sky 和 nature 標記。

watchGmailMessages 會使用 Node.js 適用的 Cloud Vision API 程式庫呼叫 Cloud Vision API：

// Tag the attachment using Cloud Vision API
const analyzeAttachment = async (data, filename) => {
  var topLabels = ['', '', ''];
  if (filename.endsWith('.png') || filename.endsWith('.jpg')) {
    const [analysis] = await visionClient.labelDetection({
      image: {
        content: Buffer.from(data, 'base64')
      }
    });
    const labels = analysis.labelAnnotations;
    topLabels = labels.map(x => x.description).slice(0, 3);
  }

  return topLabels;
};

更新 Google 試算表

watchGmailMessages 會將這項分析的結果匯出至 Google 試算表。包括寄件者名稱、附件名稱以及圖片附件的標記 (如有)。

首先請建立 Google 試算表。開啟 Google 試算表，然後按一下「開始建立新試算表」下方的「空白」範本。複製工作表 ID。舉例來說，如果瀏覽器中的網址如下：

https://docs.google.com/spreadsheets/d/abcdefghij01234567890/edit#gid=0

您的試算表 ID 為 abcdefghij01234567890。在 Cloud Shell 程式碼編輯器中更新 gcf-gmail-codelab/pubsub/env_vars.yaml，並將 YOUR-GOOGLE-SHEET-ID 替換為您自己的值。

watchGmailMessages 會連線至 Google Sheets API，以附加資訊：

const updateReferenceSheet = async (from, filename, topLabels) => {
  await googleSheets.spreadsheets.values.append({
    spreadsheetId: SHEET,
    range: SHEET_RANGE,
    valueInputOption: 'USER_ENTERED',
    requestBody: {
      range: SHEET_RANGE,
      majorDimension: 'ROWS',
      values: [
        [from, filename].concat(topLabels)
      ]
    }
  });
};

最後一步

在 Cloud Shell 程式碼編輯器中開啟 gcf-gmail-codelab/pubsub/env_vars.yaml，然後將 YOUR-GOOGLE-CLIENT-ID、YOUR-GOOGLE-CLIENT-SECRET 和 YOUR-GOOGLE-CALLBACK-URL 替換為您自己的值。您可以在 Google Cloud 控制台中找到這些值：在左側導覽選單中開啟「Cloud Functions」，選取 Cloud Functions 清單中的 auth_init，然後查看「EnvironmentVariable」部分。

部署程式碼

執行下列指令來部署 Cloud 函式：

cd ~

cd gcf-gmail-codelab/pubsub

gcloud functions deploy watchGmailMessages --runtime=nodejs8 --trigger-topic=gmail-watch --env-vars-file=env_vars.yaml

如果您是將 Cloud Pub/Sub 主題命名為 gmail-watch 以外的名稱，請將上述指令中的 gmail-watch 替換成您主題的名稱。部署 Cloud 函式可能需要幾秒鐘的時間。

7. 立即體驗

恭喜您完成設定！將含有圖片附件的電子郵件寄給自己。幾秒後，就會看到您建立的 Google 試算表會自動更新您提供的資訊。