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

Các dịch vụ nâng cao trong Apps Script cho phép nhà phát triển có kinh nghiệm 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 đó. Về cơ bản, 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 (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). Tuy nhiên, bạn phải bật một dịch vụ nâng cao thì mới có thể sử dụng dịch vụ đó trong tập lệnh.

Để biết những API nào của Google có sẵn dưới dạng dịch vụ nâng cao, hãy tìm mục Dịch vụ nâng cao của Google trong phần Tài liệu tham khảo. Nếu muốn sử dụng một API của Google không có sẵn dưới dạng dịch vụ nâng cao, bạn chỉ cần kết nối với API đó như bất kỳ API bên ngoài nào khác.

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, bạn có thể truy cập vào các API này thông qua các dịch vụ nâng cao hoặc chỉ cần đưa ra yêu cầu API trực tiếp bằng cách sử dụ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. Tuy nhiên, bạn phải bật dịch vụ nâng cao thì mới có thể sử dụng dịch vụ này. Ngoài ra, một số dịch vụ nâng cao chỉ cung cấp một phần chức năng có trong API.

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 đang coi API Google là một API bên ngoài. Với phương thức này, bạn có thể sử dụng mọi khía cạnh của API. Tuy nhiên, bạn phải tự xử lý việc uỷ quyền API. Bạn cũng phải tạo mọi tiêu đề cần thiết và phân tích cú pháp các phản hồi API.

Nhìn chung, cách dễ nhất là sử dụng một dịch vụ nâng cao nếu có thể và chỉ sử dụng phương thức UrlFetch khi dịch vụ nâng cao không cung cấp chức năng bạn cần.

Yêu cầu

Để có thể sử dụng một dịch vụ nâng cao, bạn phải đáp ứng các yêu cầu sau:

  1. Bạn phải bật dịch vụ nâng cao trong dự án tập lệnh của mình.

  2. Bạn phải đảm bảo rằng API tương ứng với dịch vụ nâng cao đã được bật trong dự án Cloud Platform (GCP) mà tập lệnh của bạn sử dụng.

    Nếu dự án tập lệnh của bạn sử dụng dự án GCP mặc định được tạo vào hoặc sau ngày 8 tháng 4 năm 2019, thì API sẽ tự động bật sau khi bạn bật dịch vụ nâng cao và lưu dự án tập lệnh. Nếu chưa thực hiện, bạn cũng có thể được yêu cầu đồng ý với Điều khoản dịch vụ của Google Cloud và Google API.

    Nếu dự án tập lệnh của bạn sử dụng dự án GCP tiêu chuẩn hoặc dự án GCP mặc định cũ, thì bạn phải bật API tương ứng của dịch vụ nâng cao theo cách thủ công trong dự án GCP. Bạn phải có quyền chỉnh sửa đối với dự án GCP để thực hiện thay đổi này.

Hãy xem phần Dự án Cloud Platform để biết thêm thông tin.

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:

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

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.

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. Hàm tự động hoàn thành của trình chỉnh tập tập lệnh thường cung cấp đủ thông tin để bạn bắt đầu. Tuy nhiên, các quy tắc dưới đâ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 đối với API của Google có thể chấp nhận nhiều loại dữ liệu khác nhau, bao gồm cả tham số đường dẫn, tham số truy vấn, nội dung yêu cầu và/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 Google Apps Script có các đối số sau:

  1. 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.
  2. Đường dẫn hoặc các tham số bắt buộc, dưới dạng các đối số riêng lẻ.
  3. Tệp đính kèm nội dung nghe nhìn tải lên, dưới dạng đối số Blob.
  4. Các tham số không bắt buộc, dưới dạng một đối tượng JavaScript ánh xạ tên tham số với các giá trị.
  5. 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.

Bạn cần lưu ý một số trường hợp ngoại lệ đặc biệt:

  • Đố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ê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).

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

Dịch vụ nâng cao chỉ là những trình bao bọc mỏng cho phép sử dụng API của Google trong Apps Script. Do đó, mọi vấn đề gặp phải khi sử dụng các API này thường là vấn đề với API cơ bản, chứ không phải với chính Apps Script.

Nếu gặp vấn đề khi sử dụng một dịch vụ nâng cao, bạn nên báo cáo vấn đề đó theo hướng dẫn hỗ trợ cho API cơ bản. Đường liên kết đến các hướng dẫn hỗ trợ này có trong mỗi hướng dẫn về dịch vụ nâng cao trong phần Tài liệu tham khảo của Apps Script.