משימת Apps Script

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

לפני שמתחילים

לפני שמשתמשים במשימת Apps Script, צריך לבצע את השלבים הבאים:

הפעלת Apps Script API

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

יצירת מזהה לקוח ב-OAuth 2.0

אם יש לכם מזהה לקוח OAuth 2.0, אתם יכולים לדלג על השלב הזה ולעבור אל הגדרת פרופיל אימות.

מידע על יצירת מזהה לקוח OAuth חדש זמין במאמר יצירת מזהה לקוח OAuth.

הגדרת פרופיל אימות

הכלי Application Integration משתמש בפרופיל האימות כדי להתחבר ל-Google Cloud לצורך פריסה והרצה של פרויקט Apps Script. כדי להגדיר פרופיל אימות:

הוספת משימה של Apps Script

  1. נכנסים לדף Application Integration במסוף Google Cloud .

    מעבר אל Application Integration

  2. בתפריט הניווט, לוחצים על Integrations (שילובים).

    מוצג הדף Integrations (שילובים) עם רשימה של כל השילובים שזמינים בפרויקט בענן של Google.

  3. בוחרים שילוב קיים או לוחצים על יצירת שילוב כדי ליצור שילוב חדש.

    אם יוצרים שילוב חדש:

    1. מזינים שם ותיאור בחלונית יצירת שילוב.
    2. בוחרים אזור לשילוב.
    3. בוחרים חשבון שירות לאינטגרציה. אפשר לשנות או לעדכן את פרטי חשבון השירות של שילוב בכל שלב מחלונית סיכום השילוב בסרגל הכלים של השילוב.
    4. לוחצים על יצירה. השילוב החדש שנוצר ייפתח בכלי השילובים.

  4. בסרגל הניווט של כלי העריכה של השילוב, לוחצים על משימות כדי לראות את רשימת המשימות והמחברים הזמינים.
  5. לוחצים על הרכיב Apps Script וממקמים אותו בכלי לעריכת שילובים.

יצירת פרופיל אימות

  1. לוחצים על הרכיב Apps Script (סקריפט של Apps) בכלי העיצוב כדי להציג את חלונית הגדרת המשימות של Apps Script.
  2. בחלונית הגדרת המשימה של Apps Script, לוחצים על + פרופיל אימות חדש.
  3. בתיבת הדו-שיח פרופיל אימות, מזינים שם ותיאור לפרופיל ומגדירים את המאפיינים הבאים:
    • סוג האימות: בוחרים באפשרות קוד הרשאה OAuth 2.0.
    • נקודת קצה לאימות: מזינים https://accounts.google.com/o/oauth2/auth
    • נקודת הקצה של הטוקן: מזינים https://oauth2.googleapis.com/token
    • מזהה לקוח: מזינים את מזהה הלקוח.

      מזהה הלקוח זמין בלוח הבקרה של הפרויקט בענן ב-Google Cloud בקטע Credentials > OAuth 2.0 Client IDs (פרטי כניסה > מזהי לקוח OAuth 2.0).

    • ‫Secret: מזינים את סוד הלקוח

      סוד הלקוח זמין בלוח הבקרה של פרויקט בענן ב-Google Cloud בקטע Credentials > OAuth 2.0 Client IDs.

    • היקפים: מזינים את הערכים הבאים:

      https://www.googleapis.com/auth/script.projects https://www.googleapis.com/auth/script.deployments https://www.googleapis.com/auth/script.deployments.readonly https://www.googleapis.com/auth/drive.scripts https://www.googleapis.com/auth/drive https://www.googleapis.com/auth/script.external_request https://www.googleapis.com/auth/userinfo.email

      הערה: אפשר להפריד בין כמה היקפי הרשאות באמצעות רווח אחד (" ").

  4. לוחצים על יצירת אסימון גישה ושמירה.

    תועברו למסך הרשאה. מתחברים ומאשרים את ההרשאות שמופיעות במסך כדי ליצור את אסימון הגישה. אם יצירת אסימון הגישה תצליח, פרופיל האימות יישמר ותוכלו להמשיך לערוך את השילוב.

הגדרת המשימה של Apps Script

