Các dịch vụ nâng cao của Google

Các dịch vụ nâng cao trong Google Apps Script cho phép bạn kết nối với một số API công khai của Google mà không cần thiết lập nhiều như khi sử dụng giao diện HTTP của các API đó. Các dịch vụ nâng cao là trình bao bọc mỏng xung quanh các API của Google. Các dịch vụ này hoạt động giống như các dịch vụ tích hợp của Apps Script. Ví dụ: các dịch vụ này cung cấp tính năng tự động hoàn thành và Apps Script tự động xử lý quy trình uỷ quyền. Hãy bật một dịch vụ nâng cao trước khi sử dụng dịch vụ đó trong một tập lệnh.

Bật dịch vụ nâng cao

Để sử dụng một dịch vụ nâng cao của Google, hãy làm theo các hướng dẫn sau:

Bước 1: Bật dịch vụ nâng cao

Bật một dịch vụ nâng cao bằng trình chỉnh sửa tập lệnh Apps Script hoặc bằng cách chỉnh sửa tệp kê khai.

Cách A: Sử dụng Trình chỉnh sửa

Mở dự án Apps Script.
Ở bên trái, hãy nhấp vào Trình chỉnh sửa .
Ở bên trái, bên cạnh Dịch vụ, hãy nhấp vào Thêm dịch vụ .
Chọn một dịch vụ nâng cao của Google rồi nhấp vào Thêm.

Cách B: Sử dụng tệp kê khai

Bật các dịch vụ nâng cao bằng cách chỉnh sửa tệp kê khai manifest file. Ví dụ: để bật dịch vụ nâng cao của Google Drive, hãy thêm trường enabledAdvancedServices vào đối tượng dependencies:

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

Sau khi bạn bật một dịch vụ nâng cao, dịch vụ đó sẽ có trong tính năng tự động hoàn thành.

Bước 2: Bật API Google Cloud (Chỉ dành cho các dự án trên đám mây Google Cloud tiêu chuẩn)

Nếu bạn đang sử dụng một dự án trên đám mây mặc định của Google (do Apps Script tự động tạo), hãy bỏ qua bước này. API sẽ tự động được bật khi bạn thêm dịch vụ ở Bước 1.

Nếu bạn đang sử dụng một dự án trên đám mây Google Cloud tiêu chuẩn, hãy bật API tương ứng với dịch vụ nâng cao theo cách thủ công. Cách bật API theo cách thủ công:

Mở dự án trên đám mây liên kết với tập lệnh của bạn trong ** Google Cloud Console**
Ở đầu bảng điều khiển, hãy nhấp vào thanh tìm kiếm rồi nhập một phần tên của API (ví dụ: "Lịch"), sau đó nhấp vào tên đó khi bạn thấy.
Nhấp vào Bật API.
Đóng bảng điều khiển Cloud của Google rồi quay lại trình chỉnh sửa tập lệnh.

Cách xác định chữ ký phương thức

Các dịch vụ nâng cao thường sử dụng cùng một đối tượng, tên phương thức và tham số như các API công khai tương ứng, mặc dù chữ ký phương thức được dịch để sử dụng trong Apps Script. Hàm tự động hoàn thành của trình chỉnh sửa tập lệnh thường cung cấp đủ thông tin để bạn bắt đầu. Các quy tắc sau đây giải thích cách Apps Script tạo chữ ký phương thức từ một API công khai của Google.

Các yêu cầu gửi đến API của Google có thể chấp nhận nhiều loại dữ liệu, bao gồm tham số đường dẫn, tham số truy vấn, nội dung yêu cầu hoặc tệp đính kèm tải lên nội dung nghe nhìn. Một số dịch vụ nâng cao cũng có thể chấp nhận các tiêu đề yêu cầu HTTP cụ thể (ví dụ: dịch vụ nâng cao của Lịch).

Chữ ký phương thức tương ứng trong Apps Script có các đối số sau:

Nội dung yêu cầu (thường là một tài nguyên), dưới dạng đối tượng JavaScript.
Tham số đường dẫn hoặc tham số bắt buộc, dưới dạng các đối số riêng lẻ. Nếu phương thức yêu cầu nhiều tham số đường dẫn, thì các tham số đó sẽ xuất hiện theo thứ tự được liệt kê trong URL điểm cuối API.
Tệp đính kèm tải lên nội dung nghe nhìn, dưới dạng Blob đối số.
Tham số không bắt buộc (thường là tham số truy vấn), dưới dạng đối tượng JavaScript ánh xạ tên tham số đến giá trị.
Tiêu đề yêu cầu HTTP, dưới dạng đối tượng JavaScript ánh xạ tên tiêu đề đến giá trị tiêu đề.

