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 các 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 so với việc sử dụng giao diện HTTP. Về cơ bản, dịch vụ nâng cao là các trình bao bọc mỏng xung quanh các API đó của Google. Chúng hoạt động giống như dịch vụ tích hợp sẵn của Apps Script, chẳng hạn như các dịch vụ này 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 dịch vụ nâng cao trước khi có thể sử dụng dịch vụ đó trong tập lệnh.

Để xem những API Google có sẵn dưới dạng các dịch vụ nâng cao, hãy tìm mục Dịch vụ nâng cao của Google trong Tài liệu tham khảo. Nếu muốn sử dụng một API 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ư mọi API bên ngoài 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 những API này thông qua các dịch vụ nâng cao hoặc đơn giản là tạo các 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à hỗ trợ tính năng tự động hoàn thành. Tuy nhiên, bạn phải bật dịch vụ nâng cao trước khi có thể sử dụng. Ngoài ra, một số dịch vụ nâng cao chỉ cung cấp một tập hợp con chức năng có sẵn trong API.

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

Nhìn chung, việc sử dụng dịch vụ nâng cao là dễ dàng nhất 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

Trước khi 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.
  2. Bạn phải đảm bảo đã bật API tương ứng với dịch vụ nâng cao 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 một 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 được 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 làm như vậy, 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 PlatformAPI của Google.

    Nếu dự án tập lệnh của bạn sử dụng dự án GCP chuẩn hoặc dự án GCP mặc định cũ hơn, bạn phải bật API tương ứng của dịch vụ nâng cao trong dự án GCP theo cách thủ công. 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 các dự án Cloud Platform để biết thêm thông tin.

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:

  1. Mở dự án Apps Script.
  2. Ở bên trái, hãy nhấp vào biểu tượng Trình chỉnh sửa .
  3. Ở bên trái, bên cạnh mục Dịch vụ, 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 dịch vụ nâng cao, dịch vụ này sẽ có sẵn trong tính năng tự động hoàn thành.

Cách xác định chữ ký phương thứ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ắt đầu, nhưng các quy tắc bên dưới 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 các API của Google có thể chấp nhận nhiều loại dữ liệu, bao gồm cả các tham số đường dẫn, các 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ụ lịch nâng cao).

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 đối tượng JavaScript.
  2. Đường dẫn hoặc các thông số bắt buộc dưới dạng đối số riêng lẻ.
  3. Tệp đính kèm tải lên phương tiện, làm đối số Blob.
  4. Tham số không bắt buộc, dưới dạng tên tham số ánh xạ đối tượng JavaScript thành giá trị.
  5. Tiêu đề của yêu cầu HTTP, dưới dạng tên tiêu đề ánh xạ đối tượng JavaScript thành giá trị tiêu đề.

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

Có một số ngoại lệ đặc biệt cần lưu ý:

  • Đối với các phương thức chấp nhận tải lên nội dung phương tiện, thông số uploadType sẽ được đặt tự động.
  • Các phương thức có tên delete trong API Google có 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 các tiêu đề của yêu cầu HTTP, cũng như thiết lập một đối tượng JavaScript của tiêu đề yêu cầu, thì bạn cũng phải đặt đối tượng JavaScript của các tham số tuỳ chọn (thành đối tượng trống nếu bạn không sử dụng các tham số tuỳ chọn).

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

Dịch vụ nâng cao chỉ là các trình bao bọc mỏng cho phép sử dụng các API Google trong Apps Script. Do đó, mọi vấn đề gặp phải khi sử dụng 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 sự cố khi sử dụng dịch vụ nâng cao, bạn nên báo cáo sự cố đó bằng cách sử dụng hướng dẫn hỗ trợ dành cho API cơ bản. Các đường liên kết đến các hướng dẫn hỗ trợ này được cung cấp trong từng hướng dẫn dịch vụ nâng cao trong phần Tài liệu tham khảo về Apps Script.