進階 Google 服務

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

如要查看哪些 Google API 可做為進階服務，請參閱參考資料中的「進階 Google 服務」一節。如果您想使用進階服務不支援的 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》和《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 物件對應參數名稱的 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 的「參考資料」部分，在每項進階服務指南中找到這些支援操作說明的連結。