Method: scripts.run

Chạy một hàm trong dự án Apps Script. Dự án tập lệnh phải được triển khai để sử dụng với API Apps Script và ứng dụng gọi phải chia sẻ cùng một dự án Cloud Platform.

Phương thức này yêu cầu uỷ quyền bằng mã thông báo OAuth 2.0 bao gồm ít nhất một trong các phạm vi được liệt kê trong phần Uỷ quyền; không thể thực thi các dự án tập lệnh không yêu cầu uỷ quyền qua API này. Để tìm phạm vi chính xác cần đưa vào mã thông báo xác thực, hãy mở trang Tổng quan về dự án tập lệnh rồi di chuyển xuống "Project OAuth Scopes."

Lỗi 403, PERMISSION_DENIED: The caller does not have permission cho biết dự án Cloud Platform được dùng để uỷ quyền yêu cầu này không giống với dự án mà tập lệnh sử dụng.

Yêu cầu HTTP

POST https://script.googleapis.com/v1/scripts/{scriptId}:run

URL sử dụng cú pháp Chuyển mã gRPC.

Tham số đường dẫn

Các tham số
scriptId

string

Mã tập lệnh của tập lệnh sẽ được thực thi. Tìm mã tập lệnh trên trang Cài đặt dự án trong "IDs."

Nội dung yêu cầu

Nội dung yêu cầu chứa dữ liệu có cấu trúc sau:

Biểu diễn dưới dạng JSON
{
  "function": string,
  "parameters": [
    value
  ],
  "sessionState": string,
  "devMode": boolean
}
Các trường
function

string

Tên của hàm thực thi trong tập lệnh đã cho. Tên không bao gồm dấu ngoặc đơn hoặc thông số. Tệp này có thể tham chiếu một hàm trong thư viện đi kèm như Library.libFunction1.

parameters[]

value (Value format)

Các tham số cần truyền đến hàm đang được thực thi. Loại đối tượng cho mỗi thông số phải khớp với loại dự kiến trong Apps Script. Tham số không được là loại đối tượng dành riêng cho Apps Script (chẳng hạn như Document hoặc Calendar); chúng chỉ có thể là các loại đối tượng gốc như string, number, array, object hoặc boolean. Không bắt buộc.

sessionState

string

Không dùng nữa. Chỉ dùng được với các tiện ích bổ sung dành cho Android. Mã nhận dạng đại diện cho phiên hiện tại của người dùng trong ứng dụng Android dành cho Google Tài liệu hoặc Trang tính, được thêm vào dưới dạng dữ liệu bổ sung trong Ý định khởi chạy tiện ích bổ sung. Khi một tiện ích bổ sung Android được chạy với trạng thái phiên, tiện ích bổ sung đó sẽ có được đặc quyền của tập lệnh giới hạn. Tức là tiện ích bổ sung này có thể truy cập vào các thông tin như vị trí con trỏ hiện tại của người dùng (trong Tài liệu) hoặc ô đã chọn (trong Trang tính). Để truy xuất trạng thái, hãy gọi Intent.getStringExtra("com.google.android.apps.docs.addons.SessionState"). Không bắt buộc.

devMode

boolean

Nếu true và người dùng là chủ sở hữu tập lệnh, thì tập lệnh sẽ chạy ở phiên bản đã lưu gần đây nhất chứ không phải phiên bản được triển khai để sử dụng với API Apps Script. Không bắt buộc; giá trị mặc định là false.

Nội dung phản hồi

Nếu thành công, phần nội dung phản hồi sẽ chứa dữ liệu có cấu trúc sau:

Biểu thị một lượt thực thi hàm Apps Script đã bắt đầu bằng run. Phản hồi thực thi sẽ không xuất hiện cho đến khi hàm thực thi xong. Thời gian chạy thực thi tối đa được liệt kê trong hướng dẫn về hạn mức Apps Script.

Sau khi bắt đầu thực thi, ứng dụng có thể nhận được một trong bốn kết quả sau:

  • Nếu hàm tập lệnh trả về thành công, trường response chứa một đối tượng ExecutionResponse có giá trị trả về của hàm trong trường result của đối tượng.
  • Nếu hàm tập lệnh (hoặc chính Apps Script) gửi ngoại lệ, thì trường error sẽ chứa đối tượng Status. Trường details của đối tượng Status chứa một mảng có một đối tượng ExecutionError duy nhất cung cấp thông tin về bản chất của lỗi.
  • Nếu quá trình thực thi chưa hoàn tất, trường done sẽ là false và cả trường response lẫn trường error đều không có mặt.
  • Nếu lệnh gọi run không thành công (ví dụ: do yêu cầu không đúng hoặc lỗi uỷ quyền), phương thức này sẽ trả về mã phản hồi HTTP trong phạm vi 4XX với định dạng khác cho nội dung phản hồi. Thư viện ứng dụng tự động chuyển đổi phản hồi 4XX thành lớp ngoại lệ.

