Method: scripts.run

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

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

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

בקשת HTTP

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

כתובת ה-URL כתובה בתחביר של gRPC Transcoding.

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

פרמטרים
deploymentId

string

מזהה הפריסה של פריסת ה-API הניתן להרצה. מזהים את מזהה הפריסה בקטע פריסה > ניהול פריסות בעורך הסקריפטים.

גוף הבקשה

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

ייצוג ב-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 בלבד. מזהה שמייצג את הסשן הנוכחי של המשתמש באפליקציית Google Docs או Sheets ל-Android, שכלול כנתונים נוספים ב-Intent שמפעיל את התוסף. כשמריצים תוסף ל-Android עם מצב סשן, הוא מקבל את ההרשאות של סקריפט מקשר – כלומר, הוא יכול לגשת למידע כמו מיקום הסמן הנוכחי של המשתמש (ב-Docs) או התא שנבחר (ב-Sheets). כדי לקבל את המצב, אפשר להתקשר אל 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 עצמה נכשלת (לדוגמה, בגלל בקשה בפורמט שגוי או שגיאת הרשאה), השיטה מחזירה קוד תגובה של 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" }.