Method: scripts.run

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

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

השגיאה 403, PERMISSION_DENIED: The caller does not have permission מציינת שהפרויקט ב-Cloud Platform שמשמש לאישור הבקשה לא זהה לפרויקט שבו הסקריפט משתמש.

בקשת HTTP

POST https://script.googleapis.com/v1/scripts/{scriptId}:run

בכתובת ה-URL נעשה שימוש בתחביר המרת קידוד של gRPC.

פרמטרים של נתיב

פרמטרים
scriptId

string

מזהה הסקריפט שיש לבצע. מזהה הסקריפט מופיע בדף הגדרות הפרויקט בקטע 'מזהים'.

גוף הבקשה

גוף הבקשה מכיל נתונים במבנה הבא:

ייצוג JSON 
{
  "function": string,
  "parameters": [
    value
  ],
  "sessionState": string,
  "devMode": boolean
}
שדות
function

string

שם הפונקציה שצריך להפעיל בסקריפט הנתון. השם לא כולל סוגריים או פרמטרים. היא יכולה להפנות לפונקציה בספרייה כלולה כמו Library.libFunction1.
parameters[]

value (Value format)

הפרמטרים שיועברו לפונקציה שמתבצעת. סוג האובייקט של כל פרמטר צריך להיות תואם לסוג המצופה ב-Apps Script. הפרמטרים לא יכולים להיות סוגי אובייקטים ספציפיים ל-Apps Script (כמו Document או Calendar); הם יכולים להיות רק סוגים ראשוניים כמו string, number, array, object או boolean. זה שינוי אופציונלי.
sessionState

string

הוצא משימוש. לשימוש עם תוספים ל-Android בלבד. מזהה שמייצג את הסשן הנוכחי של המשתמש באפליקציה ל-Android ל-Google Docs או ל-Sheets, נכלל כנתונים נוספים ב-Intent שמפעיל את התוסף. כשתוסף ל-Android מופעל עם מצב סשן, הוא מקבל את ההרשאות של סקריפט כבול, כלומר הוא יכול לגשת למידע כמו מיקום הסמן הנוכחי של המשתמש (ב-Docs) או התא שנבחר (ב-Sheets). כדי לאחזר את המדינה (State) צריך להתקשר אל Intent.getStringExtra("com.google.android.apps.docs.addons.SessionState"). זה שינוי אופציונלי.
devMode

boolean

אם true והמשתמש הוא הבעלים של הסקריפט, הסקריפט ירוץ בגרסה האחרונה שנשמרה ולא בגרסה שנפרסה לשימוש ב-Apps Script API. אופציונלי; ברירת המחדל היא false.

גוף התשובה

אם הפעולה בוצעה ללא שגיאות, גוף התגובה יכיל נתונים במבנה הבא:

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

אחרי שהביצוע מתחיל, יכולות להיות לו אחת מארבע תוצאות:

  • אם פונקציית הסקריפט מוחזרת בהצלחה, השדה response מכיל אובייקט ExecutionResponse עם הערך המוחזר של הפונקציה בשדה result של האובייקט.
  • אם פונקציית הסקריפט (או ה-Apps Script עצמה) גורמת לחריגה, השדה error מכיל אובייקט Status. השדה details של האובייקט Status מכיל מערך עם אובייקט ExecutionError יחיד שמספק מידע על אופי השגיאה.
  • אם הביצוע עדיין לא הושלם, השדה done יהיה false והשדות response ו-error לא מופיעים.
  • אם הקריאה של run עצמה נכשלת (לדוגמה, בגלל בקשה לא תקינה או שגיאת הרשאה), ה-method מחזירה קוד תגובת HTTP בטווח 4XX עם פורמט שונה לגוף התשובה. ספריות לקוח ממירות באופן אוטומטי תגובת 4XX למחלקה חריגה.