Biểu diễn dưới dạng JSON
{
  "done": boolean,

  // Union field result can be only one of the following:
  "error": {
    object (Status)
  },
  "response": {
    "@type": string,
    field1: ...,
    ...
  }
  // End of list of possible types for union field result.
}
Các trường
done

boolean

Trường này cho biết liệu quá trình thực thi tập lệnh đã hoàn tất hay chưa. Quá trình thực thi đã hoàn tất có một trường response được điền sẵn chứa ExecutionResponse từ hàm đã được thực thi.

Trường liên kết result. Kết quả hoạt động, có thể là error hoặc response hợp lệ. Nếu done == false, cả errorresponse đều không được đặt. Nếu done == true, bạn có thể đặt chính xác một trong hai error hoặc response. Một số dịch vụ có thể không cung cấp kết quả. result chỉ có thể là một trong những giá trị sau:
error

object (Status)

Nếu lệnh gọi run thành công nhưng hàm tập lệnh (hoặc chính Apps Script) gửi một ngoại lệ, thì trường này chứa một đối tượng Status. Trường details của đối tượng Status chứa một mảng có một đối tượng ExecutionError duy nhất cung cấp thông tin về bản chất của lỗi.

response

object

Nếu hàm tập lệnh trả về thành công, trường này chứa một đối tượng ExecutionResponse có giá trị trả về của hàm.

Đối tượng chứa các trường thuộc loại tùy ý. Một trường khác "@type" chứa URI xác định loại. Ví dụ: { "id": 1234, "@type": "types.example.com/standard/id" }.

Phạm vi cấp phép

Yêu cầu một trong các phạm vi OAuth sau:

  • https://apps-apis.google.com/a/feeds
  • https://apps-apis.google.com/a/feeds/alias/
  • https://apps-apis.google.com/a/feeds/groups/
  • https://mail.google.com/
  • https://sites.google.com/feeds
  • https://www.google.com/calendar/feeds
  • https://www.google.com/m8/feeds
  • https://www.googleapis.com/auth/admin.directory.group
  • https://www.googleapis.com/auth/admin.directory.user
  • https://www.googleapis.com/auth/documents
  • https://www.googleapis.com/auth/documents.currentonly
  • https://www.googleapis.com/auth/drive
  • https://www.googleapis.com/auth/dynamiccreatives
  • https://www.googleapis.com/auth/forms
  • https://www.googleapis.com/auth/forms.currentonly
  • https://www.googleapis.com/auth/groups
  • https://www.googleapis.com/auth/script.cpanel
  • https://www.googleapis.com/auth/script.external_request
  • https://www.googleapis.com/auth/script.scriptapp
  • https://www.googleapis.com/auth/script.send_mail
  • https://www.googleapis.com/auth/script.storage
  • https://www.googleapis.com/auth/script.webapp.deploy
  • https://www.googleapis.com/auth/spreadsheets
  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/sqlservice
  • https://www.googleapis.com/auth/userinfo.email

Để biết thêm thông tin, hãy xem Tổng quan về OAuth 2.0.

Trạng thái

Nếu lệnh gọi run thành công nhưng hàm tập lệnh (hoặc chính Apps Script) gửi một ngoại lệ, thì trường error của nội dung phản hồi sẽ chứa đối tượng Status này.

Biểu diễn dưới dạng JSON
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
Các trường
code

integer

Mã trạng thái. Đối với API này, giá trị này sẽ:

  • 10, biểu thị lỗi SCRIPT_TIMEOUT,
  • 3, chỉ ra lỗi INVALID_ARGUMENT, hoặc
  • 1, cho biết quá trình thực thi CANCELLED.

message

string

Thông báo lỗi mà nhà phát triển gặp phải, bằng tiếng Anh. Mọi thông báo lỗi mà người dùng nhìn thấy đều được bản địa hoá và gửi trong trường details, hoặc được ứng dụng bản địa hoá.

details[]

object

Một mảng chứa một đối tượng ExecutionError duy nhất cung cấp thông tin về bản chất của lỗi.

Đối tượng chứa các trường thuộc loại tùy ý. Một trường khác "@type" chứa URI xác định loại. Ví dụ: { "id": 1234, "@type": "types.example.com/standard/id" }.