כדי להגדיר פרויקט של Apps Script במשימה Apps Script, מבצעים את השלבים הבאים:

  1. בחלונית הגדרת המשימה, לוחצים על Configure Apps Script Project (הגדרת פרויקט Apps Script).

    מופיעה תיבת הדו-שיח Apps Script Configuration (הגדרות של Apps Script).

  2. אפשר לקשר לפרויקט קיים של Apps Script או ליצור פרויקט חדש של Apps Script.

    הגדרת פרויקט Apps Script משייכת את פרויקט Apps Script לשילוב שלכם ב-Application Integration.

  3. לוחצים על 'שמירה'.
  4. לוחצים על פתיחת פרויקט Apps Script.

    ב-Apps Script Editor, אפשר לראות את הקבצים הבאים:

    • ‫Run.gs: מכיל את קוד ההפעלה. כותבים את הסקריפט בתוך הפונקציה run. הפונקציה הזו מופעלת כשמשימת Apps Script מורצת. בסקריפט, אפשר להשתמש במשתנים שהוגדרו ברמת השילוב. מידע על השימוש במשתני האינטגרציה זמין במאמר שימוש במשתני אינטגרציה.
    • ‫Main.gs: מכיל את קוד האתחול להפעלת Apps Script מהשילוב. אין לערוך או לשנות את הקובץ הזה.
    • ‫Test.gs: מכיל את קוד ההפעלה להרצת בדיקות. אפשר לכתוב את התסריט בתוך הפונקציה testRun כדי לבדוק את התסריט.

    חשוב לוודא שפריסת הפרויקט היא בפורמט אפליקציות אינטרנט. מידע נוסף על מצבי הפריסה השונים זמין במאמר בנושא יצירה וניהול של פריסות.

גישה למשתני שילוב

משימת Apps Script משתמשת בספרייה AppsScriptTask, שמאפשרת לכם להשתמש במשתני שילוב בסקריפט. הספרייה AppsScriptTask מיובאת אוטומטית וזמינה לשימוש בפונקציה run.

כדי לגשת למשתנה שילוב ב-Apps Script, צריך להעביר את המשתנה בצורה של פרמטרים של משימה למשימת Apps Script. פרמטרי המשימה הם צמדי מפתח-ערך, שבהם Key הוא שם המשתנה במשימת AppsScript ו-Value הוא שם משתנה השילוב התואם. אפשר להוסיף פרמטר אחד או יותר של משימה בקטע Task Parameters (פרמטרים של משימה) בחלונית ההגדרות של המשימה.

לדוגמה, אם יש לכם משתנה שילוב בשם Product שבו אתם רוצים להשתמש ב-Apps Script, אתם יכולים להגדיר את Key כ-ProductKey ואת הערך כ-Product. ב-Apps Script, אפשר להשתמש ב-AppsScriptTask.getTaskParameter('ProductKey') כדי לקרוא את המשתנה Product.

ספריית AppsScriptTask מספקת את השיטות הבאות לגישה למשתני שילוב:

שם הפונקציה תיאור Usage

setIntegrationVariable

 מגדירה את הערך שצוין למשתנה.

תחביר: setIntegrationVariable(value,value)

לדוגמה: 

// Write to an Integer variable
AppsScriptTask.setIntegrationVariable('EmployeeIDKey','456');

getTaskParameter

 קבלת הערך של משתנה.

תחביר: getTaskParameter(value)

לדוגמה: 

// Read an integration variable
AppsScriptTask.getTaskParameter('EmployeeIDKey');

כדי לראות את כל הפונקציות שזמינות בספרייה AppsScriptTask, מעבירים את הסמן מעל האפשרות בתפריט AppsScriptTask בכלי לעריכת סקריפטים של Apps Script, לוחצים על סמל האפשרויות הנוספות > פתיחה בכרטיסייה חדשה.

בדיקת Apps Script

לפני שמפרסמים את השילוב, אפשר לבדוק את הסקריפט באמצעות הפונקציה testRun שזמינה בקובץ Test.gs. כותבים את קוד הבדיקה בפונקציה testRun באמצעות הספרייה AppsScriptTaskTest. הספרייה הזו מאפשרת להריץ תרחישי בדיקה מבוססי-טענות, והיא מיובאת אוטומטית לשימוש בפונקציה testRun.

כדי לראות את כל הפונקציות שזמינות בספרייה AppsScriptTaskTest, מעבירים את הסמן מעל האפשרות בתפריט AppsScriptTaskTest בכלי לעריכת סקריפטים של Apps Script, לוחצים על סמל האפשרויות הנוספות > פתיחה בכרטיסייה חדשה.