Nếu phương thức không có mục nào trong một danh mục nhất định, thì phần đó của chữ ký sẽ bị bỏ qua.

Hãy lưu ý những trường hợp ngoại lệ sau:

Đối với các phương thức chấp nhận tải lên nội dung nghe nhìn, tham số uploadType sẽ được đặt tự động.
Các phương thức có tên delete trong API của Google được đặt tên là remove trong Apps Script, vì delete là một từ dành riêng trong JavaScript.
Nếu một dịch vụ nâng cao được định cấu hình để chấp nhận tiêu đề yêu cầu HTTP và bạn đặt một đối tượng JavaScript tiêu đề yêu cầu, thì bạn cũng phải đặt đối tượng JavaScript tham số không bắt buộc (thành một đối tượng trống nếu bạn không sử dụng tham số không bắt buộc).

Ví dụ: Calendar.Events.insert

Cách tạo một sự kiện trên Lịch:

Tài liệu về API của Lịch Google cho thấy cấu trúc yêu cầu HTTP tương ứng:

Động từ HTTP: POST
URL yêu cầu: https://www.googleapis.com/calendar/v3/calendars/{calendarId}/events
Nội dung yêu cầu: Tài nguyên Sự kiện.
Tham số truy vấn: sendUpdates, supportsAttachments, v.v.

Trong Apps Script, chữ ký phương thức được xác định bằng cách sắp xếp lại các dữ liệu đầu vào này:

Nội dung: Tài nguyên sự kiện (đối tượng JavaScript).
Đường dẫn: calendarId (chuỗi).
Tham số không bắt buộc: Tham số truy vấn (đối tượng JavaScript).

Lệnh gọi phương thức thu được sẽ có dạng như sau:

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);

Dịch vụ nâng cao hay HTTP?

Mỗi dịch vụ nâng cao của Google đều được liên kết với một API công khai của Google. Trong Apps Script, hãy truy cập vào các API này bằng cách sử dụng dịch vụ nâng cao hoặc bằng cách trực tiếp đưa ra yêu cầu API bằng UrlFetch.

Nếu bạn sử dụng phương thức dịch vụ nâng cao, thì Apps Script sẽ xử lý quy trình uỷ quyền và hỗ trợ tính năng tự động hoàn thành. Hãy bật dịch vụ nâng cao trước khi sử dụng dịch vụ đó.

Nếu bạn sử dụng phương thức UrlFetch để truy cập trực tiếp vào API, thì về cơ bản, bạn sẽ coi API của Google là một API bên ngoài. Với phương thức này, hãy sử dụng tất cả các khía cạnh của API. Tuy nhiên, bạn phải xử lý việc uỷ quyền API.

Bảng sau đây so sánh hai phương thức:

Tính năng	Dịch vụ nâng cao	UrlFetch (HTTP)
Uỷ quyền	Tự động xử lý	Phải xử lý theo cách thủ công
Tự động hoàn thành	Có sẵn	Không có
Phạm vi chức năng	Có thể là một tập hợp con của API	Có toàn quyền sử dụng tất cả các tính năng của API
Độ phức tạp	Dễ hơn	Phức tạp hơn (yêu cầu xây dựng tiêu đề và phân tích cú pháp phản hồi)

So sánh mã

Các mẫu mã cho thấy sự khác biệt về độ phức tạp giữa việc tạo một sự kiện trên Lịch bằng dịch vụ nâng cao so với việc sử dụng UrlFetchApp.

Dịch vụ nâng cao:

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);

Đối với phương thức UrlFetchApp, hãy chỉ định các phạm vi OAuth bắt buộc theo cách thủ công trong tệp kê khai của tập lệnh.

Hãy sử dụng một dịch vụ nâng cao bất cứ khi nào có thể và chỉ sử dụng phương thức UrlFetch khi dịch vụ nâng cao không có hoặc không cung cấp chức năng bạn cần.

Hỗ trợ cho các dịch vụ nâng cao

Vì các dịch vụ nâng cao là trình bao bọc mỏng xung quanh các API của Google, nên mọi vấn đề gặp phải khi sử dụng các dịch vụ này thường là vấn đề với API cơ bản chứ không phải với Apps Script.

Nếu bạn gặp vấn đề khi sử dụng một dịch vụ nâng cao, hãy báo cáo vấn đề đó bằng hướng dẫn hỗ trợ cho API cơ bản.

Các dịch vụ nâng cao của Google Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.