דף זה תורגם על ידי Cloud Translation API.

הפעלת פונקציות באמצעות Apps Script API

Google Apps Script API מספק אמצעי תשלום scripts.run שמפעיל מרחוק פונקציית Apps Script מסוימת. אפשר להשתמש בשיטה הזו באפליקציה של קריאה כדי להריץ פונקציה באחד מהפרויקטים של הסקריפטים שלכם מרחוק ולקבל תשובה.

דרישות

כדי להשתמש באפליקציה לשיחות, צריך לעמוד בדרישות הבאות scripts.run . חובה:

פורסים את פרויקט הסקריפט כקובץ הפעלה של API. אפשר לפרוס, לבטל פריסה ולפרוס מחדש פרויקטים לפי הצורך.
צריך לספק אסימון OAuth בהיקף תקין להפעלה. אסימון ה-OAuth הזה צריך לכסות את כל היקפי ההרשאות ששימשו את הסקריפט, לא רק את אלה ששימשה את הפונקציה שנקראה. לצפייה הרשימה המלאה של היקפי ההרשאות בהפניה ל-method.
ודא שהסקריפט והאפליקציה ששולחת קריאה באמצעות OAuth2 לקוח משותף בפרויקט Google Cloud משותף. הפרויקט ב-Cloud חייב להיות פרויקט סטנדרטי ב-Cloud. פרויקטי ברירת מחדל שנוצרו לפרויקטים של Apps Script אינם מספיקים. אפשר להשתמש בפרויקט חדש רגיל ב-Cloud או בפרויקט קיים.
הפעלת Google Apps Script API בפרויקט בענן.

השיטה `scripts.run`

scripts.run צריך להזין פרטים מזהים עיקריים כדי להריץ את הפקודה:

אפשר להגדיר שהסקריפט יופעל במצב פיתוח. המצב הזה פועל באמצעות הגרסה האחרונה ששמורה של פרויקט הסקריפט ולא בגרסה האחרונה שנפרסה. כדי לעשות את זה, ערך בוליאני של devMode במטבע גוף הבקשה אל true. רק הבעלים של הסקריפט יכול להפעיל אותו במצב פיתוח.

טיפול בסוגי נתונים של פרמטרים

שימוש ב-Apps Script API אמצעי תשלום scripts.run בדרך כלל כרוך בשליחת נתונים ל-Apps Script כפרמטרים של פונקציה והחזרת נתונים כפונקציה, מחזירה ערכים. ה-API יכול רק לקבל ולהחזיר מהסוגים הבסיסיים: מחרוזות, מערכים, אובייקטים, מספרים ובוליאני. האלה דומים לסוגים הבסיסיים ב-JavaScript. התוצאות מורכבות יותר אובייקטים של Apps Script, כמו Document או גיליון או מפרויקט הסקריפט על ידי ה-API.

כשאפליקציית הקריאה נכתבת בשפה בעלת טיפוס חזק, כמו ב-Java, היא מעבירה פרמטרים כרשימה או כמערך של אובייקטים גנריים שתואמים לסוגים הבסיסיים האלו. במקרים רבים אפשר להשתמש מקלידים המרות באופן אוטומטי. לדוגמה, פונקציה שלוקחת מספר אפשר לתת לפרמטר את האובייקט של Java Double או Integer או Long בתור אובייקט ללא טיפול נוסף.

כשה-API מחזיר את התגובה של הפונקציה, לעיתים קרובות צריך להפעיל Cast של מוחזר ערך לסוג הנכון לפני שאפשר להשתמש בו. הנה כמה דוגמאות דוגמאות מבוססות 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, חייבים לשנות את פרויקט הסקריפט כדי להשתמש בו.

שלב 2: פריסת הסקריפט כקובץ הפעלה של API

פותחים את פרויקט Apps Script עם הפונקציות שבהן רוצים להשתמש.
בצד שמאל למעלה, לוחצים על פריסה > פריסה חדשה.
בתיבת הדו-שיח שנפתחת, לוחצים על הסמל להפעלת סוגי פריסה > API להפעלה.
בקטע 'למי יש גישה' בתפריט הנפתח, בוחרים את המשתמשים מורשים לקרוא לפונקציות של הסקריפט באמצעות Apps Script API.
לוחצים על Deploy (פריסה).

שלב 3: מגדירים את אפליקציית הקריאה

אפליקציית הקריאה צריכה להפעיל את Apps Script API וליצור OAuth חשובים לפני שאפשר להשתמש בו. צריכה להיות לכם גישה לפרויקט Cloud לשם כך.