בדוגמה הבאה מוצג שימוש בפונקציות של הספרייה AppsScriptTaskTest. 

function testRun(){

  // Create a new request
  let req = AppsScriptTaskTest.createNewTestRequest('myCustomTest');

  // Add a task parameter that references an integration variable with the value 5
  AppsScriptTaskTest.setIntegrationVariableAndCreateReference(req, 'input', '$input$', 5);

  // Add a task parameter that references an integration variable
  AppsScriptTaskTest.createReference(req, 'output', '$output$');

  // Run the task(assuming the task increments the input by 1) and get the response
  let res = AppsScriptTaskTest.runTest(req, executeScript);

  // Check the response for the expected integration variable and its corresponding values
  AppsScriptTaskTest.containsIntegrationVariable(res, 'output', true);
  AppsScriptTaskTest.containsIntegrationVariable(res, 'someOtherIntegrtionVariable', false);
  AppsScriptTaskTest.containsIntegrationVariableWithValue(res, 'output', 6);
}

בדוגמה הבאה אפשר לראות איך לגשת למשתני JSON ולמשתני מערך בשיטה testRun: 

function testRun(){

  // Create a new request
  let req = AppsScriptTaskTest.createNewTestRequest('json-test');

  // Add a task parameter that references a JSON integration variable
  AppsScriptTaskTest.setIntegrationVariableAndCreateReference(req, "emp", "employee", {name:"snape", age:35});

  // Add a task parameter that references an array integration variable
  AppsScriptTaskTest.setIntegrationVariableAndCreateReference(req, "arr", "array", ["A", "B", "C"]);


  // Run the task and get the response
  // Assume that the run method increases the age of the employee by 5 and appends a new element in the array
  let res = AppsScriptTaskTest.runTest(req, executeScript);

  // Check the response for the expected integration variable and its corresponding values
  AppsScriptTaskTest.containsIntegrationVariableWithValue(res, "employee", {name:"snape", age:40});
  AppsScriptTaskTest.containsIntegrationVariable(res, "array", true);
  AppsScriptTaskTest.containsIntegrationVariableWithValue(res, "array", ["A", "B", "C", "D"]);
}

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

שיטות מומלצות

לא מומלץ להשתמש במשימה של Apps Script אם נדרש זמן אחזור של פחות משנייה עד שתי שניות למשימה בשילוב.

בנוסף, כדי לצמצם את צווארי הבקבוק בביצועים, מומלץ לקודד את כל הלוגיקה במשימה אחת של Apps Script, במקום לשרשר כמה משימות של Apps Script.

מידע על מכסות השימוש שחלות על המשימה Apps Script מופיע במאמר מכסות שימוש.

לתשומת ליבכם

כשכוללים את משימת Apps Script בעיצוב השילוב, צריך לקחת בחשבון את מגבלות המערכת הבאות:

  • מספר הפריסות הפעילות המקסימלי ל-Apps Script: ‏ 50
  • שאילתות לשנייה (QPS) לקובצי הפעלה של API: ‏ 5,000 לדקה
  • שאילתות לשנייה (QPS) לפריסות של אפליקציות אינטרנט: 5,000 לדקה
  • זמן האחזור של קובצי API שניתנים להרצה: 1.5 שניות
  • זמן האחזור של אפליקציית האינטרנט: 2.5 שניות
  • הגודל המצטבר המקסימלי של כל משתני השילוב ב-Apps Script: ‏ 15MB

אסטרטגיה לטיפול בשגיאות

אסטרטגיה לטיפול בשגיאות במשימה מציינת את הפעולה שיש לבצע אם המשימה נכשלת בגלל שגיאה זמנית. מידע על שימוש באסטרטגיה לטיפול בשגיאות ועל סוגים שונים של אסטרטגיות לטיפול בשגיאות זמין במאמר אסטרטגיות לטיפול בשגיאות.

החרגות בהסכם רמת השירות

למשימה של Apps Script יש תלות במוצר Google Apps Script. מכיוון שהתלות הזו היא חיצונית ל-Application Integration, כל ההרצות של שילובי active שנכשלות בגלל הכשל במשימת Apps Script, לא נכללות בתנאים ובהגבלות של הסכם רמת השירות (SLA) של Application Integration.

מכסות ומגבלות

מידע על מכסות ומגבלות זמין במאמר מכסות ומגבלות.

המאמרים הבאים