ייצוג JSON 
{
  "done": boolean,

  // Union field result can be only one of the following:
  "error": {
    object (Status)
  },
  "response": {
    "@type": string,
    field1: ...,
    ...
  }
  // End of list of possible types for union field result.
}
שדות
done

boolean

השדה הזה מציין אם הפעלת הסקריפט הושלמה. כשביצוע הושלם, יש שדה response מאוכלס שמכיל את הפונקציה ExecutionResponse מהפונקציה שהופעלה.
שדה איחוד result. תוצאת הפעולה, שיכולה להיות error או response חוקית. אם done == false, לא מוגדר error וגם response. אם done == true, אפשר להגדיר בדיוק אחד מהערכים error או response. יכול להיות ששירותים מסוימים לא יספקו את התוצאה. result יכול להיות רק אחת מהאפשרויות הבאות:
error

object (Status)

אם הקריאה ל-run מצליחה, אבל פונקציית הסקריפט (או ה-Apps Script עצמה) גורמת לחריגה, השדה הזה מכיל אובייקט Status. השדה details של האובייקט Status מכיל מערך עם אובייקט ExecutionError יחיד שמספק מידע על אופי השגיאה.
response

object

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

אובייקט שמכיל שדות מסוג שרירותי. שדה נוסף "@type" מכיל URI המזהה את הסוג. לדוגמה: { "id": 1234, "@type": "types.example.com/standard/id" }.

היקפי הרשאות

נדרש אחד מהיקפי ההרשאות הבאים של OAuth:

  • https://apps-apis.google.com/a/feeds
  • https://apps-apis.google.com/a/feeds/alias/
  • https://apps-apis.google.com/a/feeds/groups/
  • https://mail.google.com/
  • https://sites.google.com/feeds
  • https://www.google.com/calendar/feeds
  • https://www.google.com/m8/feeds
  • https://www.googleapis.com/auth/admin.directory.group
  • https://www.googleapis.com/auth/admin.directory.user
  • https://www.googleapis.com/auth/documents
  • https://www.googleapis.com/auth/documents.currentonly
  • https://www.googleapis.com/auth/drive
  • https://www.googleapis.com/auth/dynamiccreatives
  • https://www.googleapis.com/auth/forms
  • https://www.googleapis.com/auth/forms.currentonly
  • https://www.googleapis.com/auth/groups
  • https://www.googleapis.com/auth/script.cpanel
  • https://www.googleapis.com/auth/script.external_request
  • https://www.googleapis.com/auth/script.scriptapp
  • https://www.googleapis.com/auth/script.send_mail
  • https://www.googleapis.com/auth/script.storage
  • https://www.googleapis.com/auth/script.webapp.deploy
  • https://www.googleapis.com/auth/spreadsheets
  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/sqlservice
  • https://www.googleapis.com/auth/userinfo.email

למידע נוסף, קראו את המאמר סקירה כללית של OAuth 2.0.

סטטוס

אם קריאה ל-run מצליחה אבל פונקציית הסקריפט (או הסקריפט של Apps Script גורמת לחריגה, השדה error בגוף התשובה יכיל את אובייקט ה-Status הזה.

ייצוג JSON 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
שדות
code

integer

קוד הסטטוס. ב-API הזה, הערך הזה יכול להיות:

  • 10, שמציין שגיאת SCRIPT_TIMEOUT,
  • 3, שמציין שגיאת INVALID_ARGUMENT, או
  • 1, מציין הפעלה של CANCELLED.
message

string

הודעת שגיאה באנגלית שמיועדת למפתחים. כל הודעות השגיאה שמוצגות למשתמשים מותאמות לשוק המקומי ונשלחות בשדה details או מותאמות לשוק המקומי על ידי הלקוח.
details[]

object

מערך שמכיל אובייקט ExecutionError יחיד שמספק מידע על אופי השגיאה.

אובייקט שמכיל שדות מסוג שרירותי. שדה נוסף "@type" מכיל URI המזהה את הסוג. לדוגמה: { "id": 1234, "@type": "types.example.com/standard/id" }.