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

מזהה הסקריפט של הסקריפט שיש להפעיל. מאתרים את מזהה הסקריפט בדף Project settings (הגדרות הפרויקט) בקטע ID (מזהים).

גוף הבקשה

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

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