[How-To] 如何申請及啟用 Gmail API 的 OAuth 2.0 憑證以供其他程式使用

申請與啟用 Gmail API 的 OAuth 2.0 憑證

最後更新時間: 2019/9/12

如果你想要透過郵件寄送程式[1]大量寄發電子郵件,又不想自己架設電子郵件伺服器[2],申請 Gmail API 讓郵件寄送程式使用其實相當方便,有需要的朋友可以試試。

使用 Gmail API 寄送郵件的好處

假如你使用 Gmail 帳戶透過郵件寄送程式傳送郵件,我想大多數人都會直接在設定中的對應欄位填入 Google 的帳戶名稱及密碼;如果你這麼做,當你必須更換 Google 帳戶的密碼時,你就必須重新變更郵件寄送程式內的密碼設定,否則傳送郵件馬上會因密碼變更而出錯。

但是當你改採透過 Gmail API 授權郵件傳送程式寄送郵件,就不會有這個困擾;你的 Google 帳戶再怎麼變更密碼,都不影響郵件寄送程式的郵件傳送功能。在使用 Gmail API 的 OAuth 2.0 憑證並授權給郵件寄送程式使用的過程中,郵件寄送程式在取得授權後直接呼叫 Gmail API,中間的連線過程並不採用帳號密碼,而是 Gmail API 與這個郵件寄送程式間專屬的金鑰。正因為如此,Google 帳戶的密碼變更,並不會讓金鑰產生變化,所以與密碼變更完全脫勾。

此外,無論你使用的是個人 Gmail 帳戶,或是 Google 提供給教育單位、組織或企業使用的 G Suite[3],只要電子郵件服務是由 Google 所提供,均可使用 Gmail API。

如果你必須使用 Gmail 大量寄送郵件,不妨改用 Gmail API,以後便不必再為變更 Google 帳戶的密碼而煩心。

申請 Gmail API 前的準備工作

以下需要先行準備的項目,要準備幾項全視你申請的 Gmail API 使用方式而定,請自行參閱需要呼叫 Gmail API 的應用程式說明的相關說明。

如果你建立的 Gmail API 要將通知傳送至某個網站,那就必須先準備好以下項目。

  • 用來接收 Google API 通知的網站,你要具備該網站的網域名稱[4]管理權限,也就是說你要有該網域名稱的 DNS 管理權限。
  • 有了網域名稱管理權限,請使用你要用來寄送 Gmail 郵件的 Google 帳戶登入 Google Search Console,在 Google Search Console 裡進行網站擁有權驗證。

假如你不具備網站的網域名稱管理權限,你可以請具備該權限的管理員先在 Google Search Console 中驗證網站擁有權,然後在 Google Search Console 中,將這項擁有權指派給你要用來寄送電子郵件的 Google 帳戶。

除此之外,因應不同的使用目的,你還需要準備以下項目。

  • 在你的網站新增兩個頁面,分別是要用來說明「隱私權政策」及「服務條款」,然後你會需要這兩個頁面的完整網址。
  • 要做到更精細的話,請上傳一張 120 像素見方[5]的圖片到你的網站上,並取得該圖片網址,這會用在 Gmail API 或其他需要產品標誌的 Google API 產品中。

申請及啟用 Gmail API 的 OAuth 2.0 憑證

多數人都會覺得 API 是屬於程式開發人員在使用的東西,其實不然;如果你有架設網站,很多功能都會要求網站管理員去申請某個 Google 所提供的 API

[6]

,然後將 API 中的特定資料回填至應用程式內,功能才會開始運作。

必須同意相關服務使用條款才能使用

請注意,當你使用 Google API 時,或許會遇到需要同意服務條款的畫面,只要碰到這種類似畫面,你只能按一下 [同意]。

你不同意條款的話,就不能使用該項服務;這項規定並非 Google 獨有,而是一種通則,也是廠商自我保護的一種方式。

除了必須同意相關服務條款之外,申請 Google 所提供的 API,並沒有帳戶類型限制,且一般用量的使用完全免費;各位只要照著以下步驟操作,就可以完成 Gmail API 的申請。

