API Google Apps Script cung cấp phương thức scripts.run giúp thực thi từ xa một hàm Apps Script được chỉ định. Bạn có thể dùng phương thức này trong ứng dụng gọi để chạy từ xa một hàm thuộc một trong các dự án tập lệnh của mình và nhận phản hồi.
Yêu cầu
Bạn phải đáp ứng các yêu cầu sau đây thì ứng dụng gọi mới có thể sử dụng phương thức scripts.run. Bạn phải:
Triển khai dự án tập lệnh ở dạng API có thể thực thi. Bạn có thể triển khai, huỷ triển khai và triển khai lại các dự án nếu cần.
Cung cấp mã thông báo OAuth trong phạm vi phù hợp để thực thi. Mã thông báo OAuth này phải bao gồm tất cả phạm vi mà tập lệnh sử dụng, chứ không chỉ những phạm vi mà hàm được gọi sử dụng. Xem danh sách đầy đủ các phạm vi uỷ quyền trong tài liệu tham khảo phương thức.
Đảm bảo rằng tập lệnh và ứng dụng OAuth2 của ứng dụng gọi dùng chung một dự án Google Cloud. Dự án Cloud phải là một dự án Cloud chuẩn; các dự án mặc định được tạo cho dự án Apps Script là không đủ. Bạn có thể sử dụng dự án Cloud chuẩn mới hoặc dự án hiện có.
Bật API Google Apps Script trong dự án trên Google Cloud.
Phương thức scripts.run
Phương thức scripts.run yêu cầu thông tin nhận dạng chính để chạy:
- Mã của dự án tập lệnh.
- Tên hàm cần thực thi.
- Danh sách tham số mà hàm yêu cầu (nếu có).
Bạn có thể tuỳ ý định cấu hình để tập lệnh thực thi ở chế độ phát triển.
Chế độ này thực thi bằng phiên bản đã lưu gần đây nhất của dự án tập lệnh thay vì phiên bản được triển khai gần đây nhất. Bạn có thể thực hiện việc này bằng cách đặt boolean devMode trong nội dung yêu cầu thành true. Chỉ chủ sở hữu của tập lệnh mới có thể thực thi tập lệnh đó ở chế độ phát triển.
Xử lý các loại dữ liệu thông số
Sử dụng phương thức scripts.run của API Apps Script thường bao gồm việc gửi dữ liệu đến Apps Script dưới dạng tham số hàm và lấy lại dữ liệu dưới dạng giá trị trả về của hàm. API chỉ có thể nhận và trả về các giá trị thuộc các kiểu cơ bản như chuỗi, mảng, đối tượng, số và boolean. Các kiểu này tương tự như các kiểu cơ bản trong JavaScript. API không thể chuyển các đối tượng Apps Script phức tạp hơn như Document (Tài liệu) hoặc Sheet (Trang tính) vào hoặc từ dự án tập lệnh.
Khi ứng dụng gọi được viết bằng ngôn ngữ loại mạnh như Java, ứng dụng đó sẽ truyền tham số dưới dạng danh sách hoặc mảng các đối tượng chung tương ứng với các loại cơ bản này. Trong nhiều trường hợp, bạn có thể tự động áp dụng
các lượt chuyển đổi loại đơn giản. Ví dụ: một hàm nhận tham số số có thể được cấp một đối tượng Double, Integer hoặc Long của Java làm tham số mà không cần xử lý thêm.
Khi API trả về phản hồi hàm, thông thường, bạn cần truyền giá trị được trả về về đúng loại trước khi có thể sử dụng. Dưới đây là một số ví dụ dựa trên Java:
- Các số được API trả về cho ứng dụng Java sẽ xuất hiện dưới dạng đối tượng
java.math.BigDecimalvà có thể cần được chuyển đổi thành loạiDoubleshoặcintnếu cần. Nếu hàm Apps Script trả về một mảng chuỗi, thì ứng dụng Java sẽ truyền phản hồi đó vào một đối tượng
List<String>:List<String> mylist = (List<String>)(op.getResponse().get("result"));Nếu muốn trả về một mảng
Bytes, bạn nên mã hoá mảng đó dưới dạng Chuỗi base64 trong hàm Apps Script và trả về Chuỗi đó:return Utilities.base64Encode(myByteArray); // returns a String.
Mã mẫu dưới đây minh hoạ các cách diễn giải phản hồi của API.
Quy trình chung
Phần sau đây mô tả quy trình chung khi sử dụng API Apps Script để thực thi các hàm của Apps Script:
Bước 1: Thiết lập dự án Google Cloud dùng chung
Cả tập lệnh và ứng dụng gọi đều cần chia sẻ cùng một dự án Google Cloud. Dự án trên đám mây này có thể là một dự án hiện có hoặc một dự án mới được tạo cho mục đích này. Sau khi có một dự án Cloud, bạn phải chuyển đổi dự án tập lệnh của mình để sử dụng dự án đó.
Bước 2: Triển khai tập lệnh dưới dạng API có thể thực thi
- Mở dự án Apps Script có các hàm bạn muốn dùng.
- Ở trên cùng bên phải, hãy nhấp vào Triển khai > Triển khai mới.
- Trong hộp thoại mở ra, hãy nhấp vào Enabled (Bật) các loại triển khai
> API Executable (API có thể thực thi). - Trong trình đơn thả xuống "Người có quyền truy cập", hãy chọn người dùng được phép gọi các hàm của tập lệnh bằng API Apps Script.
- Nhấp vào Triển khai.
Bước 3: Định cấu hình ứng dụng gọi
Ứng dụng gọi phải bật API Apps Script và thiết lập khả năng đăng ký OAuth trước khi có thể sử dụng. Bạn phải có quyền truy cập vào dự án trên Cloud để thực hiện việc này.
- Định cấu hình dự án trên đám mây mà tập lệnh và ứng dụng gọi của bạn đang sử dụng. Bạn có thể thực hiện việc này theo các bước sau:
- Mở dự án tập lệnh và ở bên trái, hãy nhấp vào biểu tượng Tổng quan
. - Trong phần Phạm vi OAuth của dự án, hãy ghi lại tất cả các phạm vi mà tập lệnh yêu cầu.
Trong mã xử lý ứng dụng gọi, hãy tạo một mã truy cập OAuth của tập lệnh cho lệnh gọi API. Đây không phải là mã thông báo mà API tự sử dụng mà là mã mà tập lệnh yêu cầu khi thực thi. Bạn phải tạo mã này bằng mã ứng dụng khách của dự án trên Cloud và phạm vi tập lệnh mà bạn đã ghi lại.
Thư viện ứng dụng của Google có thể hỗ trợ đáng kể trong việc tạo mã thông báo này và xử lý OAuth cho ứng dụng. Thay vào đó, bạn thường cho phép tạo đối tượng "thông tin xác thực" cấp cao hơn bằng phạm vi tập lệnh. Xem phần Bắt đầu nhanh API Apps Script để tham khảo ví dụ về cách tạo đối tượng thông tin xác thực từ danh sách phạm vi.
Bước 4: Đưa ra yêu cầu script.run
Sau khi định cấu hình ứng dụng gọi, bạn có thể thực hiện các lệnh gọi scripts.run. Mỗi lệnh gọi API bao gồm các bước sau:
- Tạo yêu cầu API bằng mã tập lệnh, tên hàm và mọi tham số bắt buộc.
- Thực hiện lệnh gọi
scripts.runvà bao gồm mã thông báo OAuth của tập lệnh mà bạn đã tạo trong tiêu đề (nếu sử dụng yêu cầuPOSTcơ bản), hoặc sử dụng đối tượng thông tin xác thực mà bạn đã tạo bằng phạm vi tập lệnh. - Cho phép tập lệnh hoàn tất việc thực thi. Các tập lệnh được phép mất đến 6 phút trong thời gian thực thi, vì vậy, ứng dụng của bạn nên cho phép điều này.
- Sau khi hoàn tất, hàm của tập lệnh có thể trả về một giá trị. API này sẽ phân phối lại ứng dụng nếu giá trị đó là loại được hỗ trợ.
Bạn có thể xem ví dụ về lệnh gọi API script.run trong phần dưới đây.
Ví dụ về yêu cầu API
Các ví dụ sau cho thấy cách tạo yêu cầu thực thi API Apps Script bằng nhiều ngôn ngữ, gọi một hàm Apps Script để in danh sách các thư mục trong thư mục gốc của người dùng. Bạn phải chỉ định mã tập lệnh của dự án Apps Script chứa hàm được thực thi tại vị trí được chỉ định bằng ENTER_YOUR_SCRIPT_ID_HERE. Các ví dụ này dựa trên Thư viện ứng dụng API của Google cho các ngôn ngữ tương ứng.
Tập lệnh mục tiêu
Hàm trong tập lệnh này sử dụng API Drive.
Bạn phải bật API Drive trong dự án lưu trữ tập lệnh.
Ngoài ra, ứng dụng gọi phải gửi thông tin xác thực OAuth, bao gồm các phạm vi sau đây trên Drive:
https://www.googleapis.com/auth/drive
Các ứng dụng mẫu ở đây sử dụng thư viện ứng dụng của Google để tạo đối tượng thông tin xác thực cho OAuth bằng phạm vi này.
/**
* Return the set of folder names contained in the user's root folder as an
* object (with folder IDs as keys).
* @return {Object} A set of folder names keyed by folder ID.
*/
function getFoldersUnderRoot() {
const root = DriveApp.getRootFolder();
const folders = root.getFolders();
const folderSet = {};
while (folders.hasNext()) {
const folder = folders.next();
folderSet[folder.getId()] = folder.getName();
}
return folderSet;
}
Java
/**
* Create a HttpRequestInitializer from the given one, except set
* the HTTP read timeout to be longer than the default (to allow
* called scripts time to execute).
*
* @param {HttpRequestInitializer} requestInitializer the initializer
* to copy and adjust; typically a Credential object.
* @return an initializer with an extended read timeout.
*/
private static HttpRequestInitializer setHttpTimeout(
final HttpRequestInitializer requestInitializer) {
return new HttpRequestInitializer() {
@Override
public void initialize(HttpRequest httpRequest) throws IOException {
requestInitializer.initialize(httpRequest);
// This allows the API to call (and avoid timing out on)
// functions that take up to 6 minutes to complete (the maximum
// allowed script run time), plus a little overhead.
httpRequest.setReadTimeout(380000);
}
};
}
/**
* Build and return an authorized Script client service.
*
* @param {Credential} credential an authorized Credential object
* @return an authorized Script client service
*/
public static Script getScriptService() throws IOException {
Credential credential = authorize();
return new Script.Builder(
HTTP_TRANSPORT, JSON_FACTORY, setHttpTimeout(credential))
.setApplicationName(APPLICATION_NAME)
.build();
}
/**
* Interpret an error response returned by the API and return a String
* summary.
*
* @param {Operation} op the Operation returning an error response
* @return summary of error response, or null if Operation returned no
* error
*/
public static String getScriptError(Operation op) {
if (op.getError() == null) {
return null;
}
// Extract the first (and only) set of error details and cast as a Map.
// The values of this map are the script's 'errorMessage' and
// 'errorType', and an array of stack trace elements (which also need to
// be cast as Maps).
Map<String, Object> detail = op.getError().getDetails().get(0);
List<Map<String, Object>> stacktrace =
(List<Map<String, Object>>) detail.get("scriptStackTraceElements");
java.lang.StringBuilder sb =
new StringBuilder("\nScript error message: ");
sb.append(detail.get("errorMessage"));
sb.append("\nScript error type: ");
sb.append(detail.get("errorType"));
if (stacktrace != null) {
// There may not be a stacktrace if the script didn't start
// executing.
sb.append("\nScript error stacktrace:");
for (Map<String, Object> elem : stacktrace) {
sb.append("\n ");
sb.append(elem.get("function"));
sb.append(":");
sb.append(elem.get("lineNumber"));
}
}
sb.append("\n");
return sb.toString();
}
public static void main(String[] args) throws IOException {
// ID of the script to call. Acquire this from the Apps Script editor,
// under Publish > Deploy as API executable.
String scriptId = "ENTER_YOUR_SCRIPT_ID_HERE";
Script service = getScriptService();
// Create an execution request object.
ExecutionRequest request = new ExecutionRequest()
.setFunction("getFoldersUnderRoot");
try {
// Make the API request.
Operation op =
service.scripts().run(scriptId, request).execute();
// Print results of request.
if (op.getError() != null) {
// The API executed, but the script returned an error.
System.out.println(getScriptError(op));
} else {
// The result provided by the API needs to be cast into
// the correct type, based upon what types the Apps
// Script function returns. Here, the function returns
// an Apps Script Object with String keys and values,
// so must be cast into a Java Map (folderSet).
Map<String, String> folderSet =
(Map<String, String>) (op.getResponse().get("result"));
if (folderSet.size() == 0) {
System.out.println("No folders returned!");
} else {
System.out.println("Folders under your root folder:");
for (String id : folderSet.keySet()) {
System.out.printf(
"\t%s (%s)\n", folderSet.get(id), id);
}
}
}
} catch (GoogleJsonResponseException e) {
// The API encountered a problem before the script was called.
e.printStackTrace(System.out);
}
}
JavaScript
/**
* Load the API and make an API call. Display the results on the screen.
*/
function callScriptFunction() {
const scriptId = '<ENTER_YOUR_SCRIPT_ID_HERE>';
// Call the Apps Script API run method
// 'scriptId' is the URL parameter that states what script to run
// 'resource' describes the run request body (with the function name
// to execute)
try {
gapi.client.script.scripts.run({
'scriptId': scriptId,
'resource': {
'function': 'getFoldersUnderRoot',
},
}).then(function(resp) {
const result = resp.result;
if (result.error && result.error.status) {
// The API encountered a problem before the script
// started executing.
appendPre('Error calling API:');
appendPre(JSON.stringify(result, null, 2));
} else if (result.error) {
// The API executed, but the script returned an error.
// Extract the first (and only) set of error details.
// The values of this object are the script's 'errorMessage' and
// 'errorType', and an array of stack trace elements.
const error = result.error.details[0];
appendPre('Script error message: ' + error.errorMessage);
if (error.scriptStackTraceElements) {
// There may not be a stacktrace if the script didn't start
// executing.
appendPre('Script error stacktrace:');
for (let i = 0; i < error.scriptStackTraceElements.length; i++) {
const trace = error.scriptStackTraceElements[i];
appendPre('\t' + trace.function + ':' + trace.lineNumber);
}
}
} else {
// The structure of the result will depend upon what the Apps
// Script function returns. Here, the function returns an Apps
// Script Object with String keys and values, and so the result
// is treated as a JavaScript object (folderSet).
const folderSet = result.response.result;
if (Object.keys(folderSet).length == 0) {
appendPre('No folders returned!');
} else {
appendPre('Folders under your root folder:');
Object.keys(folderSet).forEach(function(id) {
appendPre('\t' + folderSet[id] + ' (' + id + ')');
});
}
}
});
} catch (err) {
document.getElementById('content').innerText = err.message;
return;
}
}
Node.js
/**
* Call an Apps Script function to list the folders in the user's root Drive
* folder.
*
*/
async function callAppsScript() {
const scriptId = '1xGOh6wCm7hlIVSVPKm0y_dL-YqetspS5DEVmMzaxd_6AAvI-_u8DSgBT';
const {GoogleAuth} = require('google-auth-library');
const {google} = require('googleapis');
// Get credentials and build service
// TODO (developer) - Use appropriate auth mechanism for your app
const auth = new GoogleAuth({
scopes: 'https://www.googleapis.com/auth/drive',
});
const script = google.script({version: 'v1', auth});
try {
// Make the API request. The request object is included here as 'resource'.
const resp = await script.scripts.run({
auth: auth,
resource: {
function: 'getFoldersUnderRoot',
},
scriptId: scriptId,
});
if (resp.error) {
// The API executed, but the script returned an error.
// Extract the first (and only) set of error details. The values of this
// object are the script's 'errorMessage' and 'errorType', and an array
// of stack trace elements.
const error = resp.error.details[0];
console.log('Script error message: ' + error.errorMessage);
console.log('Script error stacktrace:');
if (error.scriptStackTraceElements) {
// There may not be a stacktrace if the script didn't start executing.
for (let i = 0; i < error.scriptStackTraceElements.length; i++) {
const trace = error.scriptStackTraceElements[i];
console.log('\t%s: %s', trace.function, trace.lineNumber);
}
}
} else {
// The structure of the result will depend upon what the Apps Script
// function returns. Here, the function returns an Apps Script Object
// with String keys and values, and so the result is treated as a
// Node.js object (folderSet).
const folderSet = resp.response.result;
if (Object.keys(folderSet).length == 0) {
console.log('No folders returned!');
} else {
console.log('Folders under your root folder:');
Object.keys(folderSet).forEach(function(id) {
console.log('\t%s (%s)', folderSet[id], id);
});
}
}
} catch (err) {
// TODO(developer) - Handle error
throw err;
}
}
Python
import google.auth
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError
def main():
"""Runs the sample."""
# pylint: disable=maybe-no-member
script_id = "1VFBDoJFy6yb9z7-luOwRv3fCmeNOzILPnR4QVmR0bGJ7gQ3QMPpCW-yt"
creds, _ = google.auth.default()
service = build("script", "v1", credentials=creds)
# Create an execution request object.
request = {"function": "getFoldersUnderRoot"}
try:
# Make the API request.
response = service.scripts().run(scriptId=script_id, body=request).execute()
if "error" in response:
# The API executed, but the script returned an error.
# Extract the first (and only) set of error details. The values of
# this object are the script's 'errorMessage' and 'errorType', and
# a list of stack trace elements.
error = response["error"]["details"][0]
print(f"Script error message: {0}.{format(error['errorMessage'])}")
if "scriptStackTraceElements" in error:
# There may not be a stacktrace if the script didn't start
# executing.
print("Script error stacktrace:")
for trace in error["scriptStackTraceElements"]:
print(f"\t{0}: {1}.{format(trace['function'], trace['lineNumber'])}")
else:
# The structure of the result depends upon what the Apps Script
# function returns. Here, the function returns an Apps Script
# Object with String keys and values, and so the result is
# treated as a Python dictionary (folder_set).
folder_set = response["response"].get("result", {})
if not folder_set:
print("No folders returned!")
else:
print("Folders under your root folder:")
for folder_id, folder in folder_set.items():
print(f"\t{0} ({1}).{format(folder, folder_id)}")
except HttpError as error:
# The API encountered a problem before the script started executing.
print(f"An error occurred: {error}")
print(error.content)
if __name__ == "__main__":
main()
Các điểm hạn chế
API Apps Script có một số hạn chế:
Một dự án Google Cloud phổ biến. Tập lệnh đang được gọi và ứng dụng gọi phải chia sẻ một dự án trên đám mây. Dự án Cloud phải là một dự án Cloud chuẩn; các dự án mặc định được tạo cho dự án Apps Script là không đủ. Dự án Cloud chuẩn có thể là một dự án mới hoặc một dự án hiện có.
Các kiểu dữ liệu trả về và tham số cơ bản. API không thể truyền hoặc trả về các đối tượng dành riêng cho Apps Script (chẳng hạn như Tài liệu, Blob, Lịch, Tệp trên Drive, v.v.) cho ứng dụng. Bạn chỉ có thể truyền và trả về các kiểu cơ bản như chuỗi, mảng, đối tượng, số và boolean.
Các phạm vi của OAuth. API chỉ có thể thực thi các tập lệnh có ít nhất một phạm vi bắt buộc. Điều này có nghĩa là bạn không thể sử dụng API để gọi tập lệnh không yêu cầu uỷ quyền của một hoặc nhiều dịch vụ.
Không có điều kiện kích hoạt.API không thể tạo điều kiện kích hoạt cho Apps Script.