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 API Apps Script, đồng thời ứng dụng gọi phải dùng chung 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 mục 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 đúng phạm vi cần đưa vào mã xác thực, hãy mở trang Overview (Tổng quan) của dự án tập lệnh rồi di chuyển xuống phần "Project OAuth Scopes" (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 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/{scriptId}:run
URL sử dụng cú pháp Chuyển mã gRPC.
Tham số đường dẫn
Các tham số | |
---|---|
scriptId |
Mã 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 phần "Mã nhận dạng". |
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 |
Tên của hàm cần thực thi trong tập lệnh đã cho. Tên không chứa dấu ngoặc đơn hoặc tham số. Hàm này có thể tham chiếu đến một hàm trong thư viện đi kèm, chẳng hạn như |
parameters[] |
Các tham số sẽ được truyền đến hàm đang được thực thi. Loại đối tượng cho mỗi tham số phải khớp với loại đối tượng 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ư |
sessionState |
Không dùng nữa. Chỉ để sử dụng với tiện ích bổ sung Android. Mã nhận dạng đại diện cho phiên hoạt động 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ó sẵn dưới dạng dữ liệu bổ sung trong Ý định để chạy tiện ích bổ sung. Khi chạy ở trạng thái phiên, tiện ích bổ sung Android sẽ có các đặc quyền của tập lệnh ràng buộc – tức là tiện ích này có thể truy cập vào 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 |
devMode |
Nếu |
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:
Hình minh hoạ 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 không đến cho đến khi hàm hoàn tất quá trình thực thi. Thời gian thực thi tối đa được liệt kê trong Hướng dẫn về hạn mức Apps Script.
Sau khi quá trình thực thi bắt đầu, có thể có một trong 4 kết quả:
- Nếu hàm tập lệnh trả về thành công, trường
response
sẽ chứa đối tượngExecutionResponse
có giá trị trả về của hàm trong trườngresult
của đối tượng. - Nếu hàm tập lệnh (hoặc chính Apps Script) trả về một ngoại lệ, thì trường
error
sẽ chứa đối tượngStatus
. Trườngdetails
của đối tượngStatus
chứa một mảng có một đối tượngExecutionError
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
, đồng thời cả trườngresponse
và trườngerror
đều không xuất hiện. - 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ột 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 |
Các trường | |
---|---|
done |
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ó trường |
Trường nhóm result . Kết quả toán tử, có thể là error hoặc response hợp lệ. Nếu done == false , thì cả error và response đều không được đặt. Nếu done == true , bạn có thể đặt chính xác một trong số 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 trạng thái sau đây: |
|
error |
Nếu lệnh gọi |
response |
Nếu hàm tập lệnh trả về thành công, trường này chứa đối tượng Đối tượng chứa các trường thuộc kiểu tuỳ ý. Trường bổ sung |
Phạm vi uỷ quyền
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) trả về 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 |
Mã trạng thái. Đối với API này, giá trị này:
|
message |
Một 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 dành cho người dùng đều được bản địa hoá và gửi trong trường |
details[] |
Một mảng chứa một đối tượng Đối tượng chứa các trường thuộc kiểu tuỳ ý. Trường bổ sung |