進階 Google 服務

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

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

如要查看哪些 Google API 是進階服務,請參閱參考資料中的「進階 Google 服務」一節。如果你想使用進階 API 時,無法以進階服務的形式存取,那麼就像使用其他外部 API 一樣。

進階服務或 HTTP?

每個進階 Google 服務都與公開的 Google API 相關聯。 在 Apps Script 中,您可以透過進階服務存取這些 API,也可以直接使用 UrlFetch 發出 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 PlatformGoogle API 服務條款的相關條款,

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

詳情請參閱 Cloud Platform 專案

啟用進階服務

如要使用進階 Google 服務,請按照下列指示操作:

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

啟用進階服務後,即可使用自動完成功能。

如何判定方法簽章

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

向 Google API 發出的要求可接受多種不同類型的資料,包括路徑參數、查詢參數、要求主體和/或媒體上傳附件。部分進階服務也可以接受特定 HTTP 要求標頭 (例如 Calendar Advanced 服務)。

Google Apps Script 中的對應方法簽章如下:

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

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

請特別留意以下幾個特殊例外狀況:

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

進階服務支援

進階服務只是精簡的包裝函式,可讓您在 Apps Script 中使用 Google API。因此,使用該應用程式時遭遇問題通常是基礎 API 的問題,而不是 Apps Script 本身。

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