Method: scripts.run

Chạy một hàm trong dự án Apps Script. Bạn phải triển khai dự án tập lệnh để sử dụng với Apps Script API và ứng dụng gọi phải dùng chung 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 có chứa í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 thông qua API này. Để tìm các 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 của dự án tập lệnh rồi di chuyển xuống phần "Phạm vi OAuth của dự án".

Lỗi 403, PERMISSION_DENIED: The caller does not have permission cho biết dự án Cloud Platform dùng để uỷ quyền cho yêu cầu 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/{deploymentId}:run

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

Tham số đường dẫn

Thông số
deploymentId

string

Mã hoạt động triển khai cho hoạt động triển khai API có thể thực thi. Tìm mã nhận dạng triển khai trong phần Triển khai > Quản lý việc triển khai trong trình chỉnh sửa tập lệnh.

Nội dung yêu cầu

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

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

string

Tên của hàm cần thực thi trong tập lệnh đã cho. Tên không có dấu ngoặc đơn hoặc tham số. Bạn có thể tham chiếu một hàm trong thư viện đi kèm, chẳng hạn như Library.libFunction1.
parameters[]

value (Value format)

Các tham số sẽ được truyền đến hàm đang thực thi. Loại đối tượng cho mỗi tham số phải khớp với loại dự kiến trong Apps Script. Các tham số không thể là các 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 nguyên thuỷ 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 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 Google Tài liệu hoặc Trang tính dành cho Android, được đưa vào dưới dạng dữ liệu bổ sung trong Intent khởi chạy tiện ích bổ sung. Khi chạy một tiện ích bổ sung Android ở trạng thái phiên, tiện ích đó sẽ có được các đặc quyền của một tập lệnh được liên kết, tức là có thể truy cập vào thông tin như vị trí hiện tại của con trỏ (trong Tài liệu) hoặc ô được chọn (trong Trang tính) của người dùng. Để 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 của tập lệnh, thì tập lệnh sẽ chạy ở phiên bản đã lưu gần đây nhất thay vì phiên bản được triển khai để sử dụng với API Apps Script. Không bắt buộc; 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:

Một biểu thị về quá trình thực thi một 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 hoàn tất quá trình thực thi. Thời gian chạy tối đa được liệt kê trong hướng dẫn về hạn mức của Apps Script.

Sau khi bắt đầu thực thi, quá trình này có thể 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 sẽ 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) tạo ra một ngoại lệ, thì trường error sẽ 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.
  • Nếu quá trình thực thi chưa hoàn tất, trường done sẽ là false và không có trường response cũng như error.
  • Nếu chính lệnh gọi run không thành công (ví dụ: do yêu cầu không đúng định dạng hoặc lỗi uỷ quyền), phương thức này sẽ trả về mã phản hồi HTTP trong dải 4XX với một định dạng khác cho nội dung phản hồi. Thư viện ứng dụng sẽ tự động chuyển đổi phản hồi 4XX thành một 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.
}
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. Một quá trình thực thi đã hoàn tất có trường response được điền sẵn chứa ExecutionResponse từ hàm đã thực thi.
Trường nhóm result. Kết quả của thao tác, có thể là error hoặc response hợp lệ. Nếu done == false, thì error và response đều không được thiết lập. Nếu done == true, bạn chỉ có thể thiết lập một trong hai tham số error hoặc response. Có thể một số dịch vụ sẽ không cung cấp kết quả. result chỉ có thể là một trong những trạng thái sau:
error

object (Status)

Nếu một lệnh gọi run thành công nhưng hàm tập lệnh (hoặc chính Apps Script) gặp một ngoại lệ, thì trường này sẽ 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 sẽ chứa một đối tượng ExecutionResponse có giá trị trả về của hàm.

Một đối tượng chứa các trường thuộc một loại tuỳ ý. Một trường bổ sung "@type" chứa một 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 bài viết 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 trường hợp 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: ...,
      ...
    }
  ]
}
Trường
code

integer

Mã trạng thái. Đối với API này, giá trị này có thể là:

  • 10, cho biết lỗi SCRIPT_TIMEOUT,
  • 3, cho biết 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 dành cho nhà phát triển, bằng tiếng Anh. Mọi thông báo lỗi mà người dùng thấy đều được bản địa hoá và gửi trong trường details hoặc được ứng dụng khách 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.

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