建立 Gmail API

  1. 請先連線至 Google API 網站,然後點一下畫面左側的 [資料庫]。
    • 請注意,這時你要登入的 Google 帳戶,就是將來要用來寄送電子郵件的帳戶;如果你擁有多個 Google 帳戶,千萬不要以錯誤帳戶進行登入。
  2. 在 [資料庫] 頁面的 [G Suite] 區段,按一下 [Gmail API]。
    在 [資料庫] 頁面的 [G Suite] 區段,按一下 [Gmail API]
  3. 按一下 [選取專案],然後按一下 [建立][7]
    按一下 [建立專案],然後按一下 [建立]
  4. 在 [專案名稱] 欄位中輸入個你將來會認得的專案名稱,專案 ID 會由系統自動產生,然後按一下 [建立]。
    輸入個好記有意義的專案名稱,然後按一下 [建立]

     

    • 專案名稱不接受中文[8],僅接受英文字母[9]、數字、引號、 連字號、空格或驚嘆號,且專案名稱必須 4 個字元以上、不超過 30 個字元。
    • 專案 ID 要自行編輯是可以的,但是專案 ID 必須要在整個系統裡是唯一的,你就不用再費心去想了,系統自動產生的專案 ID 必然是唯一的。

建立 Gmail API 所需要的憑證

請注意,同一個 API 能夠建立的憑證類型不僅僅只有 OAuth 一種,請依照你需要呼叫 Gamil API 的那個應用程式的說明,建立合適的憑證。為了讓 WordPress 的 Postman SMTP Mailer/Email Log 外掛順利呼叫 Gmail API,我們這次便示範建立 Gmail API 的 OAuth 2.0 憑證。

  1. 在 Google API Console 裡選取你要進行設定的 Gmail API,按一下 [Gmail API] 旁的 [啟用],然後按一下 [建立憑證]。
    按一下 [Gmail API] 旁的 [啟用],然後按一下 [建立憑證]

     

    • 假如你是連續操作沒有間斷,目前一定停留在需要進行設定的 Gmail API。
  2. 設定憑證類型,設定完畢會自動進入下一項設定。
    • 您目前使用哪個 API: Gmail API。
    • API 的呼叫來源為何: 網路瀏覽器 (JavaScript)。
    • 您需要存取什麼資料: 使用者資料。
      設定憑證類型
  3. 建立 OAuth 2.0 用戶端 ID,設定完畢會自動進入下一項設定。請注意,以下三項資料均為必填項目
    • 名稱: 請取一個你將來記得起來使用目的的名稱,可使用中文;為了避免不必要的錯誤,阿力獅使用英文取名。
    • [已授權的 JavaScript 來源] 與 [已授權的重新導向 URI]: 假如需要使用的那個會用到 Gmail API 的應用程式是英文版,那這兩項資料便分別是 Authorized JavaScript origins 與 Authorized redirect URI。
    • 這兩項資料必須由需要呼叫 Gmail API 的應用程式提供,請不要使用螢幕擷圖中的資料;即使你照著輸入,你所建立的 Gmail API 還是會無法正常運作。
      建立 OAuth 2.0 用戶端 ID
  4. 設定 OAuth 2.0 同意畫面。請注意,按一下 [更多自訂選項] 會有更多選項需要填寫。阿力獅將必填項目標註為紅色。設定完畢請按一下 [繼續]。
    • 電子郵件地址: 請注意,假如你沒有使用了錯誤的 Google 帳戶進行登入,這裡應該預設會顯示你要用來寄送電子郵件的 Google 帳戶。假如不是你要用來寄送電子郵件的 Google 帳戶,代表你之前用了錯誤 Google 帳戶登入 Google API 網站。
    • 向使用者顯示的產品名稱: 可以輸入中文,不過阿力獅為了避免麻煩,一樣是輸入英文名稱。
    • 首頁網址: 填入會使用這個 Gmail API 的網站的首頁網址。
    • 隱私權政策網址: 請填入對應網頁的完整網址。
    • 服務條款網址: 請填入對應網頁的完整網址。
      設定 OAuth 2.0 同意畫面
  5. 假如你需要備份這項憑證,請按一下 [下載] 後自行想辦法備份。接下來按一下 [完成] 就可以結束 Gmail API 的憑證設定。
    按一下 [完成] 便可結束 Gmail API 的憑證設定

