進階 Google 服務

Apps Script 中的進階服務可讓經驗豐富的開發人員連線至某些公用 Google API,而且設定比使用 HTTP 介面少。進階服務基本上是這些 Google API 周圍的精簡包裝函式。運作方式與 Apps Script 的內建服務類似,例如它們提供自動完成功能,而 Apps Script 會自動處理授權流程。不過,您必須先啟用進階服務,才能在指令碼中使用。

如要瞭解哪些 Google API 為進階服務提供,請參閱參考資料中的「進階 Google 服務」一節。如果想使用未以進階服務形式提供的 Google API,只要按照其他外部 API 的方式連線至該 API 即可。

進階服務還是 HTTP?

每項進階 Google 服務都與公開的 Google API 相關聯。在 Apps Script 中,您可以透過進階服務或直接使用 UrlFetch 提出 API 要求,來存取這些 API。

如果您使用進階服務方法,Apps Script 會處理授權流程,並提供自動完成支援。不過,您必須先啟用進階服務,才能使用進階服務。此外,部分進階服務僅提供 API 提供的部分功能。

如果您使用 UrlFetch 方法直接存取 API,基本上就是將 Google API 視為外部 API。透過這個方法,您可以使用 API 的所有層面。不過,您必須自行處理 API 授權。您也必須建構任何所需的標頭,並剖析 API 回應。

一般來說,最簡單的做法是盡可能使用進階服務,只有在進階服務無法提供您需要的功能時,才使用 UrlFetch 方法。

需求條件

您必須先滿足下列需求條件,才能使用進階服務:

  1. 您必須在指令碼專案中啟用進階服務
  2. 您必須確保已在指令碼使用的 Cloud Platform (GCP) 專案中啟用與進階服務對應的 API。

    如果您的指令碼專案使用 2019 年 4 月 8 日當天或之後建立的預設 GCP 專案,那麼在您啟用進階服務並儲存指令碼專案後,系統就會自動啟用 API。如果您尚未同意《Google Cloud 服務條款》和《Google API 服務條款》,您可能也需要先同意這些條款。

    如果您的指令碼專案使用標準 GCP 專案或舊版的預設 GCP 專案,您必須在 GCP 專案中手動啟用進階服務對應的 API。您必須具備 GCP 專案的編輯權限,才能進行這項變更。

詳情請參閱 Cloud Platform 專案

啟用進階服務

如要使用進階 Google 服務,請按照下列操作說明進行:

  1. 開啟 Apps Script 專案。
  2. 按一下左側的「編輯器」圖示
  3. 在左側的「Service」(服務) 旁邊,按一下「Add a service」(新增服務)
  4. 選取進階 Google 服務,然後按一下「新增」

您啟用進階服務後,自動完成功能就會開放使用。

方法簽章的判定方式

進階服務通常會使用與對應的公用 API 相同的物件、方法名稱和參數,不過方法簽章會經過翻譯以便用於 Apps Script。指令碼編輯器的自動完成函式通常會提供足夠的資訊,有助於快速上手,但以下規則說明 Apps Script 如何從公開的 Google API 產生方法簽章。

傳送至 Google API 的要求可接受多種資料,包括路徑參數、查詢參數、要求主體和/或媒體上傳附件。部分進階服務也可以接受特定的 HTTP 要求標頭 (例如日曆進階服務)。

Google Apps Script 中對應的方法簽章包含下列引數:

  1. 要求主體 (通常為資源),以 JavaScript 物件表示。
  2. 路徑或必要參數,做為個別引數。
  3. 媒體上傳附件,做為 Blob 引數。
  4. 選用參數,用來將 JavaScript 物件參數名稱對應至值。
  5. HTTP 要求標頭,做為 JavaScript 物件將標頭名稱對應至標頭值。

如果方法在特定類別中沒有任何項目,則系統會省略該部分簽名。

請留意下列特殊例外狀況:

  • 如果方法接受媒體上傳,系統會自動設定 uploadType 參數。
  • 由於 delete 是 JavaScript 中的保留字詞,因此 Google API 中名為 delete 的方法在 Apps Script 中稱為 remove
  • 如果進階服務設為接受 HTTP 要求標頭,且您設定了要求標頭 JavaScript 物件,則還須設定選用的參數 JavaScript 物件 (如果您未使用選用參數,則設為空白物件)。

進階服務支援

進階服務只是精簡的包裝函式,可讓您在 Apps Script 中使用 Google API。因此,使用這類 API 時遇到任何問題,通常是基礎 API 相關問題,而非 Apps Script 本身。

如果您在使用進階服務時遇到問題,應使用基礎 API 的支援操作說明回報。如需這些支援操作說明的連結,請參閱 Apps Script「參考資料」一節的每個進階服務指南。