ב-Google Apps Script API יש שיטה scripts.run
שמריצה מרחוק פונקציית Apps Script ספציפית. אפשר להשתמש בשיטה הזו באפליקציית הקריאה כדי להריץ פונקציה מרחוק באחד מפרויקטי הסקריפטים ולקבל תשובה.
דרישות
כדי שאפליקציית קריאה תוכל להשתמש ב-method scripts.run
, היא צריכה לעמוד בדרישות הבאות. חובה:
פורסים את פרויקט הסקריפט כקובץ הפעלה של API. אפשר לפרוס פרויקטים, לבטל את הפריסה שלהם ולפרוס אותם מחדש לפי הצורך.
יש לספק אסימון OAuth ברמת ההיקף המתאימה לביצוע. אסימון ה-OAuth הזה חייב לכלול את כל ההיקפים שבהם ה-script משתמש, ולא רק את אלה שבהם משתמשת הפונקציה שנקראת. בקישור הבא מופיעה רשימה מלאה של היקפי ההרשאות.
מוודאים שהסקריפט והלקוח של OAuth2 של האפליקציה הקוראת משתפים פרויקט משותף ב-Google Cloud. פרויקט Cloud צריך להיות פרויקט Cloud רגיל. פרויקטים שמוגדרים כברירת מחדל לפרויקטים של Apps Script לא מספיקים. אפשר להשתמש בפרויקט Cloud רגיל חדש או בפרויקט קיים.
מפעילים את Google Apps Script API בפרויקט ב-Cloud.
השיטה scripts.run
כדי להריץ את השיטה scripts.run
, נדרשים פרטי זיהוי של המפתח:
- המזהה של פרויקט הסקריפט.
- שם הפונקציה לביצוע.
- רשימת הפרמטרים שנדרשים לפונקציה (אם יש כאלה).
אפשר גם להגדיר שהסקריפט יפעל במצב פיתוח.
המצב הזה מפעיל את הגרסה שנשמרה לאחרונה של פרויקט הסקריפט, ולא את הגרסה שפורסה לאחרונה. כדי לעשות זאת, מגדירים את הערך true
למשתנה הבווליאני devMode
בגוף הבקשה. רק הבעלים של הסקריפט יכול להריץ אותו במצב פיתוח.
טיפול בסוגי נתונים של פרמטרים
השימוש בשיטה scripts.run
של Apps Script API כולל בדרך כלל שליחת נתונים ל-Apps Script כפרמטרים של פונקציות, וקבלת נתונים בחזרה כערכים שמוחזרים על ידי הפונקציות. ה-API יכול לקבל ולהחזיר רק ערכים מסוגים בסיסיים: מחרוזות, מערכי נתונים, אובייקטים, מספרים ומשתני בוליאני. הם דומים לסוגי הנתונים הבסיסיים ב-JavaScript. לא ניתן להעביר באמצעות ה-API אובייקטים מורכבים יותר של Apps Script, כמו Document או Sheet, אל פרויקט הסקריפט או ממנו.
כשאפליקציית הקריאה נכתבת בשפה עם סוגים מוגדרים (strongly-typed), כמו Java, היא מעבירה את הפרמטרים כרשימה או מערך של אובייקטים כלליים שתואמים לסוגי הבסיס האלה. במקרים רבים, אפשר להחיל המרות מסוג פשוט באופן אוטומטי. לדוגמה, אפשר להעביר לפונקציה שמקבלת פרמטר מספר אובייקט Java מסוג Double
או Integer
או Long
כפרמטר, בלי טיפול נוסף.
כש-API מחזיר את התגובה של הפונקציה, לרוב צריך להמיר את הערך המוחזר לסוג הנכון כדי שניתן יהיה להשתמש בו. ריכזנו כאן כמה דוגמאות ל-Java:
- מספרים שמוחזרים על ידי ה-API לאפליקציית Java מגיעים כאובייקטים מסוג
java.math.BigDecimal
, ויכול להיות שיהיה צורך להמיר אותם לסוגיDoubles
אוint
לפי הצורך. אם הפונקציה ב-Apps Script מחזירה מערך של מחרוזות, אפליקציית Java ממירה את התגובה לאובייקט
List<String>
:List<String> mylist = (List<String>)(op.getResponse().get("result"));
אם רוצים להחזיר מערך של
Bytes
, יכול להיות שיהיה נוח יותר לקודד את המערך כמחרוזת base64 בתוך הפונקציה של Apps Script ולהחזיר את המחרוזת הזו במקום זאת:return Utilities.base64Encode(myByteArray); // returns a String.
דוגמאות הקוד שבהמשך ממחישות דרכים לפרוש את התשובה מה-API.
ההליך הכללי
התהליך הכללי לשימוש ב-Apps Script API כדי להריץ פונקציות של Apps Script מתואר בהמשך:
שלב 1: מגדירים את הפרויקט המשותף ב-Cloud
גם הסקריפט וגם האפליקציה הקוראת צריכים להיות באותו פרויקט ב-Cloud. פרויקט Cloud יכול להיות פרויקט קיים או פרויקט חדש שנוצר למטרה הזו. אחרי שיוצרים פרויקט ב-Cloud, צריך להעביר את פרויקט הסקריפט לשימוש בו.
שלב 2: פורסים את הסקריפט כקובץ הפעלה של API
- פותחים את פרויקט Apps Script עם הפונקציות שבהן רוצים להשתמש.
- בפינה השמאלית העליונה, לוחצים על פריסה > פריסה חדשה.
- בתיבת הדו-שיח שנפתחת, לוחצים על 'הפעלת סוגי פריסה' > קובץ הפעלה של API.
- בתפריט הנפתח 'למי יש גישה', בוחרים את המשתמשים שמותר להם להפעיל את הפונקציות של הסקריפט באמצעות Apps Script API.
- לוחצים על פריסת.
שלב 3: מגדירים את אפליקציית השיחה
כדי שאפשר יהיה להשתמש באפליקציה הקוראת, צריך להפעיל את Apps Script API ולהגדיר פרטי כניסה ל-OAuth. כדי לעשות זאת, צריכה להיות לכם גישה לפרויקט ב-Cloud.
- מגדירים את פרויקט Cloud שבו משתמשים האפליקציה והסקריפט שמבצעים את הקריאה. כדי לעשות זאת, מבצעים את השלבים הבאים:
- פותחים את פרויקט התסריט ובצד ימין לוחצים על סקירה כללית .
- בקטע Project Oauth scopes, מתעדים את כל ההיקפים שנדרשים לסקריפט.
בקוד של האפליקציה הקוראת, יוצרים אסימון גישה מסוג OAuth ל-Script עבור קריאת ה-API. זה לא אסימון שמשמש את ה-API עצמו, אלא אסימון שנדרש לסקריפט בזמן ההפעלה. צריך לבנות אותו באמצעות מזהה הלקוח של פרויקט Cloud וההיקפים של הסקריפט שתועדו.
ספריות הלקוח של Google יכולות לעזור מאוד ביצירת האסימון הזה ובטיפול ב-OAuth באפליקציה. בדרך כלל, במקום זאת אפשר ליצור אובייקט 'פרטי כניסה' ברמה גבוהה יותר באמצעות היקפי הסקריפט. במדריכים למתחילים בנושא Apps Script API מפורטות דוגמאות ליצירת אובייקט פרטי כניסה מרשימת היקפים.
שלב 4: שולחים את הבקשה script.run
אחרי שמגדירים את אפליקציית השיחות, אפשר לבצע שיחות scripts.run
. כל קריאה ל-API מורכבת מהשלבים הבאים:
- יוצרים בקשת API באמצעות מזהה הסקריפט, שם הפונקציה וכל הפרמטרים הנדרשים.
- מריצים את הקריאה
scripts.run
וכוללים את אסימון ה-OAuth של הסקריפט שיצרתם בכותרת (אם משתמשים בבקשה בסיסית מסוגPOST
), או משתמשים באובייקט פרטי הכניסה שיצרתם עם היקפי ההרשאות של הסקריפט. - ממתינים לסיום ההרצה של הסקריפט. זמן הביצוע של סקריפטים יכול להיות עד שש דקות, לכן האפליקציה צריכה לאפשר זאת.
- בסיום, פונקציית הסקריפט עשויה להחזיר ערך, שה-API מעביר בחזרה לאפליקציה אם הערך הוא מסוג נתמך.
בהמשך מפורטות דוגמאות לקריאות ל-API מסוג script.run
.
דוגמאות לבקשות API
בדוגמאות הבאות מוסבר איך שולחים בקשה להפעלת API של Apps Script בשפות שונות, ומפעילים פונקציה של Apps Script כדי להדפיס רשימה של תיקיות בספריית השורש של המשתמש. צריך לציין את מזהה הסקריפט של פרויקט Apps Script שמכיל את הפונקציה שתתבצע, במקום שמצוין ENTER_YOUR_SCRIPT_ID_HERE
. הדוגמאות מתבססות על ספריות הלקוח של Google API בשפות הרלוונטיות.
סקריפט היעד
הפונקציה בסקריפט הזה משתמשת ב-Drive API.
צריך להפעיל את Drive API בפרויקט שבו מתארח הסקריפט.
בנוסף, אפליקציות קריאה חייבות לשלוח פרטי כניסה בפרוטוקול OAuth שכוללים את היקף ההרשאות הבא ב-Drive:
https://www.googleapis.com/auth/drive
בדוגמאות לאפליקציות שבהמשך נעשה שימוש בספריות הלקוח של Google כדי ליצור אובייקטים של פרטי כניסה ל-OAuth באמצעות ההיקף הזה.
/**
* 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()
מגבלות
ל-Apps Script API יש כמה מגבלות:
פרויקט נפוץ ב-Cloud. הסקריפט שאליו מתבצעת הקריאה והאפליקציה שמבצעת את הקריאה חייבים לשתף פרויקט ב-Cloud. הפרויקט ב-Cloud צריך להיות פרויקט Cloud רגיל. פרויקטים שמוגדרים כברירת מחדל לפרויקטים של Apps Script לא מספיקים. הפרויקט הרגיל ב-Cloud יכול להיות פרויקט חדש או פרויקט קיים.
סוגי פרמטרים ותוצאות בסיסיים ה-API לא יכול להעביר או להחזיר לאפליקציה אובייקטים ספציפיים ל-Apps Script (כמו Documents, Blobs, Calendars, Drive Files וכו'). אפשר להעביר ולהחזיר רק ערכים בסיסיים כמו מחרוזות, מערכי נתונים, אובייקטים, מספרים וערכים בוליאניים.
היקפי הרשאות OAuth. ממשק ה-API יכול להריץ רק סקריפטים שיש להם לפחות היקף נדרש אחד. המשמעות היא שאי אפשר להשתמש ב-API כדי לקרוא לסקריפט שלא מחייב הרשאה לשירות אחד או יותר.
ללא טריגרים.ה-API לא יכול ליצור טריגרים של Apps Script.