為已建立的 Google API 驗證網域 (選用項目)

如果你要使用的應用程式有需要接收 Gmail API 的通知,就必須進行網域驗證。這點請自行查相關說明;以 WordPress 的 Postman SMTP Mailer/Email Log 外掛來說,無須驗證網域便能呼叫 Gmail API。

Google API 要進行驗證網域的話,一律以 Google Search Console 內的結果為主。以下示範便是已預先在 Google Search Console 內驗證過網站所有權的結果,所以幾個點擊就完成了網域驗證。

  1. 需要的話,請先選取正確的 Google API 專案。在正確的 Google API 專案頁面中,按一下畫面左側的 [憑證],然後按一下 [網域驗證]。
  2. 按一下 [新增網域]。
    按一下 [新增網域]
  3. 輸入要驗證的網站網址,然後按一下 [新增網域]。
    輸入要驗證的網站網址,然後按一下 [新增網域]
  4. 因為阿力獅已經事先在 Google Search Console 內驗證了網站擁有權,所以會馬上驗證成功,並將通過驗證的網域列在畫面上。

使用 Gmail API 的 OAuth 2.0 憑證

會需要使用 Gmail API 的郵件相關應用程式,都會需要你建立的 Gmail API 的 OAuth 2.0 憑證中的兩項資料。

  • 用戶端 ID,英文為 Client ID。
  • 用戶端密碼,英文為 Client Secret。

通常只要在應用程式內將這兩項資料填入應用程式設定的對應欄位中,經過授權程序就可以讓應用程式呼叫並使用 Gmail API 所提供的功能。

要取得以上兩項資料,請依照以下步驟即可取得。

  1. 請在 Google API Console 網站內先選取正確的 Google API,此例中就是你剛剛建立的 Gmail API。
  2. 按一下畫面左側的 [憑證],然後在 [憑證] 畫面中按一下 [QAuth 2.0 用戶端 ID] 下方中正確的名稱[10]
    按一下 [QAuth 2.0 用戶端 ID] 下方中正確的名稱
  3. 在 [網路應用程式用戶端 ID] 頁面中,你就可以找到 [用戶端 ID] 以及 [用戶端密碼] 的資料了。
    [用戶端 ID] 以及 [用戶端密碼] 的資料

如何解決 Google API 的 OAuth 驗證授權錯誤 (400, invalid_scope)

請注意,現在申請 Gmail API 完成可以直接使用後,不會再產生這項驗證授權錯誤,因此已不再需要加入 Allow Risky Access Permissions By Unreviewed Apps 網上論壇。
Gmail API 產生授權錯誤

在將 Google API 授權給應用程式使用的時候,發生如下圖般的錯誤。

想點創意設計工作室找到的解決方案

要解決這個問題,依照想點創意設計工作室找到的解決方案,就是加入 Google 官方設立的 Allow Risky Access Permissions By Unreviewed Apps 網上論壇;加入之後,便不會再出現授權錯誤。

進入這個網上論壇頁面後,按一下 [加入群組],然後再按一下 [加入這個群組] 即可完成加入[11],完全無須任何審核程序,這點你無須擔心。

其實加入這個網上論壇後畫面上所顯示的訊息,就是你為什麼要加入這個網上論壇才能在授權應用程式時不發生錯誤訊息的原因;多了「加入這個網上論壇」這項操作,是要提醒你你正在授權給 Google 系統不認識的應用程式,你必須風險自負。

加入Google 官方開設的 Allow Risky Access Permissions By Unreviewed Apps 網上論壇後的說明

此外,根據 Allow Risky Access Permissions By Unreviewed Apps 網上論壇的這篇通知,Google 建議你的應用程式透過 OAuth 驗證並取得授權後,你就該退出這個網上論壇,直到有需要時再次加入即可。

Google 會這樣說,都是為了安全性考量。