מגדירים את הפרויקט ב-Cloud שבו משתמשים האפליקציה והסקריפט. כדי לעשות זאת:
פותחים את פרויקט הסקריפט ולוחצים על סקירה כללית בצד ימין.
בקטע היקפי ההרשאות של Project OAuth, מתעדים את כל היקפי ההרשאות של נדרש סקריפט.
בקוד של האפליקציה לקריאה, צריך ליצור סקריפט גישה ל-OAuth לקריאה ל-API. זהו לא אסימון שה-API עצמו משתמש בו, אלא אסימון נדרש בעת הביצוע של הסקריפט. צריך ליצור אותו באמצעות מזהה הלקוח של פרויקט ב-Cloud והיקפי הסקריפט שתיעדתם.

ספריות הלקוח של Google יכולות מאוד יעזרו לבנות את האסימון הזה ולטפל ב-OAuth עבור האפליקציה, בדרך כלל מאפשרות ליצור במקום זאת פרטי כניסה ברמה גבוהה יותר אובייקט באמצעות היקפי הסקריפט. לצפייה דוגמאות למדריך למתחילים של Apps Script API של בניית אובייקט של פרטי כניסה מתוך רשימה של היקפים.

שלב 4: מגישים בקשה של `script.run`

אחרי שאפליקציית השיחות הוגדרה, אפשר לבצע את הפעולות הבאות: scripts.run שיחות. כל API כולל את השלבים הבאים:

יצירה של בקשת API באמצעות מזהה הסקריפט, שם הפונקציה וכל דרישה אחרת .
מגדירים את scripts.run וכוללים את הסקריפט OAuth שיצרתם הכותרת (אם משתמשים בבקשת POST בסיסית) או באובייקט פרטי כניסה. שיצרתם באמצעות היקפים של הסקריפטים.
צריך לאפשר לסקריפט לסיים את ביצוע ההפעלה. סקריפטים יכולים לפעול עד שש דקות של זמן ביצוע, כך שהאפליקציה שלכם צריכה לאפשר זאת.
בסיום, פונקציית הסקריפט עשויה להחזיר ערך, וה-API מועבר חזרה לאפליקציה אם הערך הוא מסוג נתמך.

דוגמאות לקריאות ל-API של script.run שלמטה.

אזהרה: אם התוקף של אסימון הגישה פג בזמן בקשת API script.run מבצעת פונקציית סקריפט, וייתכן שהיא התוצאה תהיה Authorization is required to perform that action שגיאה. כדי למנוע זאת, צריך לרענן את אסימון הגישה לפני שמבצעים את הקריאה ל-API אם משך הזמן של expires_in קצר מהמקסימום סקריפט זמן ריצה לחשבון (6 דקות ברוב המקרים).

כדי לרענן את אסימון הגישה, אפשר להוסיף את קטע הקוד הבא לפני בקשת API של script.run:

if (credential.getExpiresInSeconds() <= 360) {
  credential.refreshToken();
}

דוגמאות לבקשות 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;
}target.js

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);
  }
}Execute.java

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;
  }
}
index.js

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;
  }
}index.js

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()execute.py

מגבלות

ל-Apps Script API יש כמה מגבלות:

פרויקט משותף ב-Cloud. לסקריפט שנשלח קריאה היא צריכה לשתף פרויקט בענן. הפרויקט ב-Cloud חייב להיות standard Cloud project; פרויקטי ברירת מחדל שנוצרו לפרויקטים של Apps Script אינם מספיקים. פרויקט רגיל ב-Cloud יכול להיות פרויקט חדש או קיים.
פרמטרים בסיסיים וסוגי החזרה. ה-API לא יכול להעביר או להחזיר אובייקטים ספציפיים ל-Apps Script (כמו מסמכים, Blobs, יומנים, קבצים ב-Drive וכו') אל תרגום מכונה. רק סוגים בסיסיים, כמו מחרוזות, מערכים, אובייקטים, מספרים ו אפשר להעביר ולהחזיר ערך בוליאני.
היקפי הרשאות OAuth ה-API יכול להפעיל רק סקריפטים שמכילים לפחות היקף נדרש אחד. כלומר, לא ניתן להשתמש ב-API כדי לקרוא לסקריפט שאינם מחייבים הרשאה של שירות אחד או יותר.
אין טריגרים.ל-API אין אפשרות ליצור Apps Script הטריגרים.