進階 Google 服務

Apps Script 的進階服務可讓您連線至特定公開 Google API，設定程序比使用 HTTP 介面更簡便。進階服務是這些 Google API 的精簡包裝函式。這類服務的運作方式與 Apps Script 的內建服務非常相似，例如提供自動完成功能，且 Apps Script 會自動處理授權流程。不過，您必須先啟用進階服務，才能在指令碼中使用。

啟用進階服務

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

步驟 1：啟用進階服務

您可以使用 Apps Script 編輯器或編輯資訊清單，啟用進階服務。

方法 A：使用編輯器

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

方法 B：使用資訊清單

如要啟用進階服務，請編輯資訊清單檔案。舉例來說，如要啟用 Google 雲端硬碟進階服務，請將 enabledAdvancedServices 欄位新增至 dependencies 物件：

{
  "timeZone": "America/Denver",
  "dependencies": {
    "enabledAdvancedServices": [
      {
        "userSymbol": "Drive",
        "version": "v3",
        "serviceId": "drive"
      }
    ]
  },
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8"
}

啟用進階服務後，系統就會在自動完成功能中提供該服務。

步驟 2：啟用 Google Cloud API (僅限標準 Google Cloud 專案)

如果您使用的是預設 Google Cloud 專案 (由 Apps Script 自動建立)，可以略過這個步驟。在步驟 1 中新增服務時，系統會自動啟用 API。

如果您使用標準 Google Cloud 專案，還必須手動啟用進階服務對應的 API。如要手動啟用 API，請按照下列步驟操作：

1. 在 **Google Cloud 控制台**中，開啟與指令碼相關聯的 Cloud 專案。

2. 在控制台頂端，點選搜尋列並輸入部分 API 名稱 (例如「Calendar」)，然後點選顯示的名稱。

3. 點按「啟用 API」。

4. 關閉 Google Cloud 控制台，然後返回指令碼編輯器。

方法簽章的判斷方式

一般來說，進階服務會使用與對應公開 API 相同的物件、方法名稱和參數，但方法簽章會經過翻譯，以便在 Apps Script 中使用。指令碼編輯器的自動完成功能通常會提供足夠的資訊，協助您開始使用，但下列規則說明瞭 Apps Script 如何從公開的 Google API 產生方法簽章。

對 Google API 的要求可接受各種不同類型的資料，包括路徑參數、查詢參數、要求主體或媒體上傳附件。部分進階服務也可以接受特定 HTTP 要求標頭 (例如日曆進階服務)。

Google Apps Script 中的對應方法簽章具有下列引數：

1. 要求主體 (通常是資源)，以 JavaScript 物件的形式表示。
2. 路徑或必要參數，以個別引數的形式。如果方法需要多個路徑參數，這些參數會按照 API 端點網址中列出的順序顯示。
3. 媒體上傳附件，做為 Blob 引數。
4. 選用參數 (通常是查詢參數)，以 JavaScript 物件形式將參數名稱對應至值。
5. HTTP 要求標頭，以 JavaScript 物件形式將標頭名稱對應至標頭值。

如果方法在特定類別中沒有任何項目，系統就會省略簽章的該部分。

請注意以下特殊例外情況：

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

例如：Calendar.Events.insert

假設您想建立日曆活動。Google Calendar API 說明文件會顯示對應的 HTTP 要求結構：

• HTTP 動詞：POST
• 要求網址： https://www.googleapis.com/calendar/v3/calendars/{calendarId}/events

• 要求主體：Event 資源。

• 查詢參數：sendUpdates、supportsAttachments 等。

在 Apps Script 中，方法簽章是透過重新排序這些輸入內容來決定：

1. Body：活動資源 (JavaScript 物件)。
2. 路徑：calendarId (字串)。
3. 選用參數：查詢參數 (JavaScript 物件)。

產生的方法呼叫如下所示：

const event = {
  summary: 'Lunch',
  location: 'Deli',
  start: {
    dateTime: '2026-01-01T12:00:00-05:00'
  },
  end: {
    dateTime: '2026-01-01T13:00:00-05:00'
  }
};
const calendarId = 'primary';
const optionalArgs = {
  sendUpdates: 'all'
};

Calendar.Events.insert(event, calendarId, optionalArgs);

進階服務或 HTTP？

每個進階 Google 服務都與公開的 Google API 相關聯。在 Apps Script 中，您可以使用進階服務存取這些 API，也可以使用 UrlFetch 直接發出 API 要求。

如果您使用進階服務方法，Apps Script 會處理授權流程，並提供自動完成支援。不過，您必須先啟用進階服務，才能使用這項功能。

如果您使用 UrlFetch 方法直接存取 API，基本上就是將 Google API 視為外部 API。透過此方法，您可以使用 API 的所有功能。不過，您必須處理 API 授權。

下表比較這兩種方法：

程式碼比較

程式碼範例會顯示使用進階服務建立日曆事件，與使用 UrlFetchApp 建立日曆事件的複雜程度差異。

進階服務：

const event = {
  summary: 'Lunch',
  location: 'Deli',
  start: { dateTime: '2026-01-01T12:00:00-05:00' },
  end: { dateTime: '2026-01-01T13:00:00-05:00' }
};

const optionalArgs = {
  sendUpdates: 'all'
};

Calendar.Events.insert(event, 'primary', optionalArgs);

UrlFetch (HTTP)：

const event = {
  summary: 'Lunch',
  location: 'Deli',
  start: { dateTime: '2026-01-01T12:00:00-05:00' },
  end: { dateTime: '2026-01-01T13:00:00-05:00' }
};
const url = 'https://www.googleapis.com/calendar/v3/calendars/primary/events?sendUpdates=all';
const options = {
  method: 'post',
  contentType: 'application/json',
  headers: {
    Authorization: `Bearer ${ScriptApp.getOAuthToken()}`
  },
  payload: JSON.stringify(event)
};

UrlFetchApp.fetch(url, options);

建議您盡可能使用進階服務，只有在進階服務無法使用或無法提供所需功能時，才使用 UrlFetch 方法。

支援進階服務

由於進階服務是 Google API 的精簡包裝函式，因此使用進階服務時遇到的任何問題，通常都是基礎 API 的問題，而非 Apps Script 的問題。

如果在使用進階服務時遇到問題，請按照基礎 API 的支援說明回報問題。