Gmail API 的使用限制及注意事項

使用 Gmail API 寄送郵件並非沒有限制,設下限制是為了避免有心人濫用。

所有的電子郵件系統,計算信件寄送的數量都是以收件者總數為準;舉例來說,5 封電子郵件寄送至 10 個電子郵件地址,則計為 50 名收件者。

Google 的官方文件為參考基準,Google 限制每個帳戶每僅能使用 250 個 Quota Unit (配額單位);而 Gmail API 的不同 Method,會耗用的配額單位也不同。以寄送信件的 messages.send 而言,每寄送給一位收件者需要耗用 100 個配額單位,所以每位 Gmail API 使用者每秒最多只能寄給 2.5 位收件者。

假如你有兩封信件分別要寄給 300 及 250 個電子郵件地址,則會需要寄送 1 x 300 + 1 x 250 總計 550 個收件者,那 Gmail API 會需要 550 / 2.5 總計 220 秒才能完成寄送工作。

每個 Gmail API 帳戶每日配額 250 x 60 x 60 x 24 總計 21,600,000 個配額單位,純寄件的話的話可寄給 216,000 個收件者 – 事情當然不會這麼美好!

依照 Google 帳戶類型及郵件寄送的方式,每個帳戶每日能寄送的收件者上限請參考《G Suite 的 Gmail 傳送限制》或《SMTP 轉發服務的傳送限制》。

請注意,即使使用 Gmail API 寄送郵件的次數並沒有想像中的高,但還是比使用一般電子郵件用戶端應用程式所限制的數量來的高上許多喔。這對於一般使用量來說,綽綽有餘。

結語

許多網路應用程式或是網站功能都會要求使用者申請 Google API,將申請好的 API 內的相關資料填入設定中,才能正常運作 。申請 Google API 並沒有帳戶資格限制,一般合理使用的用量也多為免費,只要你耐心、用心看完相關的操作指示,多半可以很輕易就申請完成。

這次申請 Gmail API 主要是要讓 WordPress 的 Post SMTP Mailer/Email Log 外掛使用,這樣它便可以透過 Gmail API 寄送郵件;至於 Post SMTP Mailer/Email Log 外掛如何設定,阿力獅接下來會有專文介紹。

文章摘要
如何申請及啟用 Gmail API 的 OAuth 2.0 憑證以供其他程式使用
文章標題
如何申請及啟用 Gmail API 的 OAuth 2.0 憑證以供其他程式使用
內容說明
許多與郵件相關的網站功能會需要使用 Gmail API 的 OAuth 2.0 憑證,這篇文章以圖文步驟方式教你免費取得 Gmail API 的 OAuth 2.0 憑證。
文章作者
文章出處
阿力獅的教室
作者標誌

附註   [ + ]

1. 這裡所指的郵件寄送程式不是像 Gmail 的行動版 App 這種電子郵件用戶端應用程式,而是指網站寄送通知的郵件系統或是電子報寄送程式。
2. 電子郵件伺服器即 Mail Server,在目前雲端時代可以不必使用實體機器、不用安裝伺服器作業系統及電子郵件伺服器軟體就可以自行架設,免費及付費的都有,以後阿力獅會寫幾篇文章介紹我自己在使用的雲端郵件伺服器服務。
3. 既有的 Google Apps 免費版也可以使用 Gmail API。
4. 網域名稱就是英文的 Domain Name。
5. 像素即 Pixel,單位為 px。
6. 舉例來說,許多與 Google 地圖相關的功能,會在設定時要求使用者申請 Google Maps API
7. 要申請新的 API,當然是按一下 [建立]。
8. 截至 2017 年 6 月 25 日為止,中文仍屬 Google API 專案名稱的無效的字元,不可使用;若有變更,以你使用時的狀況為主。
9. 阿力獅測試過用西班牙文、葡萄文牙、法文、德文及俄文的字元,系統都不接受,所以目前系統應該只接受英文字元。
10. 所以說取名很重要,取的名稱一定要讓將來的自己看的懂。
11. 至於你要不要在這連結你的 Google 個人資料,要不要接收通知,全憑你的決定。