ה-Google Apps Script API מספק שיטת scripts.run שמבצעת הפעלה מרחוק של פונקציית Apps Script מסוימת. תוכלו להשתמש בשיטה הזו באפליקציית התקשרות כדי להריץ פונקציה באחד מהפרויקטים שלכם בסקריפט מרחוק ולקבל תגובה.
הדרישות
עליכם לעמוד בדרישות הבאות כדי שאפליקציית שיחות תוכל להשתמש בשיטה scripts.run. חובה:
פריסה של פרויקט הסקריפט כקובץ הפעלה של ממשק API. ניתן לפרוס, לפרוס ולפרוס מחדש פרויקטים לפי הצורך.
יש לספק אסימון OAuth בהיקף מתאים לביצוע. אסימון OAuth זה חייב לכלול את כל ההיקפים המשמשים את הסקריפט, ולא רק את אלה המשמשים את הפונקציה הנקראת. תוכלו להיעזר ברשימה המלאה של היקפי ההרשאות בחומר העזר בנושא השיטה.
ודא שהסקריפט ולקוח OAuth2של יישום ההתקשרות חולקים פרויקט Google Cloud משותף. הפרויקט ב-Cloud צריך להיות פרויקט Cloud רגיל, אבל פרויקטים המוגדרים כברירת מחדל שנוצרו בפרויקטים של Apps Script לא מספיקים. אתם יכולים להשתמש בפרויקט רגיל חדש בענן או בפרויקט קיים.
מפעילים את Google Apps Script API בפרויקט ב-Cloud.
השיטה scripts.run
השיטה scripts.run
מחייבת פרטים מזהים עיקריים כדי להריץ:
- את המזהה של פרויקט הסקריפט.
- שם הפונקציה לביצוע.
- רשימת הפרמטרים שהפונקציה דורשת (אם יש כאלה).
אפשר גם להגדיר את הסקריפט להפעלה במצב פיתוח.
מצב זה פועל עם הגרסה השמורה האחרונה של פרויקט הסקריפט, במקום עם הגרסה האחרונה שפרסה. לשם כך, יש להגדיר את הערך devModeבוליאני בגוף הבקשה
true. רק הבעלים של הסקריפט יכול להפעיל אותו במצב פיתוח.
טיפול בסוגי הנתונים של הפרמטרים
השימוש ב-Apps Script API
scripts.run
בדרך כלל כולל שליחת נתונים ל-Apps Script כפרמטרים של פונקציות, והחזרת נתונים כערכי החזרת פונקציה. אפשר לקבל ולהחזיר את ה-API רק עם סוגים בסיסיים: מחרוזות, מערכים, אובייקטים, מספרים ובוליאנים. הם דומים לסוגים הבסיסיים ב-JavaScript. לא ניתן להעביר אובייקטים מורכבים יותר של Apps Script, כמו מסמך או גיליון, לפרויקט ה-API או לפרויקט הזה.
כשאפליקציית הקריאה כתובה בשפה עם הקלדה חזקה כמו Java, היא עוברת בפרמטרים כרשימה או כמערך של אובייקטים כלליים שתואמים לסוגים הבסיסיים האלה. במקרים רבים תוכלו להחיל המרות פשוטות מסוג פשוט. לדוגמה, פונקציה שלוקחת פרמטר של מספר יכולה לקבל אובייקט Double או Integer Long של Java כפרמטר, ללא טיפול נוסף.
כשה-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.
- מגדירים את הפרויקט בענן שבו משתמשת אפליקציית ההתקשרות והסקריפט. ניתן לעשות זאת באמצעות השלבים הבאים:
- פותחים את פרויקט הסקריפט ולוחצים על סקירה כללית
. - בקטע Project Oauth scopes, מתעדים את כל היקפי ההרשאות שהסקריפט דורש.
בקוד של האפליקציה לשיחות, יוצרים אסימון גישה מסוג OAuth לקריאת ה-API. זה לא אסימון ש-API עצמו משתמש בו, אלא אסימון שהסקריפט דורש בעת ההפעלה. יש ליצור אותו באמצעות מזהה הלקוח של הפרויקט בענן וההיקפים של הסקריפטים שהקלטת.
ספריות הלקוח של Google יכולות לסייע מאוד בבניית האסימון והטיפול ב-OAuth עבור האפליקציה, שלרוב מאפשרות לך לבנות במקום זאת אובייקט ברמה גבוהה יותר של "פרטי כניסה" באמצעות היקפי הסקריפט. בקטע טיפים למתחילים ב-Apps Script API ניתן למצוא דוגמאות לבניית אובייקט של פרטי כניסה מתוך רשימה של היקפים.
שלב 4: שולחים בקשת script.run
אחרי שמגדירים את אפליקציית השיחות, אפשר להתקשר למספר scripts.run. כל קריאה ל-API מורכבת מהשלבים הבאים:
- יוצרים בקשת API באמצעות מזהה הסקריפט, שם הפונקציה והפרמטרים הנדרשים.
- כדאי לבצע את הקריאה ל-
scripts.runולכלול את אסימון ה-OAuth של הסקריפט שיצרתם בכותרת (אם אתם משתמשים בבקשתPOSTבסיסית), או להשתמש באובייקט של פרטי כניסה שיצרתם להיקפי ההרשאות של הסקריפט. - יש לאפשר לסקריפט לסיים את הביצוע. סקריפטים יכולים להימשך עד שש דקות בזמן ביצוע, כך שהאפליקציה אמורה לאפשר זאת.
- בסיום, פונקציית הסקריפט עשויה להחזיר ערך, שה-API מספק בחזרה לאפליקציה אם הערך הוא סוג נתמך.
דוגמאות לקריאות ל-API מסוג script.run מפורטות בהמשך.
דוגמאות לבקשות API
הדוגמאות הבאות מראות איך לשלוח בקשת הפעלה של Apps Script API בשפות שונות. הקריאה לפונקציה של Apps Script היא להדפיס רשימה של תיקיות בספריית הבסיס של המשתמש. את מזהה הסקריפט של פרויקט Apps Script שמכיל את הפונקציה המופעלת, יש לציין במקום שמצוין באמצעות ENTER_YOUR_SCRIPT_ID_HERE. הדוגמאות מבוססות על ספריות הלקוח של Google API בשפות הרלוונטיות להן.
סקריפט יעד
הפונקציה בסקריפט הזה משתמשת ב-Drive API.
צריך להפעיל את ממשק ה-API של Drive בפרויקט המארח את הסקריפט.
בנוסף, אפליקציות לשיחות צריכות לשלוח פרטי כניסה ב-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
from __future__ import print_function
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}."
f"{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 (למשל מסמכים, Blobs, יומנים, <br class="ph-0">49<ph-0-3"> אפשר להעביר ולהחזיר רק סוגים בסיסיים, כמו מחרוזות, מערכים, אובייקטים, מספרים ובוליאנים.
היקפי ההרשאות של OAuth. אפשר להריץ ב-API רק סקריפטים עם היקף נדרש אחד לפחות. כלומר, לא ניתן להשתמש ב-API כדי לקרוא לסקריפט שלא דורש הרשאה לשירות אחד או יותר.
אין טריגרים.ל-API אין אפשרות ליצור טריגרים של Apps Script.