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). כדי לאחזר את המדינה, יש להתקשר אל 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" }