Google Apps Script API מספק שיטה scripts.run שמפעילה מרחוק פונקציית Apps Script מסוימת. אפשר להשתמש בשיטה הזו באפליקציית התקשרות כדי להריץ מרחוק פונקציה באחד מהפרויקטים של הסקריפט, ולקבל תגובה.
דרישות
כדי שאפליקציית קריאה תוכל להשתמש ב-method scripts.run, אתם צריכים לעמוד בדרישות הבאות. מה צריך לעשות:
פריסה של פרויקט הסקריפט בתור קובץ הפעלה API. אתם יכולים לפרוס, לפרוס ולפרוס מחדש פרויקטים לפי הצורך.
צריך לספק אסימון OAuth עם היקף מתאים להפעלה. אסימון ה-OAuth צריך לכלול את כל ההיקפים שבהם הסקריפט משתמש, ולא רק את אלה שבהם משתמשת הפונקציה שנקראת. אפשר לעיין ברשימה המלאה של היקפי ההרשאות בחומר העזר בנושא השיטה.
מוודאים שהסקריפט ולקוח OAuth2 של אפליקציית הקריאה חולקים עם אותו פרויקט Google Cloud. הפרויקט ב-Cloud צריך להיות פרויקט ב-Cloud רגיל. פרויקטים ברירת מחדל שנוצרו לפרויקטים של Apps Script לא מספיקים. אפשר להשתמש בפרויקט סטנדרטי חדש ב-Cloud או בפרויקט קיים.
מפעילים את Google Apps Script API בפרויקט Cloud.
השיטה scripts.run
כדי להפעיל את השיטה scripts.run נדרשים פרטים מזהים חשובים:
- המזהה של פרויקט הסקריפט.
- שם הפונקציה שצריך לבצע.
- רשימת הפרמטרים שנדרשת לפונקציה (אם יש כזו).
אפשר להגדיר את הסקריפט כך שהוא יופעל במצב פיתוח.
המצב הזה פועל בגרסה השמורה האחרונה של פרויקט הסקריפט, ולא בגרסה האחרונה שנפרסה. כדי לעשות זאת, מגדירים את הערך הבוליאני devMode בגוף הבקשה ל-true. רק הבעלים של הסקריפט יכול להפעיל אותו במצב פיתוח.
טיפול בסוגי נתונים של פרמטרים
כשמשתמשים ב-method scripts.run ב-Apps Script API, בדרך כלל צריך לשלוח נתונים ל-Apps Script כפרמטרים של פונקציה ולקבל את הנתונים בחזרה כערכים של הפונקציה שמחזירים אותם. ה-API יכול לקבל ולהחזיר רק ערכים מהסוגים הבסיסיים: מחרוזות, מערכים, אובייקטים, מספרים ובוליאנים. הסוגים האלה דומים לסוגים הבסיסיים ב-JavaScript. באמצעות ה-API אי אפשר להעביר אובייקטים מורכבים יותר ב-Apps Script, כמו Document או Sheet, לפרויקט הסקריפט או ממנו.
כשאפליקציית הקריאה נכתבת בשפה מאוד חזקה כמו 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 Executable. - בתפריט הנפתח 'למי יש גישה', בוחרים את המשתמשים שרשאים לבצע קריאה לפונקציות של הסקריפט באמצעות Apps Script API.
- לוחצים על פריסה.
שלב 3: הגדרה של אפליקציית הקריאה
כדי שתהיה אפשרות להשתמש ב-API של Apps Script, אפליקציית הקריאה צריכה להגדיר מזהי OAuth. כדי לעשות את זה, צריכה להיות לכם גישה לפרויקט ב-Cloud.
- מגדירים את הפרויקט ב-Cloud שבו משתמשים בסקריפט ובאפליקציית הקריאה. אפשר לעשות זאת לפי השלבים הבאים:
- פותחים את פרויקט הסקריפט ובצד ימין לוחצים על סקירה כללית
. - בקטע היקפי הרשאות של Oauth, מתעדים את כל ההיקפים שהסקריפט מחייב.
בקוד של אפליקציית הקריאה, יוצרים אסימון גישה מסוג OAuth לסקריפט עבור הקריאה ל-API. זה לא אסימון שה-API עצמו משתמש בו, אלא אסימון שהסקריפט דורש בזמן הביצוע. צריך ליצור אותה באמצעות מזהה הלקוח של הפרויקט ב-Cloud והיקפי הסקריפט שתיעדתם.
ספריות הלקוח של Google יכולות לסייע מאוד בפיתוח האסימון הזה ובטיפול ב-OAuth עבור האפליקציה, בדרך כלל הן מאפשרות לך ליצור אובייקט 'פרטי כניסה' ברמה גבוהה יותר באמצעות היקפי הסקריפט. לקבלת דוגמאות לבניית אובייקט של פרטי כניסה מרשימת היקפים, תוכלו להיעזר במדריכים למתחילים של API של Apps Script.
שלב 4: שולחים את בקשת script.run
אחרי שמגדירים את אפליקציית השיחות, אפשר לבצע שיחות scripts.run. כל קריאה ל-API מורכבת מהשלבים הבאים:
- יוצרים בקשת API באמצעות מזהה הסקריפט, שם הפונקציה והפרמטרים הנדרשים.
- מפעילים את הקריאה
scripts.runוכוללים את אסימון OAuth של הסקריפט שיצרתם בכותרת (אם משתמשים בבקשתPOSTבסיסית), או משתמשים באובייקט של פרטי כניסה שיצרתם באמצעות היקפי הסקריפט. - צריך לאפשר לסקריפט לסיים את ההפעלה. זמן הביצוע של סקריפטים יכול להימשך עד שש דקות, ולכן אתם אמורים לקבל זאת באפליקציה.
- בסיום, פונקציית הסקריפט עשויה להחזיר ערך, שה-API מחזיר לאפליקציה אם הערך הוא מסוג נתמך.
בהמשך מופיעות דוגמאות ל-script.run קריאות ל-API.
דוגמאות לבקשות API
הדוגמאות הבאות ממחישות איך ליצור בקשת הפעלה של Apps Script API בשפות שונות, ולקרוא לפונקציה של 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, יומנים, קובצי Drive וכו') לאפליקציה. אפשר להעביר ולהחזיר רק סוגים בסיסיים כמו מחרוזות, מערכים, אובייקטים, מספרים ובוליאנים.
היקפי OAuth. ה-API יכול להפעיל רק סקריפטים שיש להם לפחות היקף נדרש אחד. המשמעות היא שלא ניתן להשתמש ב-API כדי להפעיל סקריפט שלא דורש הרשאה לשירות אחד או יותר.
אין טריגרים.ה-API לא יכול ליצור טריגרים ל-Apps Script.