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

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

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

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 Google API công khai. 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 trực tiếp thực hiện các yêu cầu API 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à ưu đãi 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 trước khi bạn có thể sử dụng nó. Ngoài ra, một số dịch vụ nâng cao chỉ cung cấp một số có sẵn trong API.

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

Nhìn chung, cách dễ nhất là sử dụng một dịch vụ nâng cao khi 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 dịch vụ nâng cao, bạn phải đáp ứng các yêu cầu sau các yêu cầu:

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

  2. Bạn phải đảm bảo rằng bạn đã 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 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 được bật tự động sau khi bạn bật dịch vụ nâng cao và lưu dự án tập lệnh. Nếu bạn chưa làm như vậy, bạn cũng có thể đã yêu cầu đồng ý với Google Cloud và Điều khoản dịch vụ API 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 một 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 dự án GCP để thực hiện thay đổi nà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 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 biểu tượng 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ẽ có trong tính năng tự động hoàn thành.

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

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ố dưới dạng API công khai tương ứng, mặc dù chữ ký phương thức được dịch cho sử dụng trong Apps Script. Thông tin của trình chỉnh sửa tập lệnh hàm tự động hoàn thành thường cung cấp đủ thông tin để bắt đầu, nhưng các quy tắc bên dưới sẽ giải thích cách Apps Script tạo chữ ký phương thức qua một API công khai của Google.

Yêu cầu gửi tới Google API có thể chấp nhận nhiều loại dữ liệu, bao gồm các tham số đường dẫn, tham số truy vấn, nội dung yêu cầu và/hoặc phương tiện tải tệp đính kèm lên. Một số dịch vụ nâng cao cũng có thể chấp nhận yêu cầu HTTP cụ thể đầu trang (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 đặc điểm sau đối số:

  1. Nội dung yêu cầu (thường là tài nguyên), dưới dạng đối tượng JavaScript.
  2. Đường dẫn hoặc tham số bắt buộc, dưới dạng đối số riêng lẻ.
  3. Tệp đính kèm để tải nội dung nghe nhìn lên, dưới dạng Blob đối số.
  4. Tham số không bắt buộc, dưới dạng tên tham số ánh xạ đối tượng JavaScript đến giá trị.
  5. Tiêu đề của yêu cầu HTTP dưới dạng đối tượng JavaScript ánh xạ tên tiêu đề đến tiêu đề giá trị.

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ý 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 việc tải nội dung nghe nhìn lên, tham số uploadType đượ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 một dịch vụ nâng cao được định cấu hình để chấp nhận tiêu đề của yêu cầu HTTP, và bạn đặt đối tượng JavaScript cho tiêu đề yêu cầu, thì bạn cũng phải đặt thuộc tính đối tượng JavaScript tham số (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à các trình bao bọc mỏng cho phép sử dụng API trong Apps Script. Do đó, bất kỳ sự cố nào gặp phải khi sử dụng chúng thường là sự cố với API cơ bản chứ không phải với chính Apps Script.

Nếu bạn gặp sự cố khi sử dụng dịch vụ nâng cao, được báo cáo bằng cách sử dụng hướng dẫn hỗ trợ cho API cơ bản. Liên kết đến các hướng dẫn hỗ trợ khác có trong mỗi hướng dẫn dịch vụ nâng cao trong Phần Tài liệu tham khảo về Apps Script.