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à những 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 tương tự như các dịch vụ tích hợp sẵn của Apps Script, chẳng hạn như 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. Bật dịch vụ nâng cao trước khi dùng dịch vụ đó trong một tập lệnh.

Bật các 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 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 1: 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. 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ẽ xuất hiện trong tính năng tự động hoàn thành.

Bước 2: Bật Google Cloud API (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 mặc định trên Google Cloud (do Apps Script tự động tạo), hãy bỏ qua bước này. API này sẽ tự động bật khi bạn thêm dịch vụ ở Bước 1.

Nếu sử dụng 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 được 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 và 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 các đố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. Chức năng 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 Google API công khai.

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 cả 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 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 một đối tượng JavaScript.
Đường dẫn hoặc cá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 nội dung nghe nhìn tải lên, dưới dạng đối số Blob.
Các tham số không bắt buộc (thường là tham số truy vấn), dưới dạng một đối tượng JavaScript ánh xạ tên tham số với các giá trị.
Tiêu đề yêu cầu HTTP, dưới dạng một đối tượng JavaScript ánh xạ tên tiêu đề với các 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 những phương thức chấp nhận nội dung nghe nhìn tải lên, tham số uploadType sẽ được đặt tự động.
Các phương thức có tên delete trong Google API được đặt tên là remove trong Apps Script, vì delete là một từ dành riêng trong JavaScript.
Nếu bạn định cấu hình một dịch vụ nâng cao để 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 các tham số không bắt buộc).

Ví dụ: Calendar.Events.insert

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

Tài liệu về API 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: Một tài nguyên Event.
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 đầu vào sau:

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 các dịch vụ nâng cao hoặc bằng cách đưa ra yêu cầu API trực tiếp bằng UrlFetch.

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

Nếu sử dụng phương thức UrlFetch để truy cập trực tiếp vào API, về cơ bản, bạn sẽ coi API Google là một API bên ngoài. Với phương thức này, hãy sử dụng mọi 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 pháp này:

Tính năng	Dịch vụ nâng cao	UrlFetch (HTTP)
Uỷ quyền	Được xử lý tự động	Phải xử lý theo cách thủ công
Tự động hoàn thành	Còn hàng	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 (cần tạo tiêu đề và phân tích cú pháp các 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 theo cách thủ công phạm vi OAuth bắt buộc trong tệp kê khai của tập lệnh.

Hãy sử dụng 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ó sẵn hoặc không cung cấp chức năng bạn cần.

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

Vì các dịch vụ nâng cao là các trình bao bọc mỏng xung quanh 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 đề đó theo 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.